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.
+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 sales@bestpractical.com.
-
- Jesse Vincent
- Best Practical Solutions, LLC
- March, 2005
+us at <sales@bestpractical.com>.
REQUIRED PACKAGES
o Perl 5.8.3 or later (http://www.perl.org).
- Perl versions prior to 5.8.3 contain bugs that could result
- in data corruption. RT won't start on older versions.
+ Perl versions prior to 5.8.3 contain bugs that could result in
+ data corruption. RT won't start on older versions.
o A supported SQL database
- Currently supported: Mysql 4.0.13 or later with InnoDB support.
- Postgres 7.2 or later.
+ 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)
o Apache version 1.3.x or 2.x (http://httpd.apache.org)
- with mod_perl -- (http://perl.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.
- 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.
+ 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 (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 other than where you want to install RT
+ 2) Run the "configure" script. To see the list of options, run:
- To do this cleanly, run the following command:
+ ./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
- 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.
+ It is particularly important that you read the warnings at the top of
+ UPGRADING-4.0 for some common issues.
- If you're upgrading RT then it worth to read UPGRADING document at this
- moment. Some extension you're using may have been integrated into
- core. It's recommended to use 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.
+ 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.
+ 3) Make sure that RT has the Perl and system libraries 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:
-
- As a user with permission to install RT in your chosen directory, type:
-
- make install
-
- 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
-
- As a user with permission to read RT's configuration file, type:
-
- make initialize-database
+ make testdeps
- If the make fails, type:
+ 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 dropdb
+ make fixdeps
- and start over from step 6
+ Some modules require user input or environment variables to install
+ correctly, so it may be necessary to install them manually.
-7 If you're upgrading from RT 3.0 or newer:
+ 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:
- Read through the UPGRADING document included in this distribution. If
- you're using MySQL, read through UPGRADING.mysql as well.
+ install CPAN
- It includes special upgrade instructions that will help you get this
- new version of RT up and running smoothly.
+ If you are unsure of your CPAN version, it will be printed when you
+ run the shell.
- As a user with permission to install RT in your chosen installation
- directory, type:
+ If you are having trouble installing GD or Graphviz, you should
+ install gd-devel and the graphviz libraries using your
+ distribution's package manager.
- make upgrade
+ 5) Check to make sure everything was installed properly.
- This will install new binaries, config files and libraries without
- overwriting your RT database.
+ make testdeps
- 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
+ It might sometimes be necessary to run "make fixdeps" several times
+ to install all necessary perl modules.
- 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).
+6a) If this is a NEW installation (not an upgrade):
- 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
+ As a user with permission to install RT in your chosen directory,
+ type:
- You should back up your database before running this command.
+ make install
- /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
+ To configure RT with the web installer, run:
- Clear mason cache dir:
+ /opt/rt4/sbin/rt-server
- rm -fr /opt/rt3/var/mason_data/obj
-
- Stop and start web-server.
-
-
-8 If you're upgrading from RT 2.0:
-
- Use the RT::Extension::RT2toRT3 module to upgrade to the current RT
- release. You can download it from CPAN here:
- http://search.cpan.org/dist/RT-Extension-RT2toRT3/
-
-9 Configure the email and web gateways, as described below.
-
- NOTE: root's password for the web interface is "password"
- (without the quotes). Not changing this is a SECURITY risk!
-
-10 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/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
+ 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.
+ 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
-11 Set up users, groups, queues, scrips and access control.
+ As a user with permission to read RT's configuration file, type:
- 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.
+ make initialize-database
+ If the make fails, type:
+ make dropdb
+ and re-run 'make initialize-database'.
-SETTING UP THE WEB INTERFACE
-----------------------------
+6b) If you are UPGRADING from a previous installation:
-RT's web interface is based around HTML::Mason, which works well with
-the mod_perl perl interpreter within Apache httpd and FastCGI.
+ 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.
-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
+ 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.
-mod_perl 1.xx
--------------
+ Next, install new binaries, config files and libraries by running:
-WARNING: mod_perl 1.99_xx is not supported.
+ make upgrade
-See below configuration instructions for mod_perl 2.x
+ This will also prompt you to upgrade your database by running:
-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:
+ make upgrade-database
- perl -MCPAN -e'install "Apache::DBI"'
+ 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.
-Next, add a few lines to your Apache 1.3.xx configuration file, so that
-it knows where to find RT:
+ Finally, clear the Mason cache dir:
-<VirtualHost your.ip.address>
- ServerName your.rt.server.hostname
+ rm -fr /opt/rt4/var/mason_data/obj
- DocumentRoot /opt/rt3/share/html
- AddDefaultCharset UTF-8
+ You may then start your web server again.
- # optional apache logs for RT
- # ErrorLog /opt/rt3/var/log/apache.error
- # TransferLog /opt/rt3/var/log/apache.access
+ 7) Configure the web server, as described in docs/web_deployment.pod,
+ and the email gateway, as described below.
- PerlModule Apache::DBI
- PerlRequire /opt/rt3/bin/webmux.pl
+ NOTE: The default credentials for RT are:
+ User: root
+ Pass: password
+ Not changing the root password from the default is a SECURITY risk!
- <Location /NoAuth/images>
- SetHandler default
- </Location>
- <Location />
- SetHandler perl-script
- PerlHandler RT::Mason
- </Location>
-</VirtualHost>
+ 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:
-mod_perl 2.xx
--------------
+ perldoc /path/to/rt/sbin/rt-clean-sessions
-WARNING: mod_perl 1.99_xx is not supported.
+ 8) Set up users, groups, queues, scrips and access control.
-Add a few lines to your Apache 2.xx configuration file, so that
-it knows where to find RT:
-
-<VirtualHost your.ip.address>
- ServerName your.rt.server.hostname
-
- DocumentRoot /opt/rt3/share/html
- AddDefaultCharset UTF-8
-
- # optional apache logs for RT
- # ErrorLog /opt/rt3/var/log/apache2.error
- # TransferLog /opt/rt3/var/log/apache2.access
-
- PerlRequire "/opt/rt3/bin/webmux.pl"
-
- <Location /NoAuth/images>
- SetHandler default
- </Location>
- <Location />
- SetHandler perl-script
- PerlResponseHandler RT::Mason
- </Location>
-</VirtualHost>
-
-FastCGI
--------
-
-Installation with FastCGI is a little bit more complex and is documented
-in detail at http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration
-
-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:
-
-
-# Tell FastCGI to put its temporary files somewhere sane.
-FastCgiIpcDir /tmp
-
-FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120
-
-<VirtualHost rt.example.com>
- ServerName your.rt.server.hostname
-
- # Pass through requests to display images
- Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
-
- AddHandler fastcgi-script fcgi
- ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
-</VirtualHost>
+ 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 as
+ follows:
-SETTING UP THE MAIL GATEWAY
----------------------------
+ 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
-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.
+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:
+ Add the following lines to /etc/aliases (or your local equivalent)
+ on your mail server:
-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/"
+ 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:
+ 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/rt3/bin/rt-mailgate
+ perldoc /opt/rt4/bin/rt-mailgate
+ 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.
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 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
+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.
+MAILING LISTS AND WIKI
+----------------------
-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.
-
-
-
-RT-USERS MAILING LIST
----------------------
-
-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
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.
+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.
+
-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>.
+SECURITY
+--------
+If you believe you've discovered a security issue in RT, please send an
+email to <security@bestpractical.com> 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
----
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.
+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@bestpractical.com>.
# BEGIN BPS TAGGED BLOCK {{{
-#
+#
# COPYRIGHT:
-#
-# This software is Copyright (c) 1996-2009 Best Practical Solutions, LLC
-# <jesse@bestpractical.com>
-#
+#
+# This software is Copyright (c) 1996-2014 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
# 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