Request Tracker

This article has some todo items:

Update Apache FastCGI instructions
Update Lighttpd instructions
Add instructions about fetching emails/generating tickets

Request Tracker (RT) is a battle-tested issue tracking system which thousands of organizations use for bug tracking, help desk ticketing, customer service, workflow processes, change management, network operations, youth counselling and even more. Organizations around the world have been running smoothly thanks to RT for over 10 years.

About This Guide

This guide was written using the latest version of RT available, which at the time of this writing is 4.2.9.

This guide assumes that you are familiar enough with Apache or Lighttpd and will not delve into the details of either.

Whether or not you use virtual hosting holds no bearing on the bulk of this guide. It will be noted if there's something significantly different that must be done in a virtual hosting environment.

Installation

USE flags

USE flags for www-apps/rt RT is an enterprise-grade ticketing system

`+apache`	Add www-servers/apache support
`+postgres`	Add support for the postgresql database
`fastcgi`	Add support for the FastCGI interface
`lighttpd`	Add www-servers/lighttpd support
`mysql`	Add mySQL Database support
`nginx`	Add www-servers/nginx support
`vhosts`	Add support for installing web-based applications into a virtual-hosting environment

Data provided by the Gentoo Package Database · Last update: 2024-10-01 16:22 More information about USE flags

Requirements

RT requires a database backend and works equally well with either MySQL or PostgreSQL. You must enable at most one of their USE flags:

root #echo "www-apps/rt mysql" >> /etc/portage/package.use

root #echo "www-apps/rt postgres" >> /etc/portage/package.use

RT also requires a Web server. The default is to run on Apache, but you can use lighttpd. To use lighttpd, you must enable its USE flag:

root #echo "www-apps/rt lighttpd" >> /etc/portage/package.use

Emerge

Many of the packages RT depends on, including RT's own package, are keyword masked. Use the following command to have a patch automatically generated for you.

root #emerge -av --autounmask-write =www-apps/rt-4.2.9

Once the previous command has finished, use dispatch-conf to apply the patch:

root #dispatch-conf

Run emerge again:

root #emerge -av www-apps/rt

If you have the vhosts USE flag enabled, you'll need to run webapp-config to finish the installation:

root #webapp-config -I -h localhost -d rt rt 4.2.9

Setup and Configuration

Database

RT provides a script called rt-setup-database which creates the initial database and a database user for you.

root #/var/www/localhost/rt-4.2.9/sbin/rt-setup-database --action init --dba dbasuperuser --prompt-for-dba-password

In order to create or update your RT database, this script needs to connect to your
Pg instance on localhost (port '') as postgres
Please specify that user's database password below. If the user has no database
password, just press return.

Password: 
Working with:
Type:   Pg
Host:   localhost
Port:
Name:   rt4
User:   rt_user
DBA:    postgres
Now creating a Pg database rt4 for RT.
Done.
Now populating database schema.
Done.
Now inserting database ACLs.
Done.
Now inserting RT core system objects.
Done.
Now inserting data.
Done inserting data.
Done.

Configuring RT

RT uses an overlay system for configuration. This means that the default configuration is declared in /var/www/localhost/rt-4.2.9/etc/RT_Config.pm, and that custom configurations are declared in /var/www/localhost/rt-4.2.9/etc/RT_SiteConfig.pm. RT_SiteConfig.pm will not exist until you create it. Any custom configuration in RT_SiteConfig.pm will be preserved in upgrades, while the default configurations, RT_Config.pm, will be overwritten.

You can copy just certain sections from RT_Config.pm to RT_SiteConfig.pm, or you can create a full copy.

root #

cd /var/www/localhost/rt-4.2.9/etc

root #

cp RT_Config.pm RT_SiteConfig.pm

root #

chmod u+w RT_SiteConfig.pm

root #$EDITOR RT_SiteConfig.pm

The configuration file is well documented, but you may want to consult the official documentation.

Sendmail Alternatives

If you don't have, or don't want, a full-blown SMTP server running, you can use a lightweight client to send the emails instead as long as it provides a sendmail-compatible executable. You can pass specific options via your RT_SiteConfig.pm.

Configuring the Web Server

Request Tracker can be run on any PSGI compliant server. However, Apache and Lighttpd are proven platforms.

Apache

Only information pertinent to RT will be covered. Additional information about Apache is covered elsewhere.

There's little information about which method works better for RT on Apache, and benchmarks have shown mod_perl and FastCGI to be nearly equal.

mod_perl

Save the following snippet within the individual VirtualHost tags you installed RT to or /etc/apache2/vhosts.d/default_vhost.include.

CODE

# Replace /rt with the proper URL path after the domain name
<Location /rt>
    SetHandler modperl
    PerlResponseHandler Plack::Handler::Apache2
    # Correct this path
    PerlSetVar psgi_app /var/www/localhost/rt-4.2.9/sbin/rt-server
</Location>

<Perl>
    use Plack::Handler::Apache2;
    # Correct this one, too
    Plack::Handler::Apache2->preload("/var/www/localhost/rt-4.2.9/sbin/rt-server");
</Perl>

In case you haven't done so already, instruct Apache to start with mod_perl enabled.

FILE /etc/conf.d/apache2

APACHE2_OPTS="... -D PERL"

