$Header: /raid/cvsroot/rt/README,v 1.36 2001/01/08 19:04:54 jesse Exp $ RT is (c) 1996-2000 by Jesse Vincent 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 Into Networks, Utopia Inc, Funcom Online, 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 ) -- sort of free FTP mysql from www.mysql.com and follow the INSTALL instructions contained therein. RT 1.0.x cannot be used with other DBMS'es. 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. If RT complains that it's missing CGI::Vars after installation, your CGI.pm is probably too old. 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. RECOMMENDED PACKAGES -------------------- o An MTA (Mail Transfer Agent), i.e. sendmail -- free. RT 1.0 needs to pipe the mail to some program that can send mail, i.e. /usr/lib/sendmail. The installation guide below also assumes that the server RT is running on is capable of _receiving_ mail. It is possible to get it running with a remote mailserver, using fetchmail to fetch incoming messages from the mailserver, or by allowing the mailserver to execute RT remotely with ssh or by having the data directory (transactions) NFS accessable and letting RT access the database remotely. 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 Make sure you've installed the perl modules that RT depends on. perl /tmp/rt/bin/testdeps.pl -warn will tell you if it notices anything out of place. perl /tmp/rt/bin/testdeps.pl -fix will fix things up if you've got CPAN installed. 4 Create a user rt with primary group rt 5 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. 6a 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) 6b 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. 7 Configure the email and web gateways, as described below. 8 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 [root@host bin]# ./rtadmin user -create 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 9 Edit templates to your liking. Templates are found in rt/etc/templates/queues/ 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" | | <----/ | | <---/ "action" here will make this address only parse actions in the message without recording the message as a transaction of its own" WARNING: as currently written, any mail from postmaster or mailer-daemon will be silently discarded. Some users of RT actually want that mail, and hand-edit line 288 of lib/rt/ui/mail/manipulate.pm accordingly. Be careful, because after that "if" is an "elseif" that you probably want to keep. 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" If you want to handle MIME Attachments, you should _really_ take a look at stripmime in ftp://ftp.fsck.com/pub/rt/contrib 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 Adam Hammer, Heather Sherman and Thomas Koester have all contributed bug reports, code or ideas that have helped RT along. Arepa, Inc, Utopia Inc, Wesleyan University, The Leftbank Operation and Into Networks 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