-# BEGIN LICENSE BLOCK
-#
-# Copyright (c) 1996-2003 Jesse Vincent <jesse@bestpractical.com>
-#
-# (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 <sales@bestpractical.com>.
-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-<databasename> --with-<web-environment>
+ 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-<databasename> --with-<web-environment> --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-<databasename> --with-<web-environment>
+ 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:
-
-<VirtualHost your.ip.address>
- 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
- <Location />
- SetHandler perl-script
- PerlHandler RT::Mason
- </Location>
-
- # this section applies to Apache2+mod_perl2 only
- <FilesMatch "\.html$">
- SetHandler perl-script
- PerlHandler RT::Mason
- </FilesMatch>
- <LocationMatch "/Attachment/">
- SetHandler perl-script
- PerlHandler RT::Mason
- </LocationMatch>
- <LocationMatch "/REST/">
- SetHandler perl-script
- PerlHandler RT::Mason
- </LocationMatch>
-</VirtualHost>
-
-
-
-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/"
- | | |
- <queue-name>----/ | |
- | |
- <correspond or comment depending on whether | |
- the mail should be resent to the requestor>---/ |
- |
- <URL for RT's web interface>---/
+ 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
+<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.
-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
-<jesse@bestpractical.com>.
+<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.
+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 <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/
-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 <rt-bugs@bestpractical.com>.
+
+
+# BEGIN BPS TAGGED BLOCK {{{
+#
+# COPYRIGHT:
+#
+# This software is Copyright (c) 1996-2016 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