diff options
Diffstat (limited to 'rt/README')
| -rwxr-xr-x | rt/README | 232 |
1 files changed, 96 insertions, 136 deletions
@@ -1,14 +1,8 @@ -# {{{ BEGIN BPS TAGGED BLOCK +# BEGIN LICENSE BLOCK # -# COPYRIGHT: -# -# This software is Copyright (c) 1996-2004 Best Practical Solutions, LLC -# <jesse@bestpractical.com> +# Copyright (c) 1996-2003 Jesse Vincent <jesse@bestpractical.com> # -# (Except where explicitly superseded by other copyright notices) -# -# -# LICENSE: +# (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 @@ -20,29 +14,13 @@ # 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: +# 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. # -# (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 +# 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 @@ -50,31 +28,30 @@ 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 - + March 2003 REQUIRED PACKAGES: ------------------ -o Perl 5.8.3 or later (http://www.perl.com). +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 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. + 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 4.0.13 or later with InnoDB support. + Currently supported: Mysql 4.0.13 or later. 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 ) @@ -89,7 +66,23 @@ 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 needs to access RT's configuration file. + 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 Various and sundry perl modules A tool included with RT takes care of the installation of @@ -104,10 +97,9 @@ o Various and sundry perl modules 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 +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 @@ -120,69 +112,53 @@ want to read a more comprehensive installation guide at: ./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 Satisfy RT's myriad dependencies. -3.1 Check for missing dependencies: +3.1 Check for compliance: + + perl sbin/rt-test-dependencies \ + --with-<databasename> --with-<web-environment> - make testdeps + 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 + perl sbin/rt-test-dependencies \ + --with-<databasename> --with-<web-environment> --install + 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. + 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 + make install (replace "make" with the local name for + Make, if you need to) + 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. +5b FOR UPGRADING: (Within the RT 3.0.x series) As root, type: - make upgrade + 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. - - 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. + + It may then instruct you to update your RT system database objects 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 @@ -204,64 +180,43 @@ want to read a more comprehensive installation guide at: 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 +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'. -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: +Apache + You'll need to add a few lines to your httpd.conf telling it about RT: <VirtualHost your.ip.address> 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 + # this line applies to Apache2+mod_perl2 only 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> - -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/ - + # 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> @@ -269,9 +224,6 @@ Apache configuration file telling it about RT: 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. @@ -292,15 +244,14 @@ rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url ht BUGS ---- -To report a bug, send email to rt-bugs@fsck.com. +To report a bug, send email to rt-3.0-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. +are available at http://www.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 @@ -313,15 +264,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.bestpractical.com + rt-users-request@lists.fsck.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. +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 @@ -335,6 +286,15 @@ 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! |