# {{{ BEGIN BPS TAGGED BLOCK # # COPYRIGHT: # # This software is Copyright (c) 1996-2004 Best Practical Solutions, LLC # # # (Except where explicitly superseded by other copyright notices) # # # LICENSE: # # 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. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. # # # CONTRIBUTION SUBMISSION POLICY: # # (The following paragraph is not intended to limit the rights granted # to you to modify and distribute this software under the terms of # the GNU General Public License and is only of importance to you if # you choose to contribute your changes and enhancements to the # community by submitting them to Best Practical Solutions, LLC.) # # By intentionally submitting any modifications, corrections or # derivatives to this work, or any other work intended for use with # Request Tracker, to Best Practical Solutions, LLC, you confirm that # you are the copyright holder for those contributions and you grant # Best Practical Solutions, LLC a nonexclusive, worldwide, irrevocable, # royalty-free, perpetual, license to use, copy, create derivative # works based on those contributions, and sublicense and distribute # those contributions and any derivatives thereof. # # }}} END BPS TAGGED 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 commercially supported software. To purchase support, training, custom development or professional services, please write to sales@bestpractical.com. Jesse Vincent Best Practical Solutions, LLC June 2004 REQUIRED PACKAGES: ------------------ o Perl 5.8.3 or later (http://www.perl.com). Perl versions prior to 5.8.3 contain bugs that could result in data corruption. We recommend strongly that you use 5.8.3 or newer. RT may function with perl 5.8.0 and later, but is unsupported in that configuration. o A DB backend; MySQL is recommended ( http://www.mysql.com ) Currently supported: Mysql 4.0.13 or later with InnoDB support. Postgres 7.2 or later. Oracle 9iR2. Beta-quality support for Informix and SQLite is also available. 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 needs to access RT's configuration file. o Various and sundry perl modules 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 a more comprehensive installation guide at: http://wiki.bestpractical.com/index.cgi?InstallationGuides 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 Run the "configure" script. ./configure --help to see the list of options ./configure (with the flags you want) 3 Make sure that RT has everything it needs to run: 3.1 Check for missing dependencies: make testdeps 3.2 If there are unsatisfied dependencies, install them by hand or run: make fixdeps 3.3 Check to make sure everything was installed properly: make testdeps It might sometimes be necessary to run "make fixdeps" several times to install all necessary perl modules. 4 Create a group called 'rt' 5a FOR A NEW INSTALLATION: As root, type: make install make initialize-database If the make fails, type: make dropdb and start over from step 5a 5b FOR UPGRADING: (Within the RT 3.x series) Read through the UPGRADING document included in this distribution. It may contain important instructions which will help you upgrade RT safely. As root, type: make upgrade This will build new binaries, config files and libraries without overwriting your RT database. You may also need to update RT's database. To find out, type: ls etc/upgrade For each item in that directory whose name is greater than your previously installed RT version, run: /opt/rt3/sbin/rt-setup-database --action schema \ --datadir etc/upgrade/ /opt/rt3/sbin/rt-setup-database --action acl \ --datadir etc/upgrade/ /opt/rt3/sbin/rt-setup-database --action insert \ --datadir etc/upgrade/ 5c FOR UPGRADING: (From RT 2.0.x) Download the RT2 to RT3 migration tools from: http://bestpractical.com/pub/rt/devel/rt2-to-rt3.tar.gz Follow the included instructions. 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. 8 Stop and start your webserver, so it picks up your configuration changes. 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 in RT's manual. 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. THE WEB INTERFACE ----------------- RT's web interface is based around HTML::Mason, which works well with the mod_perl perl interpreter within Apache httpd and FastCGI mod_perl -------- To install RT with mod_perl, you'll need to add a few lines to your Apache configuration file telling it about RT: ServerName your.rt.server.hostname DocumentRoot /opt/rt3/share/html AddDefaultCharset UTF-8 # these four lines apply to Apache2+mod_perl2 only: {{{ PerlSetVar MasonArgsMethod CGI PerlModule Apache2 Apache::compat RewriteEngine On RewriteRule ^(.*)/$ $1/index.html # }}} PerlModule Apache::DBI PerlRequire /opt/rt3/bin/webmux.pl SetHandler perl-script PerlHandler RT::Mason FastCGI ------- Installation with FastCGI is a little bit more complex and is documented in detail at http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration In the most basic configuration, you can set up your webserver to run as a user who is a member of the "rt" unix group so that the FastCGI script can read RT's configuration file. It's important to understand the security implications of this configuration, which are discussed in the document mentioned above. To install RT with FastCGI, you'll need to add a few lines to your Apache configuration file telling it about RT: # Pass through requests to display images Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/ # Tell FastCGI to put its temporary files somewhere sane. FastCgiIpcDir /tmp FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120 AddHandler fastcgi-script fcgi ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/ SETTING UP THE MAIL GATEWAY --------------------------- RT can accept incoming email using a simple program run as a "pipe" by your mail server. 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: "|/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/" | | | ----/ | | | | ---/ | | ---/ BUGS ---- To report a bug, send email to rt-bugs@fsck.com. GETTING HELP ------------ If RT is mission-critical for you or if you use it heavily, we recommend that you purchase a commercial support contract. Details on support contracts are available at http://www.bestpractical.com or by writing to sales@bestpractical.com. If you're interested in having RT extended or customized or would like more information about commercial support options, please send email to to discuss rates and availability. RT-USERS MAILINGLIST -------------------- 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.bestpractical.com 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 rt-devel@lists.bestpractical.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 publicly, send them personally to . RT WEBSITE ---------- For current information about RT, check out the RT website at http://www.bestpractical.com/ You'll find screenshots, a pointer to the current version of RT, contributed patches, and lots of other great stuff.