diff options
Diffstat (limited to 'rt/README')
| -rwxr-xr-x | rt/README | 402 |
1 files changed, 183 insertions, 219 deletions
@@ -1,139 +1,167 @@ -$Header: /home/cvs/cvsroot/freeside/rt/README,v 1.1 2002-08-12 06:17:06 ivan Exp $ -RT is (c) 1996-2002 by Jesse Vincent <jesse@bestpractical.com> +# BEGIN LICENSE BLOCK +# +# Copyright (c) 1996-2003 Jesse Vincent <jesse@bestpractical.com> +# +# (Except where explictly superceded by other copyright notices) +# +# This work is made available to you under the terms of Version 2 of +# the GNU General Public License. A copy of that license should have +# been provided with this software, but in any event can be snarfed +# from www.gnu.org. +# +# This work is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# General Public License for more details. +# +# Unless otherwise specified, all modifications, corrections or +# extensions to this work which alter its source code become the +# property of Best Practical Solutions, LLC when submitted for +# inclusion in the work. +# +# +# END LICENSE BLOCK +RT is an enterprise-grade issue tracking system. It allows +organizations to keep track of their to-do lists, who is working +on which tasks, what's already been done, and when tasks were +completed. It is available under the terms of version 2 of the GNU +General Public License (GPL), so it doesn't cost anything to set +up and use. -RT is licensed to you under the terms of version 2 of the GNU General -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. - - -INSTALLATION INSTRUCTIONS -------------------------- - -These instructions are a summary of those at http://www.fsck.com/rtfm/ -The docs on the web at www.fsck.com/rtfm/ are likely to be more up to -date and complete than this document. You should consult them before -proceeding. + Jesse Vincent + Best Practical Solutions, LLC + March 2003 REQUIRED PACKAGES: ------------------ -o Perl5.005_03 or later with support for setgid perl scripts - RT's command line and mail gateway tools run setgid to the 'rt' group - to protect RT's database password. You may need to install a special - "suidperl" package or reconfigure your perl setup to support - "setuid scripts". +o Perl 5.8.0 or later (http://www.perl.com). + + (If you intend to use the FastCGI or SpeedyCGI support, you + need to make sure that perl has been built with support for + setgid perl scripts.)` + + Perl 5.6.1 is currently deprecated and will be officially desupported + in a future release o A DB backend; MySQL is recommended ( http://www.mysql.com ) - Currently supported: Mysql 3.23.38 or newer. - (Some older releases had crippling SQL bugs) - Postgres 7.1 or newer. + Currently supported: Mysql 4.0.13 or later. + Postgres 7.2 or later. + + Mysql 3.23.46 or newer with support for InnoDB + is currently deprecated and will be officially + desupported in a future release. + +o Apache version 1.3.x or 2.x (http://httpd.apache.org) + with mod_perl -- (http://perl.apache.org ) + or a webserver with FastCGI support (www.fastcgi.com) + + mod_perl 2.0 isn't quite ready for prime_time just yet; + Best Practical Solutions strongly recommends that sites use + Apache 1.3 or FastCGI. + + Compiling mod_perl on Apache 1.3.x as a DSO has been known + to have massive stability problems and is not recommended. + + mod_perl 1.x must be build with EVERYTHING=1 + + RT's FastCGI handler runs setgid to the 'rt' group to + protect RT's database password. You may need to install + a special "suidperl" package or reconfigure your perl + setup to support "setuid scripts" if you intend to use RT + with FastCGI. + + Debian GNU/* 3.0+: the package which installs suidperl is + called perl-suid, and should work without any tweaking. + + FreeBSD 4.2+: the package is called sperl, and should + install a suidperl that just works + + Conectiva Linux 6.0+: suidperl is installed by default when + perl is installed, but the program /bin/suidperl is not setuid. + You must use chmod to make it setuid. -o Apache + mod_perl -- ( http://perl.apache.org) - or A webserver with FastCGI support (www.fastcgi.com) - If you compile mod_perl as a DSO, you're on your own. It's known - to have massive stability problems. - mod_perl must be build with EVERYTHING=1 o Various and sundry perl modules - RT takes care of the installation of most of these automatically - during the "make testdeps" and "make fixdeps" stages below + A tool included with RT takes care of the installation of + most of these automatically during the install process. + + The tool supplied with RT uses Perl's CPAN system + (http://www.cpan.org) to install modules. Some operating + systems package all or some of the modules required and + you may be better off installing the modules that way. GENERAL INSTALLATION -------------------- +This is a rough guide to installing RT. For more detail, you'll want +to read 'Chapter 2: Installing' in RT's manual, available at +http://www.bestpractical.com/rt + 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 + tar xzvf rt.tar.gz -C /tmp -2 Check over /tmp/rt/Makefile +2 Run the "configure" script. - There are many variables you NEED to customize for your site. - Even if you are just upgrading, you must set ALL variables. + ./configure --help to see the list of options + ./configure (with the flags you want) -3 Satisfy RT's myriad dependencies. There's a perl script in rt/tools - called testdeps that uses CPAN to automate all of this. +3 Satisfy RT's myriad dependencies. 3.1 Check for compliance: - make testdeps + + perl sbin/rt-test-dependencies \ + --with-<databasename> --with-<web-environment> + + databasename is one of: mysql, postgres + web-environment is one of: fastcgi, modperl1, modperl2 -3.2 If there are unsatisfied dependencies, install them by hand or run - make fixdeps - - (You may need to install Apache::Session and Apache::DBI by hand. +3.2 If there are unsatisfied dependencies, install them by hand or run: - You might need to install Msql-Mysql-Modules by hand. - perl -MCPAN -e'install DBD::mysql::Install' should do it for you. - ) + perl sbin/rt-test-dependencies \ + --with-<databasename> --with-<web-environment> --install + 3.3 Check to make sure everything was installed properly: - make testdeps + + perl sbin/rt-test-dependencies \ + --with-<databasename> --with-<web-environment> 4 Create a group called 'rt' 5a FOR A NEW INSTALLATION: As root, type: - make install (replace "make" with the local name for - Make, if you need to) + make install (replace "make" with the local name for + Make, if you need to) - If the make fails, type: - make dropdb - and start over from step 5a + + make initialize-database -5b FOR UPGRADING: (Within the RT 2.0.x series) - Make a backup of /path/to/rt/etc/config.pm - - As root, type: - make upgrade (replace "make" with the local name for - Make, if you need to) + If the make fails, type: + make dropdb + and start over from step 5a - This will build new binaries, config files and libraries without - overwriting your RT database. +5b FOR UPGRADING: (Within the RT 3.0.x series) - WARNING: This WILL clobber your existing configuration file! - - The install process will then instruct you to update your RT system - database objects by running rt/etc/insertdata <version> where - <version> is the version of RT you're upgrading from. + As root, type: + make upgrade (replace "make" with the local name for + Make, if you need to) + This will build new binaries, config files and libraries without + overwriting your RT database. - -5c FOR UPGRADING (From 1.0.x): - - Follow the instructions for installing RT 2.0. + It may then instruct you to update your RT system database objects - Once you have installed RT 2.0, download import-1.0-to-2.0 - from http://www.fsck.com/pub/rt/contrib/2.0/rt-addons - - Edit the configuration defaults in import-1.0-to-2.0 - - If you don't set $DEFAULTQUEUE to the name of one of your - RT 1.0 queues, THE IMPORT WILL FAIL. - - perl ./import-1.0-to-2.0 - - The import tool will do its thing. If you're using postgres, you'll - need to execute the following SQL statement within your RT2 database: - - select setval('tickets_id_seq', (select max(id) from tickets)); - - It imports: - Queues, Areas, Users, Acls, Mailing Rules, Queue Members, - Tickets and Transactions. - - It DOES NOT IMPORT: - Attachments removed by stripmime or Templates. - -6 Edit etc/config.pm in your RT installation directory. In many - cases sensible defaults have been included. In others, you MUST - supply a value. +6 Edit etc/RT_SiteConfig.pm in your RT installation directory, by specifying + any values you need to change from the defaults in etc/RT_Config.pm 7 Configure the email and web gateways, as described below. @@ -142,97 +170,81 @@ GENERAL INSTALLATION NOTE: root's password for the web interface is "password" (without the quotes.) Not changing this is a SECURITY risk -9 Configure RT per the instructions at http://www.fsck.com/rtfm/ +9 Configure RT per the instructions in RT's manual. - Until you do this, RT will not be able to send or recieve email, + Until you do this, RT will not be able to send or receive email, nor will it be more than marginally functional. This is not an optional step. -SETTING UP THE MAIL GATEWAY ---------------------------- +THE WEB INTERFACE +----------------- -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 lines to /etc/aliases (or your local equivalent) : - -rt: "|/path/to/rt2/bin/rt-mailgate --queue general --action correspond" -rt-comment: "|/path/to/rt2/bin/rt-mailgate --queue general --action comment" - | | - <queue-name>----/ | - | - <correspond or comment depending on whether | - the mail should be resent to the requestor>---/ - - - -THE WEB UI ----------- - -RT's web ui is based around HTML::Mason, which works well with the mod_perl -perl interpreter within Apache httpd as well as with a webserver which -supports FastCGI. (Instructions for configuring RT for use with FastCGI -are available at http://www.fsck.com/rtfm/ ) +RT's web interface is based around HTML::Mason, which works best with the mod_perl +perl interpreter within Apache httpd. Alternatively, support for the FastCGI +(and plain CGI) interface is also provided as 'bin/mason_handler.fcgi'. Apache - RT Uses HTML::Mason. You'll need to add a few lines to your - httpd.conf telling it to use rt's web ui. If you have mod-perl - (you should, the perl scripts will go quite a bit faster around with - it), you can do something like this: - + You'll need to add a few lines to your httpd.conf telling it about RT: <VirtualHost your.ip.address> -DocumentRoot /path/to/rt2/WebRT/html -ServerName your.rt.server.hostname -PerlModule Apache::DBI -PerlFreshRestart On -PerlRequire /path/to/rt2/bin/webmux.pl -<Location /> - SetHandler perl-script - PerlHandler RT::Mason -</Location> + ServerName your.rt.server.hostname + DocumentRoot /opt/rt3/share/html + AddDefaultCharset UTF-8 + + # this line applies to Apache2+mod_perl2 only + PerlModule Apache2 Apache::compat + + PerlModule Apache::DBI + PerlRequire /opt/rt3/bin/webmux.pl + + # this section applies to Apache 1 only + <Location /> + SetHandler perl-script + PerlHandler RT::Mason + </Location> + + # this section applies to Apache2+mod_perl2 only + <FilesMatch "\.html$"> + SetHandler perl-script + PerlHandler RT::Mason + </FilesMatch> + <LocationMatch "/Attachment/"> + SetHandler perl-script + PerlHandler RT::Mason + </LocationMatch> + <LocationMatch "/REST/"> + SetHandler perl-script + PerlHandler RT::Mason + </LocationMatch> </VirtualHost> -Additionally, you should set up a cron job to remove stale session data. - -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - WARNING: Don't install this cron job or run this find command if your - MASON_SESSION_PATH (known in config.pm as $MasonSessionDir) - points to a directory that could EVER contain any file that's not - a Apache::Session datafile. -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -# Every hour, nuke session files and lockfiles that haven't been -# touched in 10 hours - -0 * * * * find /path/to/rt2/WebRT/sessiondata -type f -amin +600 -exec rm {} \; -THE CLI -------- - Binaries for the CLI are located in rt/bin - You've got: +SETTING UP THE MAIL GATEWAY +--------------------------- - "rt" (manipulate or display requests) - "rtadmin" (modify queues, users and acls) +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 lines to /etc/aliases (or your local equivalent) : - Both of these programs take --help as an option. +rt: "|/opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://localhost/" +rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url http://localhost/" + | | | + <queue-name>----/ | | + | | + <correspond or comment depending on whether | | + the mail should be resent to the requestor>---/ | + | + <URL for RT's web interface>---/ BUGS ---- -Known issues with releases of RT2 are listed at -<URL:http://fsck.com/rt2/NoAuth/Errata.html>. This includes every bug known -to exist in each release of RT. (When prompted, login as guest/guest) - -To find out more about currently open bugs, check out the live -Buglist at <URL:http://fsck.com/rt2/NoAuth/Buglist.html>. -(When prompted, login as guest/guest) - -To report a bug, send an email to rt-2.0-bugs@fsck.com. +To report a bug, send email to rt-3.0-bugs@fsck.com. GETTING HELP ------------ @@ -249,8 +261,8 @@ information about commercial support options, please send email to RT-USERS MAILINGLIST -------------------- -To keep up to date on the latest RT tips, techniques and extections, -you probably want to join the rt-users mailinglist. Send a message to: +To keep up to date on the latest RT tips, techniques and extensions, +you probably want to join the rt-users mailing list. Send a message to: rt-users-request@lists.fsck.com @@ -258,79 +270,31 @@ With the body of the message consisting of only the word: subscribe -If you're interested in hacking on rt, you'll want to subscribe to +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. Address questions about the stable release to the rt-users list, and questions about the development version to the rt-devel list. If you feel -your questions are best not asked publically, send them personally to +your questions are best not asked publicly, send them personally to <jesse@bestpractical.com>. -If you want to be informed of every commit to the CVS repository, -subscribe to rt-commit@fsck.com using similar instructions to those above. - RT WEBSITE ---------- For current information about RT, check out the RT website at -http://www.bestpractical.com/rt You'll find screenshots, a pointer -to the current version of rt, contributed patches and lots of other great -stuff. + http://www.bestpractical.com/ + +You'll find screenshots, a pointer to the current version of RT, contributed +patches, and lots of other great stuff. TROUBLESHOOTING --------------- -All errors will be appended to a logfile, which lives in /tmp/rt.log.* unless -you've reconfigured it. Check etc/config.pm for details. - If the solution to the problem you're running into isn't obvious and you've -checked the FAQ, feel free to send mail to rt-users@fsck.com (for release +checked the FAQ, feel free to send mail to rt-users@fsck.com (for released versions of RT) or rt-devel@fsck.com (for development versions). -GIVING SOMETHING BACK ---------------------- - -RT is free software. You are not obligated to pay for it. You should be -aware, however, that bestpractical.com's sole source of revenue is commercial -work related to RT. If you are able, either a contract to extend RT in some -way that would be useful to your organization, a financial contribution, or -even something off the author's amazon wishlist - ( http://www.amazon.com/exec/obidos/wishlist/2GMHUDAFBT2XR/ ) -would be much appreciated. - Thanks! - - -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 Wiesman, Adam Hammer, Ivan Kohler, Alex -Pilosov, Mary Alderdice, Deborah Kaplan, Jens von Bülow, Tristan Horn, -Lee Ann Goldstein, Karel P Kerezman, Feargal Reilly, Christian Steger, -Christian Kurz, JD Falk, Arthur de Jong, Ben Carter, Mark Vevers -and many others -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 maintain 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@bestpractical.com> - Best Practical Solutions, LLC |