Setting up RT on a VPS

Easy way to set up an issue tracking system

Subject

We're going to set up an instance of Request Tracker (RT) on a VPS or a dedicated server. It is not targetted at shared hosting with no shell access, so you can skip this article if this is the type of server you have. We will skip all the other common services required for RT to function and focus on getting the system itself up and running. By the end of this guide, a standalone RT instance will be fully operational.

Prerequisites

  • Basic Linux/Unix command line proficiency.
  • A database server (like PostgreSQL) already installed and configured. Access to database superuser (password-based) will be required.
  • A dedicated unix user that will run RT code (no superuser access). A couple of operating system components will need to be installed, so at least help from an administrator will be required.
  • Unix programs: curl, autoconf, git, gnu make, gnupg1, openssl-devel.
  • One to two hours of free time.

What is RT?

Request Tracker is an open source issue tracking system best suited for tracking issues from outside your organization, as it can be interacted with purely by email. I personally like it because even though it's coming from a company (as opposed to being a community project), it has no paid tier or "Enterprise Edition". Once you're able to host it yourself you get the entire thing for free.

Step 1: perlbrew

Before we begin, switch to a user which will be managing the RT instance. Superuser rights are undesirable.

Most of RT is written in Perl. A good practice is not to depend on system perl, which is vital for the operating system to function properly. Perlbrew will provide freedom in choosing and maintaining perl version. It can be installed with a single command:

\curl -L https://install.perlbrew.pl | bash

If succeeded, further installation instructions will be printed. A bash line containing perlbrew bashrc will need to be added to your ~/.bashrc. Create it if it doesn't exist.

To confirm that it worked, type in perlbrew - help page should be printed with available commands. If it wasn't, try logging out and back in again. If that also didn't work, the problem most likely lies within your configuration files - ~/.profile and ~/.bashrc.

Installing perl

Now that perlbrew is operational, execute these commands:

perlbrew install --notest 5.32.1
perlbrew switch 5.32.1
perlbrew install-cpanm

The first one will likely take a while, as perl is being compiled from source. We add --notest flag to make it much faster, but you can remove it if you're not sure if it will run well on your platform.

When this is done, check which perl and which cpanm - both should be in a directory tree of /home/USER/perl5. If one of them isn't then something went wrong and you will likely have to step back a little and check if all the commands succeeded.

Step 2: RT

We will now fetch the latest code from Best Practical's Github repository. They have a branch named stable that I trust lives up to its name, but if you're unsure you can also unpack one of the official release tarballs. If you choose to do so, you won't need to run the autoconf command.

cd ~
git clone https://github.com/bestpractical/rt.git
cd rt && autoconf

Pre-install configuration

RT is configured with a configure script often used in unix programs. From the many options available you must find and specify those that fit your needs and put them in a call to the configure script. I always use the following line:

./configure \
        --with-web-handler=standalone\
        --with-bin-owner=USER\
        --with-libs-owner=USER\
        --with-libs-group=USER\
        --with-db-type=Pg\
        --with-db-port=5432\
        --with-db-database=DB_DATABASE\
        --with-db-rt-user=DB_USER\
        --with-db-rt-pass=DB_PASS\
        --with-my-user-group\
        --prefix=/home/USER/rt/opt

This assumes that your database is PostgreSQL and is running locally on default port 5432. All the options in full uppercase should be replaced with real values:

  • USER - unix user name
  • DB_DATABASE - database name (need not to exist beforehand)
  • DB_USER - database user (need not to exist beforehand)
  • DB_PASS - database user password

Dependencies

After this command finishes, we will have to install the Perl dependencies for RT.

make fixdeps

This is quite a long process that requires user consent from time to time. It will also likely not fully run on the first try, as some of the packages require operating system components. The most notable examples of this are GnuPG and OpenSSL. Even if you have OpenSSL installed, the dependencies will likely complain anyway because they require development packages. Install these as a superuser or notify your administrator.

Installing

At this point, we're already past the hard part. The following commands should not cause much problems:

make install
make initialize-database

The second one will ask you for a database admin password and create a new user and database for you. If it doesn't work then it's possible that the database server is not configured to authenticate admin user by password locally - server administrator will have to sort that out.

Post-install configuration

The last RT-specific step is configuring the system details. You do this by editing a file ~/rt/opt/etc/RT_SiteConfig.pm. I use the following template:

use utf8;

Set($rtname, 'rt.example.com');
Set($Organization, 'example.com');
Set($WebDomain, 'rt.example.com');
Set($CorrespondAddress, 'contact@example.com');
Set(@ReferrerWhitelist, qw(rt.example.com rt.example.com:443));
Set($LogoLinkURL, "https://example.com");
Set($LogoAltText, "logo");
Set($Timezone, "Europe/Warsaw");
Set(@LexiconLanguages, qw(en));
Set($MailCommand, "sendmail");

1;

While these configs may not be vital for basic features of RT, lack of them will get in your way later when you choose to configure integration with mail server.

Testing the installation

We're now ready to test if any of our efforts has borne any fruit. The next command will run the web server:

~/rt/opt/sbin/rt-server --port 8999 --max-workers 4

You can choose any open port you'd like. Now visit website.com:8999 and there you should find a login page. Try logging in - the default credentials are root:password.

Oops... there's no login page!

Common reasons for that are firewall settings (blocking the port you specified), something already using that port or not all dependencies were installed correctly. Troubleshooting can be tough sometimes, but it is a lot easier if you have superuser access to verify all the system configuration and log files.

Daemonizing

The next logical step is making sure that the RT instance is persistent. My favorite way of doing that is through the Ubic Perl module. It requires no elevated privileges, is easy to install and works very well. To install:

cpanm Ubic
ubic-admin setup
ubic status

Now we need a service file for RT. These aren't that easy to create, but you can often just copy most of the configuration from one to another:

use Ubic::Service::SimpleDaemon;

Ubic::Service::SimpleDaemon->new(
        bin => '/home/USER/rt/opt/sbin/rt-server --port 8999 --max-workers 4',
        ubic_log => '/home/USER/rt/opt/var/log/ubic/ubic.log',
        stdout => '/home/USER/rt/opt/var/log/ubic/server.log',
        stderr => '/home/USER/rt/opt/var/log/ubic/error.log',
        user => 'USER',
        env => {
                PATH => '/home/USER/perl5/perlbrew/perls/perl-5.32.1/bin/'
        },
);

Put this into ~/ubic/service/rt and replace all the USER occurences with your unix user login. Ubic should now be able to see and run the service:

mkdir ~/rt/opt/var/log/ubic
ubic start rt

If all goes well, your RT instance will now be revived after a crash or a server restart.

That's it!

You now have a functional RT instance that is good enough for testing and some personal use. It is by no means the end of the journey if you would like to use it heavily. I suggest to play with it some more if it meets your needs, and if it does continue with the next steps:

  • Put the standalone server behind a proxy, like Apache2 or Nginx
  • Hide the original server and unsafe actions from the outside world
  • Configure a mail server and integrate it with RT

Each of these is enough matter to discuss over a separate article, and I can provide one if there is demand for it - let me know if this is something that would benefit you!

Comments? Suggestions? Send to bbrtj.pro@gmail.com
Published on 2021-01-27