X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=rt%2FREADME;h=6581240aa9d0d175f1762b2990940f62014842ba;hp=7c5e4d47ad8abacf3187f1bcbd09ddaee00985c9;hb=681a340f6be4184b1472a8e1fa9cd5d074f6f325;hpb=673b9a458d9138523026963df6fa3b4683e09bae diff --git a/rt/README b/rt/README index 7c5e4d47a..6581240aa 100755 --- a/rt/README +++ b/rt/README @@ -1,300 +1,326 @@ -# BEGIN LICENSE BLOCK -# -# Copyright (c) 1996-2003 Jesse Vincent -# -# (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. +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 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. - Jesse Vincent - Best Practical Solutions, LLC - March 2003 +RT is commercially-supported software. To purchase support, training, +custom development, or professional services, please get in touch with +us at . -REQUIRED PACKAGES: ------------------- -o Perl 5.8.0 or later (http://www.perl.com). +REQUIRED PACKAGES +----------------- - (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.10.1 or later (http://www.perl.org). - Perl 5.6.1 is currently deprecated and will be officially desupported - in a future release + RT won't start on versions of Perl older than 5.10.1. -o A DB backend; MySQL is recommended ( http://www.mysql.com ) - Currently supported: Mysql 4.0.13 or later. - Postgres 7.2 or later. +o A supported SQL database - Mysql 3.23.46 or newer with support for InnoDB - is currently deprecated and will be officially - desupported in a future release. + Currently supported: MySQL 5.1 or later with InnoDB support. + Postgres 8.4 or later; 9.0 or later suggested + Oracle 9iR2 or later. + SQLite 3.0 or later; for testing only, no + upgrade path guaranteed -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) +o Apache version 1.3.x or 2.x (http://httpd.apache.org) + with FastCGI -- (http://www.fastcgi.com) + or mod_perl -- (http://perl.apache.org) + or another webserver with FastCGI support - 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. + RT's FastCGI handler needs to access RT's configuration file. - Compiling mod_perl on Apache 1.3.x as a DSO has been known - to have massive stability problems and is not recommended. +o Various and sundry perl modules - mod_perl 1.x must be build with EVERYTHING=1 + A tool included with RT takes care of the installation of most + of these automatically during the install process. - 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. + The tool supplied with RT uses Perl's CPAN (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. - 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 +GENERAL INSTALLATION +-------------------- - 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. + 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. To see the list of options, run: -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. + ./configure --help - 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. + Peruse the options, then rerun ./configure with the flags you want. + RT defaults to installing in /opt/rt4 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/rt4 does not work under + SELinux's default configuration. -GENERAL INSTALLATION --------------------- + If you are upgrading from a previous version of RT, please review + the upgrade notes for the appropriate versions, which can be found + in docs/UPGRADING-* If you are coming from 4.0.x to 4.2.x you should + review both the UPGRADING-4.0 and UPGRADING-4.2 files. Similarly, if + you were coming from 3.8.x, you would want to review the UPGRADING-3.8, + UPGRADING-4.0 and UPGRADING-4.2 documents. -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 + Any upgrade steps given in version-specific UPGRADING files should + be run after the rest of the steps below; however, please read the + relevant documentation before beginning the upgrade, so as to be + aware of important changes. -1 Unpack this distribution SOMWHERE OTHER THAN where you want to install RT + RT stores the arguments given to ./configure at the top of the + etc/RT_Config.pm file in case you need to recreate your previous use + of ./configure. - Granted, you've already got it open. To do this cleanly: + 3) Make sure that RT has the Perl and system libraries it needs to run. + Check for missing dependencies by running: - tar xzvf rt.tar.gz -C /tmp + make testdeps -2 Run the "configure" script. + 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: - ./configure --help to see the list of options - ./configure (with the flags you want) + make fixdeps -3 Satisfy RT's myriad dependencies. + Some modules require user input or environment variables to install + correctly, so it may be necessary to install them manually. -3.1 Check for compliance: - - perl sbin/rt-test-dependencies \ - --with- --with- + If you are having trouble installing GD, refer to "Installing GD libraries" + in docs/charts.pod. Ticket relationship graphing requires the graphviz + library which you should install using your distribution's package manager. - databasename is one of: mysql, postgres - web-environment is one of: fastcgi, modperl1, modperl2 + 5) Check to make sure everything was installed properly. -3.2 If there are unsatisfied dependencies, install them by hand or run: + make testdeps - perl sbin/rt-test-dependencies \ - --with- --with- --install - + It might sometimes be necessary to run "make fixdeps" several times + to install all necessary perl modules. -3.3 Check to make sure everything was installed properly: +6a) If this is a NEW installation (not an upgrade): - perl sbin/rt-test-dependencies \ - --with- --with- + As a user with permission to install RT in your chosen directory, + type: -4 Create a group called 'rt' + make install -5a FOR A NEW INSTALLATION: - - As root, type: - make install (replace "make" with the local name for - Make, if you need to) + To configure RT with the web installer, run: - - make initialize-database + /opt/rt4/sbin/rt-server + and follow the instructions. Once completed, you should now have a + working RT instance running with the standalone rt-server. Press + Ctrl-C to stop it, and proceed to Step 7 to configure a recommended + deployment environment for production. - If the make fails, type: - make dropdb - and start over from step 5a + To configure RT manually, you must setup 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 -5b FOR UPGRADING: (Within the RT 3.0.x series) + As a user with permission to read RT's configuration file, type: - As root, type: - make upgrade (replace "make" with the local name for - Make, if you need to) + make initialize-database - 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 + If the make fails, type: -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 + make dropdb -7 Configure the email and web gateways, as described below. + and re-run 'make initialize-database'. -8 Stop and start your webserver, so it picks up your configuration changes. +6b) If you are UPGRADING from a previous installation: - 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. + Before upgrading, always ensure that you have a complete current + backup. If you don't have a current backup, upgrading your database + could accidentally damage it and lose data, or worse. - 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. + If you are using MySQL, please read the instructions in + docs/UPGRADING.mysql as well to ensure that you do not corrupt + existing data. + First, stop your webserver. You may also wish to put incoming email + into a hold queue, to avoid temporary delivery failure messages if + your upgrade is expected to take several hours. -THE WEB INTERFACE ------------------ + Next, install new binaries, config files and libraries by running: -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: - - - ServerName your.rt.server.hostname - DocumentRoot /opt/rt3/share/html - AddDefaultCharset UTF-8 - - # this line applies to Apache2+mod_perl2 only - PerlModule Apache2 Apache::compat - - PerlModule Apache::DBI - PerlRequire /opt/rt3/bin/webmux.pl - - # this section applies to Apache 1 only - - SetHandler perl-script - PerlHandler RT::Mason - - - # this section applies to Apache2+mod_perl2 only - - SetHandler perl-script - PerlHandler RT::Mason - - - SetHandler perl-script - PerlHandler RT::Mason - - - SetHandler perl-script - PerlHandler RT::Mason - - - - - -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/" - | | | - ----/ | | - | | - ---/ | - | - ---/ + make upgrade + This will also prompt you to upgrade your database by running: -BUGS ----- + make upgrade-database + + You should back up your database before running this command. + When you run it, you will be prompted for your previous version of + RT (such as 4.0.23) so that the appropriate set of database + upgrades can be applied. + + If 'make upgrade-database' completes without error, your upgrade + has been successful; you should now run any commands that were + supplied in version-specific UPGRADING documentation. You should + then restart your webserver. + + 7) Configure the web server, as described in docs/web_deployment.pod, + and the email gateway, as described below. + + NOTE: The default credentials for RT are: + User: root + Pass: password + Not changing the root password from the default is a SECURITY risk! + + 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 /opt/rt4/sbin/rt-clean-sessions + + 8) 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. + + 9) Set up automated recurring tasks (cronjobs): + + 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 by + adding the following lines as /etc/cron.d/rt: + + 0 0 * * * root /opt/rt4/sbin/rt-email-digest -m daily + 0 0 * * 0 root /opt/rt4/sbin/rt-email-digest -m weekly + 0 * * * * root /opt/rt4/sbin/rt-email-dashboards + +10) Configure the RT email gateway. 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. + + Add the following lines to /etc/aliases (or your local equivalent) + on your mail server: + + rt: "|/opt/rt4/bin/rt-mailgate --queue general --action correspond --url http://rt.example.com/" + rt-comment: "|/opt/rt4/bin/rt-mailgate --queue general --action comment --url http://rt.example.com/" + + 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: + + perldoc /opt/rt4/bin/rt-mailgate + +11) Set up automatic backups for RT and its data as described in + the docs/backups.pod document. -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 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 +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 --------------------- +MAILING LISTS AND WIKI +---------------------- -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: +To keep up to date on the latest RT tips, techniques and extensions, you +may wish 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: +with the body of the message consisting of only the word: - subscribe + 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 -. +. 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. +The RT wiki, at http://requesttracker.wikia.com/ , is also a potential +resource. -RT WEBSITE ----------- -For current information about RT, check out the RT website at - http://www.bestpractical.com/ +SECURITY +-------- -You'll find screenshots, a pointer to the current version of RT, contributed -patches, and lots of other great stuff. +If you believe you've discovered a security issue in RT, please send an +email to with a detailed description of the +issue, and a secure means to respond to you (such as your PGP public +key). You can find our PGP key and fingerprint at +http://bestpractical.com/security/ -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). +BUGS +---- -Thanks! +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 . + + +# BEGIN BPS TAGGED BLOCK {{{ +# +# COPYRIGHT: +# +# This software is Copyright (c) 1996-2016 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 }}}