$Header: /usr/local/cvsroot/rt/README,v 1.13 1998/09/08 07:18:55 jesse Exp $

RT is (c) 1996,1997 by Jesse Vincent <jrvincent@wesleyan.edu>

RT is distributed under the GNU Public License.
If you don't have a copy of the GPL, you've been living in a cave,
but one should be included in this distribution.

WARNING:  RT IS BETA SOFTWARE.  VERSIONS OF IT HAVE BEEN RUNNING AT
SEVERAL SITES FOR OVER A YEAR, HOWEVER I MAKE NO PROMISES AS TO ITS
STABILITY.

Development of RT has been sponsored in part by Utopia Inc, by The
Leftbank Operation and by Wesleyan University.

Some code for RT has been derived from Remy Evard's req package.
Some code for RT has been derived from Reuven Lerner's form-mail.pl

All of these works are distributed under the GPL
 

REQUIRED PACKAGES:
------------------

o   Perl5.x ( http://www.perl.com ) -- free

o   MySQL 3.20.x, 3.21.x or 3.22.x ( http://www.tcx.se ) -- free
        
	FTP mysql from www.tcx.se and follow the INSTALL instructions
        contained therein

o   MysqlPerl ( http://www.tcx.se ) -- free

	Mysqlperl is included in the MySQL distribution


INSTALL INSTRUCTIONS
--------------------

With all of the above installed, it's time to do the rather easy job
of installing RT.  Choose a directory in which you wish to install RT. 
For the sake of simplicity, we use /usr/local/rt in our example.


GENERAL INSTALLATION
--------------------

0   Read README.FIRST before you touch ANYTHING

1   Unpack this distribution SOMWHERE OTHER THAN where you want to install RT

        Granted, you've already got it open. To do this cleanly:

        	tar xzvf rt.tar.gz -C /tmp

2   Create a user rt with primary group rt

3   Check over /tmp/rt/Makefile

	There are many variables you NEED to customize for your site.
	Even if you are just upgrading, you must set ALL variables.

4a  FOR A NEW INSTALLATION: (If you don't have RT requests you want to keep)

        As ROOT: make install

4b  FOR UPGRADING: (From any RT installation NEWER than RT 0.9.2)

        As ROOT: make upgrade
	This will build new RT wrappers, config files and libraries without
	overwriting your RT database.

5   Configure the email and web gateways, as described below. 

6   Using rtadmin, add a RT user for yourself.  Add an RT queue.   
    This must be done as root, as the only user with acls to access rt is root.

            [root@host bin]# ./rtadmin queue -create general
            [root@host bin]# ./rtadmin user  -create joebob

    NOTE: root's password for the web interface is "wordpass" 
    (without the quotes.)  Not changing this is a SECURITY risk  
 
7   Edit templates to your liking. Templates are found in
    rt/etc/templates/queues/<queue-name>



SETTING UP THE MAIL GATEWAY 
---------------------------

An alias for the initial queue will need to be made in either your
global mail aliases file (if you are using NIS) or locally on your
machine.
 
Add the following line to /etc/aliases (or your local equivalent) :

        rt:     |"/path/to/lrt/bin/rt-mailgate general correspond"
                                                    |          |
                                   <<queue-name>----/          |
                                                               |
                <<correspond or comment depending on whether   |
                 the mail shoud be resent to the requestor>---/
		 "action" here will make this address only
		  parse actions in the message without 
		  recording the message as a transaction
		  of its own"

The RT Mail Gateway can be used to perform actions on requests.
For an explanation of how to use the Mail Gateway, send a message to
any RT alias with the command %RT HELP on a line by itself.     

You'll need an alias like the following for action requests:

        rt-action:      |"/path/to/rt/bin/rt-mailgate general action"
	

THE WEB UI
----------

If you don't already have an http daemon set up, you will probably want
to start one to handle the CGI interface.  For now, I'd recommend the CERN
httpd.  Apache with a minor authentication patch works quite well, too.

To get apache to pass authentication headers to cgi scripts, remove the 
following two lines from util_script.c:

-       else if (!strcasecmp (hdrs[i].key, "Authorization"))
-           continue;

(These lines can be found at approximately line 180 in apache 1.2.5)

NOTE: Netscape's servers don't allow nph-cgi scripts to perform their own 
authentication so they don't really work with WebRT. Besides, CERN and Apache 
are free.

A sample config file for CERN httpd ( http://www.w3.org )
is in rt/etc/httpd/cern.   Invoke it with the following command line:

         /path/to/cern/httpd -r /path/to/rt/etc/httpd/cern/httpd.conf

o     you'll find rt-admin at http://host:8080/rt/nph-admin-webrt.cgi
o     you'll find rt at http://host:8080/rt/nph-webrt.cgi and
o                       http://host:8080/rt/nph-webrt.cgi/frames

 

THE CLI
-------

        Binaries for the CLI are located in /usr/local/rt/bin
        You've got:

                "rtq" (display a request queue)
                "rt" (manipulate a request)
                "rtadmin" (modify queues, users and acls)

        All three of these programs take --help as an option.


RT-USERS MAILINGLIST
--------------------


By now, you've probably hit at least one sticking point. you probably
want to join the RT-users mailinglist.  Send a message to:

         rt-users-request@lists.fsck.com 

With the body of the message consisting of only the word:

        subscribe

Address questions to the mailinglist.  If you feel your questions are
best not asked publically, send them to me personally at:
jrvincent@wesleyan.edu.

NOTE THAT THE LIST HAS MOVED



CREDITS
-------

A lot of people are responsible for making RT a better program.  Many
thanks to Lauren Burka, who originally tasked me with writing this beast.
She forced me to use a database backend.  I've thanked her for it every
day since.  Rich West rewrote this readme and did some UI hacking.  Adam
Hirsch, Kit Kraysha, Robin Garner, Jens Glaser, John Adams, Trey Belew, 
Sean Dague, Nathan Mehl, Kee Hinckley, Rich West, Dale Bewley and Serge Zhuk 
have all contributed bug reports, code  or ideas that have helped RT along.  
If I've left you out, please drop me a line....it wasn't intentional. 
 
        Enjoy

        Jesse Vincent
        jrvincent@wesleyan.edu

