X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;f=rt%2FREADME;h=37a6aff672c700744ccb464437e19a30635b8920;hb=43a06151e47d2c59b833cbd8c26d97865ee850b6;hp=9373f69499333bde1e84a6854336ee2137ad1093;hpb=d39d52aac8f38ea9115628039f0df5aa3ac826de;p=freeside.git diff --git a/rt/README b/rt/README index 9373f6949..37a6aff67 100755 --- a/rt/README +++ b/rt/README @@ -1,340 +1,344 @@ -# {{{ BEGIN BPS TAGGED BLOCK -# -# COPYRIGHT: -# -# This software is Copyright (c) 1996-2004 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., 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.) -# -# 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 -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. +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. - Jesse Vincent - Best Practical Solutions, LLC - June 2004 +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. +RT is commercially-supported software. To purchase support, training, +custom development, or professional services, please get in touch with +us at . -REQUIRED PACKAGES: ------------------- + Jesse Vincent + Best Practical Solutions, LLC + March, 2011 -o Perl 5.8.3 or later (http://www.perl.com). - 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 with InnoDB support. - Postgres 7.2 or later. - Oracle 9iR2. - Beta-quality support for Informix and SQLite is also available. +REQUIRED PACKAGES +----------------- +o Perl 5.8.3 or later (http://www.perl.org). -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) + Perl versions prior to 5.8.3 contain bugs that could result in + data corruption. RT won't start on older versions. - 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. +o A supported SQL database - Compiling mod_perl on Apache 1.3.x as a DSO has been known - to have massive stability problems and is not recommended. + Currently supported: Mysql 4.1 or later with InnoDB support. + Postgres 8.1 or later. + Oracle 9iR2 or later. + SQLite 3.0. (Not recommended for production) - mod_perl 1.x 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 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. +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. + 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. GENERAL INSTALLATION -------------------- -This is a rough guide to installing RT. For more detail, you'll -want to read a more comprehensive installation guide at: + 1) Unpack this distribution other than where you want to install RT. + To do this cleanly, run the following command: - http://wiki.bestpractical.com/index.cgi?InstallationGuides + tar xzvf rt.tar.gz -C /tmp -1 Unpack this distribution SOMWHERE OTHER THAN where you want to install RT + 2) Run the "configure" script. To see the list of options, run: - Granted, you've already got it open. To do this cleanly: + ./configure --help - tar xzvf rt.tar.gz -C /tmp + Peruse the options, then rerun ./configure with the flags you want. -2 Run the "configure" script. + 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. - ./configure --help to see the list of options - ./configure (with the flags you want) + 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 3.8.6 to 4.0.x you should + review both the UPGRADING-3.8 and UPGRADING-4.0 file. Similarly, if + you were coming from 3.6.7, you would want to review UPGRADING-3.6, + UPGRADING-3.8 and UPGRADING-4.0 -3 Make sure that RT has everything it needs to run: + It is particularly important that you read the warnings at the top of + UPGRADING-4.0 for some common issues. -3.1 Check for missing dependencies: + 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. - make testdeps + 3) Make sure that RT has the Perl and system libraries it needs to run. + Check for missing dependencies by running: + + make testdeps -3.2 If there are unsatisfied dependencies, install them by hand or run: + 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 -3.3 Check to make sure everything was installed properly: - - make testdeps + Some modules require user input or environment variables to install + correctly, so it may be necessary to install them manually. - It might sometimes be necessary to run "make fixdeps" several times - to install all necessary perl modules. + If you are installing with CPAN module older than 1.84, you will + need to start CPAN (by running perl -MCPAN -e shell) and upgrade the + CPAN shell with: -4 Create a group called 'rt' + install CPAN -5a FOR A NEW INSTALLATION: - - As root, type: - make install - - make initialize-database + If you are unsure of your CPAN version, it will be printed when you + run the shell. - If the make fails, type: - make dropdb - and start over from step 5a + If you are having trouble installing GD or Graphviz, you should + install gd-devel and the graphviz libraries using your + distribution's package manager. -5b FOR UPGRADING: (Within the RT 3.x series) + 5) Check to make sure everything was installed properly. - Read through the UPGRADING document included in this distribution. - It may contain important instructions which will help you upgrade - RT safely. + make testdeps - As root, type: - make upgrade + It might sometimes be necessary to run "make fixdeps" several times + to install all necessary perl modules. - This will build new binaries, config files and libraries without - overwriting your RT database. +6a) If this is a NEW installation (not an upgrade): - You may also need to update RT's database. To find out, type: + As a user with permission to install RT in your chosen directory, + type: - ls etc/upgrade + make install - 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/ - /opt/rt3/sbin/rt-setup-database --action acl \ - --datadir etc/upgrade/ - /opt/rt3/sbin/rt-setup-database --action insert \ - --datadir etc/upgrade/ + To configure RT with the web installer, run: + /opt/rt4/sbin/rt-server -5c FOR UPGRADING: (From RT 2.0.x) + 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. - Download the RT2 to RT3 migration tools from: + 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 - http://bestpractical.com/pub/rt/devel/rt2-to-rt3.tar.gz + As a user with permission to read RT's configuration file, type: - Follow the included instructions. + make initialize-database -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 + If the make fails, type: -7 Configure the email and web gateways, as described below. + make dropdb -8 Stop and start your webserver, so it picks up your configuration changes. + and re-run 'make initialize-database'. - 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. +6b) If you are UPGRADING from a previous installation: - 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. + 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. + If you are using MySQL, please read the instructions in + docs/UPGRADING.mysql as well to ensure that you do not corrupt + existing data. -THE WEB INTERFACE ------------------ + 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. -RT's web interface is based around HTML::Mason, which works well with -the mod_perl perl interpreter within Apache httpd and FastCGI + Next, install new binaries, config files and libraries by running: -mod_perl --------- + make upgrade -To install RT with mod_perl, you'll need to add a few lines to your -Apache configuration file telling it about RT: + This will also prompt you to upgrade your database by running: - - ServerName your.rt.server.hostname - DocumentRoot /opt/rt3/share/html - AddDefaultCharset UTF-8 + make upgrade-database - # these four lines apply to Apache2+mod_perl2 only: {{{ - PerlSetVar MasonArgsMethod CGI - PerlModule Apache2 Apache::compat - RewriteEngine On - RewriteRule ^(.*)/$ $1/index.html - # }}} + 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 3.6.4) so that the appropriate set of database + upgrades can be applied. - PerlModule Apache::DBI - PerlRequire /opt/rt3/bin/webmux.pl + Finally, clear the Mason cache dir: - - SetHandler perl-script - PerlHandler RT::Mason - - + rm -fr /opt/rt4/var/mason_data/obj -FastCGI -------- + You may then start your web server again. -Installation with FastCGI is a little bit more complex and is documented -in detail at http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration + 7) Configure the web server, as described in docs/web_deployment.pod, + and the email gateway, as described below. -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. + NOTE: The default credentials for RT are: + User: root + Pass: password + Not changing the root password from the default is a SECURITY risk! -To install RT with FastCGI, you'll need to add a few lines to your -Apache configuration file telling it about RT: + 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 - # 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 + 8) Set up users, groups, queues, scrips and access control. - FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120 + 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. - AddHandler fastcgi-script fcgi - ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/ - - + 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 as + follows: + crontab -e # as the RT administrator (probably root) + # insert the following lines: + 0 0 * * * /opt/rt4/sbin/rt-email-digest -m daily + 0 0 * * 0 /opt/rt4/sbin/rt-email-digest -m weekly + 0 * * * * /opt/rt4/sbin/rt-email-dashboards -SETTING UP THE MAIL GATEWAY ---------------------------- +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. -RT can accept incoming email using a simple program run as a "pipe" -by your mail server. + Add the following lines to /etc/aliases (or your local equivalent) + on 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. - -Add the following lines to /etc/aliases (or your local equivalent) : + 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/" -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/" - | | | - ----/ | | - | | - ---/ | - | - ---/ + 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 -BUGS ----- + If your webserver uses SSL, rt-mailgate will require several new + Perl libraries. RT can detect and install these for you automatically + if you include --enable-ssl-mailgate when running configure and then + run make fixdeps as described in step 4. It is safe to rerun configure + and make fixdeps after you have installed RT, you should be sure to include + all the arguments you used in step 2 plus --enable-ssl-mailgate. -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 or by writing to -sales@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.bestpractical.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.bestpractical.com. Subscribe to it with instructions -similar to those above. +. 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. -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 -. +The RT wiki, at http://requesttracker.wikia.com/ , is also a potential +resource. -RT WEBSITE ----------- +SECURITY +-------- + +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/ + + +BUGS +---- -For current information about RT, check out the RT website at - http://www.bestpractical.com/ +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 . -You'll find screenshots, a pointer to the current version of RT, contributed -patches, and lots of other great stuff. +# BEGIN BPS TAGGED BLOCK {{{ +# +# COPYRIGHT: +# +# This software is Copyright (c) 1996-2012 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 }}}