diff options
Diffstat (limited to 'rt/README')
| -rwxr-xr-x | rt/README | 232 |
1 files changed, 136 insertions, 96 deletions
@@ -1,8 +1,14 @@ -# BEGIN LICENSE BLOCK +# {{{ BEGIN BPS TAGGED BLOCK # -# Copyright (c) 1996-2003 Jesse Vincent <jesse@bestpractical.com> +# COPYRIGHT: +# +# This software is Copyright (c) 1996-2004 Best Practical Solutions, LLC +# <jesse@bestpractical.com> # -# (Except where explictly superceded by other copyright notices) +# (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 @@ -14,13 +20,29 @@ # 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. +# 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.) # -# END LICENSE BLOCK +# 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 @@ -28,30 +50,31 @@ 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 - March 2003 + June 2004 + REQUIRED PACKAGES: ------------------ -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.)` +o Perl 5.8.3 or later (http://www.perl.com). - Perl 5.6.1 is currently deprecated and will be officially desupported - in a future release + 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. + 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. - 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 ) @@ -66,23 +89,7 @@ o Apache version 1.3.x or 2.x (http://httpd.apache.org) 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. - - + 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 @@ -97,9 +104,10 @@ o Various and sundry perl modules 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 +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 @@ -112,53 +120,69 @@ http://www.bestpractical.com/rt ./configure --help to see the list of options ./configure (with the flags you want) -3 Satisfy RT's myriad dependencies. +3 Make sure that RT has everything it needs to run: -3.1 Check for compliance: - - perl sbin/rt-test-dependencies \ - --with-<databasename> --with-<web-environment> +3.1 Check for missing dependencies: - databasename is one of: mysql, postgres - web-environment is one of: fastcgi, modperl1, modperl2 + make testdeps 3.2 If there are unsatisfied dependencies, install them by hand or run: - perl sbin/rt-test-dependencies \ - --with-<databasename> --with-<web-environment> --install - + make fixdeps 3.3 Check to make sure everything was installed properly: + + make testdeps - perl sbin/rt-test-dependencies \ - --with-<databasename> --with-<web-environment> + 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 (replace "make" with the local name for - Make, if you need to) - + 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.0.x series) +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 (replace "make" with the local name for - Make, if you need to) + make upgrade This will build new binaries, config files and libraries without overwriting your RT database. - - It may then instruct you to update your RT system database objects + + 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/<version> + /opt/rt3/sbin/rt-setup-database --action acl \ + --datadir etc/upgrade/<version> + /opt/rt3/sbin/rt-setup-database --action insert \ + --datadir etc/upgrade/<version> + + +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 @@ -180,43 +204,64 @@ http://www.bestpractical.com/rt THE WEB INTERFACE ----------------- -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'. +RT's web interface is based around HTML::Mason, which works well with +the mod_perl perl interpreter within Apache httpd and FastCGI -Apache - You'll need to add a few lines to your httpd.conf telling it about RT: +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: <VirtualHost your.ip.address> ServerName your.rt.server.hostname DocumentRoot /opt/rt3/share/html AddDefaultCharset UTF-8 - # this line applies to Apache2+mod_perl2 only + # 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 - # this section applies to Apache 1 only <Location /> SetHandler perl-script PerlHandler RT::Mason </Location> +</VirtualHost> - # 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> +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: + +<VirtualHost rt.example.com> + + # 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/ + </VirtualHost> @@ -224,6 +269,9 @@ Apache 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. @@ -244,14 +292,15 @@ rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url ht BUGS ---- -To report a bug, send email to rt-3.0-bugs@fsck.com. +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. +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 @@ -264,15 +313,15 @@ 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.fsck.com + 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.fsck.com. Subscribe to it with instructions similar to -those above. +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 @@ -286,15 +335,6 @@ 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. - - -TROUBLESHOOTING ---------------- - -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 released -versions of RT) or rt-devel@fsck.com (for development versions). - -Thanks! |