$Header: /raid/cvsroot/rt/README,v 1.25 1999/10/06 21:57:00 jesse Exp $

RT is (c) 1996-1999 by Jesse Vincent <jesse@fsck.com>
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.

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

Some code for RT has been derived from Remy Evard's req package.

All of these works are distributed under the GPL
 

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

o   Perl5.x ( http://www.perl.com ) -- free
	
	RT is written almost entirely in perl.

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

o   GNU Make ( http://www.gnu.org ) -- free

	I know for sure that GNU Make supports the conditionals syntax RT's
	Makefile uses. I can't be sure about anything else.  If you don't have 
	GNU Make, but feel reasonably comfortable with Makefiles, you probably
	can get by without it.

o   Msql-Mysql-modules ( ftp://ftp.mysql.com/pub/mysql/Contrib ) -- free

	When installing Msql-Mysql-modules, it is imperative that you say yes 
	when asked "Do you want to install the MysqlPerl emulation?"  Please 
	note that Msql-Mysql-modules requires DBD to be installed to function.
	See the Msql-Mysql-modules documentation for more information.

o   CGI.pm ( http://www.perl.com ) -- free
	
	CGI.pm and CGI::Cookie are used for our basic Form and Cookie processing
	We recommend that you use at least 2.53 as we know that version works.

o   Digest::MD5 ( http://www.perl.com ) -- free
	
	Digest::MD5 is a perl module used for generating MD5 hashes 
	of files or strings, in this case, the password hashes used by 
	the Web interface. It is required for web authentication to work.


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
--------------------

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   Read the documentation in /tmp/rt/docs. All of it.

3   Create a user rt with primary group rt

4   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.

5a  FOR A NEW INSTALLATION: (If you don't  have an "rt" database in Mysql)

        As root, type:
		 make install	(replace "make" with the local name for 
				 GNU Make, if you need to)


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

        As root, type: 
		make upgrade     (replace "make" with the local name for 
				  GNU Make, if you need to)

	This will build new RT wrappers, config files and libraries without
	overwriting your RT database.

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

7   Using rtadmin, or admin-webrt.cgi 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.
	
	Commandline instructions:

            [root@host bin]# ./rtadmin queue -create <queue name>
            [root@host bin]# ./rtadmin user  -create <user name>

	Web instructions:
	
	    Click on "Create a user called" (after filling out the text input 
					     to the right of the button)
	
	    Click on "Create a queue called"  (after filling out the text input 
                                             to the right of the button)


    NOTE: root's password for the web interface is "wordpass" 
    (without the quotes.)  Not changing this is a SECURITY risk  
 
8   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 Apache
httpd.  Additionally, you'll need a web browser that supports unless you've 
enabled "external" authentication above.

Apache 
	To get Apache working, you'll want to add two lines to your httpd.conf:

	Alias /webrt/ "/path/to/rt/lib/images/"
	ScriptAlias /rt/ "/path/to/rt/bin/cgi/"

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

	If you'd rather use Apache's mod_auth_mysql, check out 
	"contrib/mod_auth_mysql.README"

CERN:
	It just works. 
	
	You'' want to tell your server that /webrt/ is an alias for 
	"/path/to/rt/lib/images/" and that
	/rt is a Script Alias for "/path/to/rt/bin/cgi/"

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

Netscape:
	You're on your own for configuring it, but it should work just fine.


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:
jesse@fsck.com

If you're interested in hacking on rt, you;ll want to subscribe to 
rt-devel@lists.fsck.com.  Subscribe to it with instructions similar to those 
above.

RT WEBSITE
----------

For current information about RT, check out the RT website at 
http://www.fsck.com/projects/rt  You'll find screenshots, a pointer
to the current version of rt, contributed patches and lots of other great
stuff.


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, Serge Zhuk,
John Lengeling, Elmar Knipp, Gerald Abshez, Dave Hull, Dave Schenet,
Dave Walton, Jan Okrouhly, Tobias Brox, Lamont Lucas, Charlie Brady,
Robin Shostack, Eric Mumpower, Jerrod Weisman and Adam Hammer 
have all contributed bug reports, code or ideas that have helped RT along.  

Arepa, Inc, Utopia Inc, Wesleyan University and The Leftbank Operation 
have paid me to update RT and release it to the public.  Without their 
support RT would not exist.  If I've left you out, please drop me a line
....it wasn't intentional. 
 


        Enjoy

        Jesse Vincent
	jesse@fsck.com
