-$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 <jesse@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.
-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 <version> where
- <version> 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"
- | |
- <queue-name>----/ |
- |
- <correspond or comment depending on whether |
- the mail should be resent to the requestor>---/
+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:
<VirtualHost your.ip.address>
-DocumentRoot /path/to/rt2/WebRT/html
-ServerName your.rt.server.hostname
-PerlModule Apache::DBI
-PerlFreshRestart On
-PerlRequire /path/to/rt2/bin/webmux.pl
-<Location />
- SetHandler perl-script
- PerlHandler RT::Mason
-</Location>
+ 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
+
+ <Location /NoAuth/images>
+ SetHandler default
+ </Location>
+ <Location />
+ SetHandler perl-script
+ PerlHandler RT::Mason
+ </Location>
</VirtualHost>
-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.
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+<VirtualHost your.ip.address>
+ 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"
+ <Location /NoAuth/images>
+ SetHandler default
+ </Location>
+ <Location />
+ SetHandler perl-script
+ PerlResponseHandler RT::Mason
+ </Location>
+</VirtualHost>
-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
-<URL:http://fsck.com/rt2/NoAuth/Errata.html>. 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 <URL:http://fsck.com/rt2/NoAuth/Buglist.html>.
-(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.
+<VirtualHost rt.example.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/
+</VirtualHost>
-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
---------------------
+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
-<jesse@bestpractical.com>.
-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
+<sales@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 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
+<rt-devel@lists.bestpractical.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>.
+
+
+
+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
- <jesse@bestpractical.com>
- 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
+# <sales@bestpractical.com>
+#
+# (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 }}}
projects / freeside.git / blobdiff