You may need to change the owner and group of RT's Mason data directory.

root #chown -R apache:apache /var/www/localhost/rt-4.2.9/var/mason_data

mod_fastcgi

NOTE: If you wish to use mod_fastcgi, you need to instruct webapp-config to install rt with appropriate permissions. Edit /etc/vhosts/webapp-config:

FILE /etc/vhosts/webapp-config

VHOST_DEFAULT_UID="rt"
VHOST_DEFAULT_GID="rt"

Save the following snippet within the individual VirtualHost tags you installed RT to or /etc/apache2/vhosts.d/default_vhost.include.

CODE

# You may need to tell FastCGI to put its temporary files somewhere sane
#FastCgiIpcDir /tmp

# Match the path to the file system location
FastCgiServer /var/www/localhost/rt-4.2.9-r1/sbin/rt-server.fcgi -processes 5 -idle-timeout 300

# Match the first path to the URL where RT is actually available
# Match the second path to the file system location
ScriptAlias /rt /var/www/localhost/rt-4.2.9-r1/sbin/rt-server.fcgi/

# Match the path to the URL where RT is actually available
<Location /rt>
    <IfVersion >= 2.4> # For Apache 2.4
        Require all granted
    </IfVersion>
    <IfVersion < 2.4>  # For Apache 2.2
        Order allow,deny
        Allow from all
    </IfVersion>

    Options +ExecCGI
    SetHandler fastcgi-script
</Location>

Edit /etc/conf.d/apache2 to instruct apache2 to start with FASTCGI and enabled.

FILE /etc/conf.d/apache2

APACHE2_OPTS="-D FASTCGI"

If this is your first time installing apache, you will want it to start on bootup.

root #rc-update add apache2 default

Restart apache so that all changes made so far will take effect.

root #/etc/init.d/apache2 restart

lighttpd (untested)

You can run RT on lighttpd + fastcgi. The ebuild will install an initscript /etc/init.d/rt and a config file /etc/conf.d/rt.

NOTE: If you wish to use mod_fastcgi, you need to instruct webapp-config to install rt with appropriate permissions. Edit /etc/vhosts/webapp-config:

FILE /etc/vhosts/webapp-config

VHOST_DEFAULT_UID="rt"
VHOST_DEFAULT_GID="rt"

You will need to edit /etc/conf.d/rt to set RTPATH to the root of your installation. You shouldn't need to edit anything else in that file.

Also note that, under the default configuration, the socket in $FCGI_SOCKET_PATH is owned by rt:lighttpd, and is chmod-ded to g+rwx. This means that user lighttpd needs to be in the rt group. One way to do that is to use vigr. If you don't like that, edit /etc/init.d/rt to suit your needs.

You will also need to edit /etc/lighttpd.conf to enable mod_fastcgi.

Uncomment mod_fastcgi under server.modules
set server.document-root
set fastcgi.server to something like this:

FILE /etc/lighttpd.conf

fastcgi.server = ( "/rt" =>
 ( "rt" =>
 (
 "socket" => "/var/www/localhost/rt-3.6.1/var/appSocket",
 "check-local" => "disable"
 )
 )
 )

Be sure to set the correct path to socket (same as $FCGI_SOCKET_PATH in /etc/conf.d/rt).

Now, start rt and lighttpd:

root #

/etc/init.d/rt start

root #/etc/init.d/lighttpd start

If things don't seem to be working, check the lighttpd logs in /var/log/lighttpd and edit /etc/init.d/rt as per the comments in the file to make the rt daemon more verbose.

Note: you should be able to use this initscript with any fastcgi-enabled webserver. Please send me an email if you get rt to work with any other webserver.

Feeding Emails Into RT

There are a variety of methods to feed email into RT. If you have an MTA -- such as Postfix, Exim, or the real Sendmail -- you'll be better off using it. Follow the MTA On Same Server portion of this section.

However, if you're fetching email from a remote server, you don't have to install an MTA, just 2 or 3 smaller utilities. Follow the Without An MTA portion of this section.

MTA On Same Server

TODO

Without An MTA

There are 2 utilities you'll need: net-mail/fetchmail and mail-mta/msmtp. In case you're using aliases delivered to the same email box, you'll want mail-filter/procmail as well.

FILE /etc/fetchmailrcConfiguration file for fetchmail

set logfile "/var/log/fetchmail.log"
set no bouncemail

poll imap.example.com protocol IMAP;

user "rt@example.com" there with password "password"
ssl
sslproto SSL3
nofetchall
keep
no rewrite
mda "/usr/bin/procmail -f %F /var/www/localhost/rt-4.2.9/etc/procmailrc";

FILE /var/www/localhost/etc/rt-4.2.9/etc/procmailrcConfiguration for procmail

LOGFILE=/var/log/procmail.log

:0
* ^To:.*help@example.com
| /var/www/localhost/rt-4.2.9/bin/rt-mailgate --url http://localhost/rt --queue Help --action correspond

:0
* ^To:.*help-comment@example.com
| /var/www/localhost/rt-4.2.9/bin/rt-mailgate --url http://localhost/rt --queue Help --action comment

Log In

Use your browser to log into RT. Username is root, and password is password. Change your password.

Special Thanks

Thank you to all those who worked on the original version of this guide.