X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=rt%2FREADME;h=361c206814a809aa29256f00f07a2edbda5c03ff;hp=d16100c5f4d10d5baf24fa9d24258004c3ca348d;hb=ea3ce8d7f076e7fecff4be7ae63bc413adb0adf5;hpb=0ebeec96313dd7edfca340f01f8fbbbac1f4aa1d diff --git a/rt/README b/rt/README index d16100c5f..361c20681 100755 --- a/rt/README +++ b/rt/README @@ -1,336 +1,425 @@ -$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 +RT is an enterprise-grade issue tracking system. It allows organizations +to keep track of what needs to get done, who is working on which tasks, +what's already been done, and when tasks were (or weren't) completed. -RT is licensed to you under the terms of version 2 of the GNU General -Public License. +RT doesn't cost anything to use, no matter how much you use it; it +is freely available 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. +RT is commercially-supported software. To purchase support, training, +custom development, or professional services, please get in touch with +us at sales@bestpractical.com. + Jesse Vincent + Best Practical Solutions, LLC + March, 2010 -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. +REQUIRED PACKAGES +----------------- -REQUIRED PACKAGES: ------------------- +o Perl 5.8.3 or later (http://www.perl.org). -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". + Perl versions prior to 5.8.3 contain bugs that could result + in data corruption. RT won't start on older versions. -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. +o A supported SQL database -o Apache + mod_perl -- ( http://perl.apache.org) - or A webserver with FastCGI support (www.fastcgi.com) + Currently supported: Mysql 4.0.13 or later with InnoDB support. + Postgres 7.2 or later. + Oracle 9iR2 or later. + SQLite 3.0. (Not recommended for production) - 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 Apache version 1.3.x or 2.x (http://httpd.apache.org) + with mod_perl -- (http://perl.apache.org ) + or with FastCGI -- (www.fastcgi.com) + or other webserver with FastCGI support -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 + 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 -------------------- -1 Unpack this distribution SOMWHERE OTHER THAN where you want to install RT +1 Unpack this distribution other than where you want to install RT + + To do this cleanly, run the following command: + + 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) + + RT defaults to installing in /opt/rt3 with MySQL as its database. It + tries to guess which of www-data, www, apache or nobody your webserver + will run as, but you can override that behavior. Note that the + default install directory in /opt/rt3 does not work under SELinux's + default configuration. + + If you're upgrading RT stop and review the UPGRADING document. + Some extensions you're using may have been integrated into + core, or there may be other extra steps to follow. It's recommended + that you use a new clean directory when you're upgrading to + new major release (for example from 3.6.x to 3.8.x). + +3 Make sure that RT has everything it needs to run. + + Check for missing dependencies by running: + + make testdeps + +4 If the script reports any missing dependencies, install them by hand + or run the following command as a user who has permission to install perl + modules on your system: + + make fixdeps + + Some modules require user input or environment variables to install correctly, + so it may be necessary to install them manually. + +5 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. + +6 If this is a new installation: - Granted, you've already got it open. To do this cleanly: + As a user with permission to install RT in your chosen directory, type: - tar xzvf rt.tar.gz -C /tmp + make install -2 Check over /tmp/rt/Makefile + Set up etc/RT_SiteConfig.pm in your RT installation directory. + You'll need to add any values you need to change from the defaults + in etc/RT_Config.pm - There are many variables you NEED to customize for your site. - Even if you are just upgrading, you must set ALL variables. + As a user with permission to read RT's configuration file, type: -3 Satisfy RT's myriad dependencies. There's a perl script in rt/tools - called testdeps that uses CPAN to automate all of this. + make initialize-database -3.1 Check for compliance: - make testdeps + If the make fails, type: -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. + make dropdb - You might need to install Msql-Mysql-Modules by hand. - perl -MCPAN -e'install DBD::mysql::Install' should do it for you. - ) + and start over from step 6 -3.3 Check to make sure everything was installed properly: - make testdeps +7 If you're upgrading from RT 3.0 or newer: -4 Create a group called 'rt' + Read through the UPGRADING document included in this distribution. If + you're using MySQL, read through UPGRADING.mysql as well. -5a FOR A NEW INSTALLATION: - - As root, type: - make install (replace "make" with the local name for - Make, if you need to) + It includes special upgrade instructions that will help you get this + new version of RT up and running smoothly. - If the make fails, type: - make dropdb - and start over from step 5a + As a user with permission to install RT in your chosen installation + directory, type: -5b FOR UPGRADING: (Within the RT 2.0.x series) + make upgrade - 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) + This will install new binaries, config files and libraries without + overwriting your RT database. - This will build new binaries, config files and libraries without - overwriting your RT database. + Update etc/RT_SiteConfig.pm in your RT installation directory. + You'll need to add any new values you need to change from the defaults + in etc/RT_Config.pm - 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 where - is the version of RT you're upgrading from. + You may also need to update RT's database. You can do this with + the rt-setup-database tool. Replace root with the name of the dba + user on your database (root is the default for MySQL). - - -5c FOR UPGRADING (From 1.0.x): + You will be prompted for your previous version of RT (such as 3.6.4) + so that we can calculate which database updates to apply - Follow the instructions for installing RT 2.0. + You should back up your database before running this command. - 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 + /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade - Edit the configuration defaults in import-1.0-to-2.0 + Clear mason cache dir: - If you don't set $DEFAULTQUEUE to the name of one of your - RT 1.0 queues, THE IMPORT WILL FAIL. + rm -fr /opt/rt3/var/mason_data/obj - perl ./import-1.0-to-2.0 + Stop and start web-server. - 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. +8 If you're upgrading from RT 2.0: - 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. + Read more in UPGRADING -7 Configure the email and web gateways, as described below. +9 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! - 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/ +10 Set up automated recurring tasks (cronjobs): - Until you do this, RT will not be able to send or recieve email, + To generate email digest messages, you must arrange for the provided + utility to be run once daily, and once weekly. You may also want to + arrange for the rt-email-dashboards utility to be run hourly. + For example, if your task scheduler is cron, you can configure it as + follows: + + crontab -e # as the RT administrator (probably root) + # insert the following lines: + 0 0 * * * /opt/rt3/sbin/rt-email-digest -m daily + 0 0 * * 0 /opt/rt3/sbin/rt-email-digest -m weekly + 0 * * * * /opt/rt3/sbin/rt-email-dashboards + + +11 Set up users, groups, queues, scrips and access control. + + 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 ---------------------------- +SETTING UP 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's web interface is based around HTML::Mason, which works well with +the mod_perl perl interpreter within Apache httpd and FastCGI. -rt: "|/path/to/rt2/bin/rt-mailgate --queue general --action correspond" -rt-comment: "|/path/to/rt2/bin/rt-mailgate --queue general --action comment" - | | - ----/ | - | - ---/ +Once you've set up the web interface, consider setting up automatic +logout for inactive sessions. For more information about how to do that, +run + perldoc /path/to/rt/sbin/rt-clean-sessions +mod_perl 1.xx +------------- -THE WEB UI ----------- +WARNING: mod_perl 1.99_xx is not supported. + +See below configuration instructions for mod_perl 2.x -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/ ) +To install RT with mod_perl 1.x, you'll need to install the +apache database connection cache. To make sure it's installed, run +the following command: -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: + perl -MCPAN -e'install "Apache::DBI"' +Next, add a few lines to your Apache 1.3.xx configuration file, so that +it knows where to find RT: -DocumentRoot /path/to/rt2/WebRT/html -ServerName your.rt.server.hostname -PerlModule Apache::DBI -PerlFreshRestart On -PerlRequire /path/to/rt2/bin/webmux.pl - - SetHandler perl-script - PerlHandler RT::Mason - + ServerName your.rt.server.hostname + + DocumentRoot /opt/rt3/share/html + AddDefaultCharset UTF-8 + + # optional apache logs for RT + # ErrorLog /opt/rt3/var/log/apache.error + # TransferLog /opt/rt3/var/log/apache.access + + PerlModule Apache::DBI + PerlRequire /opt/rt3/bin/webmux.pl + + + SetHandler default + + + SetHandler perl-script + PerlHandler RT::Mason + -Additionally, you should set up a cron job to remove stale session data. +mod_perl 2.xx +------------- + +WARNING: mod_perl 1.99_xx is not supported. + +Add a few lines to your Apache 2.xx configuration file, so that +it knows where to find RT: -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - 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. -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + ServerName your.rt.server.hostname + + DocumentRoot /opt/rt3/share/html + AddDefaultCharset UTF-8 -# Every hour, nuke session files and lockfiles that haven't been -# touched in 10 hours + # optional apache logs for RT + # ErrorLog /opt/rt3/var/log/apache2.error + # TransferLog /opt/rt3/var/log/apache2.access -0 * * * * find /path/to/rt2/WebRT/sessiondata -type f -amin +600 -exec rm {} \; + PerlRequire "/opt/rt3/bin/webmux.pl" + + SetHandler default + + + SetHandler perl-script + PerlResponseHandler RT::Mason + + -THE CLI +FastCGI ------- - Binaries for the CLI are located in rt/bin - You've got: - "rt" (manipulate or display requests) - "rtadmin" (modify queues, users and acls) +Installation with FastCGI is a little bit more complex and is documented +in detail at http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration - Both of these programs take --help as an option. +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: -BUGS ----- -Known issues with releases of RT2 are listed at -. This includes every bug known -to exist in each release of RT. (When prompted, login as guest/guest) +# Tell FastCGI to put its temporary files somewhere sane. +FastCgiIpcDir /tmp -To find out more about currently open bugs, check out the live -Buglist at . -(When prompted, login as guest/guest) +FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120 -To report a bug, send an email to rt-2.0-bugs@fsck.com. + + ServerName your.rt.server.hostname -GETTING HELP ------------- + # Pass through requests to display images + Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/ -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. + AddHandler fastcgi-script fcgi + ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/ + -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 --------------------- +SETTING UP THE MAIL GATEWAY +--------------------------- -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 let email flow to your RT server, you need to add a few lines of +configuration to your mail server's "aliases" file. These lines "pipe" +incoming email messages from your mail server to RT. - rt-users-request@lists.fsck.com +Add the following lines to /etc/aliases (or your local equivalent) on your mail server: -With the body of the message consisting of only the word: +rt: "|/opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://rt.example.com/" +rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url http://rt.example.com/" - subscribe +You'll need to add similar lines for each queue you want to be able +to send email to. To find out more about how to configure RT's email +gateway, type: -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. + perldoc /opt/rt3/bin/rt-mailgate -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 -. -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. + +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 +. + +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 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. +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 ---------------- -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 -versions of RT) or rt-devel@fsck.com (for development versions). - -GIVING SOMETHING BACK +RT-USERS MAILING LIST --------------------- -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. +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: -Thanks! + rt-users-request@lists.bestpractical.com +with the body of the message consisting of only the word: -CREDITS -------- + subscribe + +If you're interested in hacking on RT, you'll want to subscribe to +. 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 +. + + + +BUGS +---- -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 - - Best Practical Solutions, LLC +RT's a pretty complex application, and as you get up to speed, you might +run into some trouble. Generally, it's best to ask about things you +run into on the rt-users mailinglist (or pick up a commercial support +contract from Best Practical). But, sometimes people do run into bugs. In +the exceedingly unlikely event that you hit a bug in RT, please report +it! We'd love to hear about problems you have with RT, so we can fix them. +To report a bug, send email to rt-bugs@fsck.com. + + +# BEGIN BPS TAGGED BLOCK {{{ +# +# COPYRIGHT: +# +# This software is Copyright (c) 1996-2011 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., 51 Franklin Street, Fifth Floor, Boston, MA +# 02110-1301 or visit their web page on the internet at +# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html. +# +# +# 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 }}}