path: root/rt/README

# {{{ BEGIN BPS TAGGED BLOCK
# 
# COPYRIGHT:
#  
# This software is Copyright (c) 1996-2004 Best Practical Solutions, LLC 
#                                          <jesse@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., 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. 

        Jesse Vincent
        Best Practical Solutions, LLC
        June 2004


REQUIRED PACKAGES:
------------------

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.


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)

        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.

        Compiling mod_perl on Apache 1.3.x as a DSO has been known 
         to have massive stability problems and is not recommended.

        mod_perl 1.x must be build with EVERYTHING=1

        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
--------------------

This is a rough guide to installing RT. For more detail, you'll
want to read a more comprehensive installation guide at:

    http://wiki.bestpractical.com/index.cgi?InstallationGuides

1   Unpack this distribution SOMWHERE OTHER THAN where you want to install RT

        Granted, you've already got it open. To do this cleanly:

                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)

3   Make sure that RT has everything it needs to run:

3.1   Check for missing dependencies:

        make testdeps        

3.2   If there are unsatisfied dependencies, install them by hand or run:

        make fixdeps

3.3   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.

4   Create a group called 'rt'

5a  FOR A NEW INSTALLATION: 
        
        As root, type:
                 make install   
                       
                 make initialize-database 

        If the make fails, type:
                make dropdb 
        and start over from step 5a

5b  FOR UPGRADING: (Within the RT 3.x series)

        Read through the UPGRADING document included in this distribution.
        It may contain important instructions which will help you upgrade
        RT safely.

        As root, type: 
                make upgrade    

        This will build new binaries, config files and libraries without
        overwriting your RT database. 

        You may also need to update RT's database.  To find out, type:

           ls etc/upgrade

        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/<version>
            /opt/rt3/sbin/rt-setup-database --action acl \
                --datadir etc/upgrade/<version>
            /opt/rt3/sbin/rt-setup-database --action insert \
                 --datadir etc/upgrade/<version>


5c  FOR UPGRADING: (From RT 2.0.x)

    Download the RT2 to RT3 migration tools from:

    http://bestpractical.com/pub/rt/devel/rt2-to-rt3.tar.gz

    Follow the included instructions.

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

7   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
    
9   Configure RT per the instructions in RT's manual.

    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.


THE WEB INTERFACE
-----------------

RT's web interface is based around HTML::Mason, which works well with
the mod_perl perl interpreter within Apache httpd and FastCGI

mod_perl
--------

To install RT with mod_perl, you'll need to add a few lines to your 
Apache configuration file telling it about RT:

<VirtualHost your.ip.address>
    ServerName your.rt.server.hostname
    DocumentRoot /opt/rt3/share/html
    AddDefaultCharset UTF-8

    # these four lines apply to Apache2+mod_perl2 only: {{{
    PerlSetVar MasonArgsMethod CGI
    PerlModule Apache2 Apache::compat
    RewriteEngine On
    RewriteRule ^(.*)/$ $1/index.html
    # }}}

    PerlModule Apache::DBI
    PerlRequire /opt/rt3/bin/webmux.pl

    <Location />
        SetHandler perl-script
        PerlHandler 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:

<VirtualHost rt.example.com>

   # 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

   FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120

   AddHandler fastcgi-script fcgi
   ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
   
</VirtualHost>



SETTING UP THE MAIL GATEWAY 
---------------------------

RT can accept incoming email using a simple program run as a "pipe" 
by 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/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>---/


BUGS
----

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 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
--------------------

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:

         rt-users-request@lists.bestpractical.com 

With the body of the message consisting of only the word:

        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>.


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.