diff options
Diffstat (limited to 'rt/README')
| -rwxr-xr-x | rt/README | 302 |
1 files changed, 302 insertions, 0 deletions
diff --git a/rt/README b/rt/README new file mode 100755 index 0000000..7188f09 --- /dev/null +++ b/rt/README @@ -0,0 +1,302 @@ +# 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. + + + Jesse Vincent + Best Practical Solutions, LLC + March 2003 + +REQUIRED PACKAGES: +------------------ + +o Perl 5.8.3 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. + + 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. + Postgres 7.2 or later. + Oracle 9iR2. + +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 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 '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 + +2 Run the "configure" script. + + ./configure --help to see the list of options + ./configure (with the flags you want) + +3 Satisfy RT's myriad dependencies. + +3.1 Check for compliance: + + perl sbin/rt-test-dependencies \ + --with-<databasename> --with-<web-environment> + + databasename is one of: mysql, postgres, oracle + web-environment is one of: fastcgi, modperl1, modperl2 + +3.2 If there are unsatisfied dependencies, install them by hand or run: + + perl sbin/rt-test-dependencies \ + --with-<databasename> --with-<web-environment> --install + + +3.3 Check to make sure everything was installed properly: + + 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 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) + + + Read through the UPGRADING document included in this distribution. + It may contain important instructions for updating your database + + 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. + + It may then instruct you to update your RT system database objects + +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 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 + 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 + PerlModule Apache2 Apache::compat + RewriteEngine On + RewriteRule ^(.*)/$ $1/index.html + # }}} + + PerlModule Apache::DBI + PerlRequire /opt/rt3/bin/webmux.pl + + <Location /> + SetHandler perl-script + PerlHandler RT::Mason + </Location> +</VirtualHost> + + + +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 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/" + | | | + <queue-name>----/ | | + | | + <correspond or comment depending on whether | | + the mail should be resent to the requestor>---/ | + | + <URL for RT's web interface>---/ + + +BUGS +---- + +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. + +If you're interested in having RT extended or customized or would like more +information about commercial support options, please send email to +<sales@bestpractical.com> 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.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.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 publicly, send them personally to +<jesse@bestpractical.com>. + + +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! |