RT on DreamHost

Request Tracker from Best Practical is a very popular and flexible ticketing system. In this tutorial, we’re going to cover a basic installation of RT on a DreamHost shared hosting account. This is slightly more involved than a standard RT installation, which would generally be done on a dedicated server and require elevated permissions to complete the installation. While the shared environment at DreamHost won’t be powerful enough for a high-traffic site, for low volume help desks this is a great option.

Prerequisites

You will need a few things in place to follow this document. All of them can be created via the DreamHost web panel.

First, a domain with web hosting. This tutorial is going to cover installing RT on it’s own domain, like rt.example.com. RT can also be installed to a sub-directory of an existing site, but that won’t be covered. Additionally, the web hosting user that runs the side will need to have shell access enabled. This is necessary so you can SSH to the hosting server as the web account to perform the installation and setup.

The next thing you’ll need is a MySQL database. Just like the domain, this should be a database used solely for RT.

Finally, as RT is heavily integrated with email, you’ll need at least one email address. Two are recommended, as RT can make use of separate email address for ticket correspondence versus ticket comments. These are usually something like help@example.com for correspondence and comment@example.com for comments. If you plan on having multiple ticket queues with their own email addresses, you will want two per queue.

Preparation

The rest of the tutorial assumes you have connected to your DreamHost shared server with SSH as the web user. If you connect to the server but never get a command prompt, the user is likely setup for SFTP access only. If that’s the case, you’ll need to go back to the web panel and enable full shell access.

Setup Your Environment

First, you’ll need to set a handful of environment variables. These can either be added directly to your .bashrc file, or you can create a separate rt.env file and source that as needed.

# what version of rt are we using?
export RT_VERSION="4.4.3"

# where will rt be installed?
export RT_HOME="${HOME}/opt/rt-${RT_VERSION}"
export RT_LOCAL="${RT_HOME}/local"
export RT_LOCAL_LIB="${RT_LOCAL}/lib"

# ensure perl modules are installed in the rt directory so they can be found
export PERL5LIB="${RT_LOCAL_LIB}"
export PERL_MB_OPT="--install_base ${RT_LOCAL} --install_path lib=${RT_LOCAL_LIB} --install_path arch=${RT_LOCAL_LIB}"
export PERL_MM_OPT="INSTALL_BASE=${RT_LOCAL} INSTALLPRIVLIB=${RT_LOCAL_LIB} INSTALLARCHLIB=${RT_LOCAL_LIB} INSTALLSITELIB=${RT_LOCAL_LIB} INSTALLSITEARCH=${RT_LOCAL_LIB}"

Once you’ve added those, don’t forget to source the file so the variables are added to your current session.

Get the Source Code

Next, you’ll need to get the source code for RT. The commands below will create a src directory under your home directory, then download and extract the RT source code.

# create a directory for source
test -e ~/src || mkdir ~/src && cd ~/src

# download and extract the rt source
wget https://download.bestpractical.com/pub/rt/release/rt-${RT_VERSION}.tar.gz
tar xvf rt-${RT_VERSION}.tar.gz

Installation

Now that you have the source downloaded and extracted, you’re ready to get RT installed. The first step is to do the basic configuration so it knows basic information about the desired installation environment. Note that the ${USER} variable in the command hasn’t been set by us; it is a Bash provided variable that expands to your current username. Similarly, $(id -gn) runs the id command and tells it to print your users’s primary group name.

cd rt-${RT_VERSION}
./configure --prefix=${RT_HOME} --enable-gd --with-web-user=${USER} --with-web-group=$(id -gn) --with-bin-owner=$USER --with-libs-owner=$USER --with-libs-group=$(id -gn)

Dependencies

RT has many dependencies. Before it can be installed, you’ll first have to install the dependencies. It’s important to use cpan for this instead of perl -MCPAN, as the latter is not properly recognized by the DreamHost process watcher and will be terminated if it exceeds your allotted resource limits. (See this DreamHost document for more details.)

The first two cpan commands ensure that two specific dependencies get installed first. Generally, cpan should handle dependencies properly. However, I’ve experienced failed installs when these specific modules aren’t already in place. Once those have been installed, the output of RT’s dependency check script is parsed and fed as a list of modules to cpan install.

cpan install Proc::Wait3
cpan install Parallel::Prefork
cpan install $(make testdeps 2>/dev/null | awk '/MISSING$/ {print $1}' | sort -u)

Once that completes, all dependencies should be installed. You can verify this by running make testdeps. At the end of the output, it should show “All dependencies have been found.”

Install RT

With all the dependencies in place, you can now install RT.

make install

That will install RT to the directory given to the configure command previously. If you used the values without modification, that will be under opt/rt-4.4.3 in your home directory. To make upgrades easier, it’s helpful to have a symlink to the current version.

cd ~/opt
ln -s rt-${RT_VERSION} rt

Next, we need to ensure the web server can run the RT application. To do this, you’ll need to create a script in your web site’s document root that runs the RT FastCGI script. In the example below, replace rt.example.com with your RT domain name.

cd ~/rt.example.com
cat > index.fcgi [<FCGI
#!/bin/bash

exec ~/opt/rt/sbin/rt-server.fcgi
FCGI
chmod 0755 index.fcgi

Configuration

With everything installed, you now need to perform your basic configuration. You do this by editing ${RT_HOME}/etc/RT_SiteConfig.pm. Here is a sample.

use utf8;

# general settings
Set($rtname,       'example.com');
Set($Organization, 'example.com');
Set($Timezone,     'EST5EDT');

# email settings
Set($CorrespondAddress,  'help@example.com');
Set($CommentAddress,     'comment@example.com');

# web settings
Set($WebDomain, 'rt.example.com');
Set($WebPort,    443);

# database settings
Set($DatabaseType,     'mysql');
Set($DatabaseHost,     'mysql.example.com');
Set($DatabaseName,     'database_name');
Set($DatabaseAdmin,    'database_user');
Set($DatabaseUser,     'database_user');
Set($DatabasePassword, 'database_password');

Populate the Database

The RT setup scripts attempt to create and populate the database. This won’t work as creating the database requires elevated MySQL permissions. However, since you’ve already created a database via the DreamHost web panel, that part isn’t needed anyway. The commands below handle everything the normal RT setup would do, but skip the database creation.

cd ${RT_HOME}
./sbin/rt-setup-database --action schema
./sbin/rt-setup-database --action core data
./sbin/rt-setup-database --action insert --datafile etc/initialdata

Complete the Setup

At this point, you have RT installed and configured. All that’s left is to browse to your RT site and complete the configuration using their web based setup.

Email Integration

A huge feature of RT is the excellent email integration. Since your DreamHost shell account won’t be able to directly receive email, you’ll instead need to have the email pulled to it. I cover this in my Fetchmail on DreamHost tutorial. When walking through that, you’ll need to use ${RT_HOME}/bin/rt-mailgate --action correspond --queue help --url https://your.rt.url/; obviously replacing the queue name and RT URL. The --action argument can be either correspond or comment. The difference is that a comment is only sent to the users that work the queue, not the requestor or others.

Conclusion

If you’ve completed all the above steps, you should now have RT running on your shared DreamHost account. If you have any questions or issues, or would like to suggest a topic, please reach out via the Contact link at the top of the page.