ManualInstallation

Prev: ManualRequirements — Up: UserManual — Next: ManualApacheConfig

This guide walks you through installing RT from source on a modern, popular Linux distro. Specifically, that means a distribution based on Debian or Red Hat that’s been released since around 2020.

RT's README for the version you are installing is the best starting resource. It provides the high-level steps to follow, but not details. This guide provides some of those details. It is not meant to be followed step by step, but it does provide guidance once you have picked the database and web server you want to use for RT.

This guide assumes:

• You can install packages generally available in Debian/Ubuntu or Red Hat/Fedora/CentOS.
• You want to install RT, and all of its Perl dependencies, from source to get the latest versions. (This is a trade-off. It means the boundaries of your install will be very clear, but you won’t get security updates for RT or Perl modules from your distribution.)
• You are willing to install a couple of extra tools to manage the RT installation similarly to how you would in other packaging systems (like PyPI, npm, etc.).
• You are willing to do a relatively maximal install of RT, enabling all the options during installation and then setting what you need in the configuration. (You could save a little space and time by being pickier about your options, but then that complicates the guide and makes it harder to turn those options on later if you want.)
• You are using a regular user account on the Linux system that can get superuser privileges with sudo.

Install the base dependencies

These are required by RT, either to run or to install the dependencies.

Debian/Ubuntu

sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz multiwatch openssl perl w3m

Red Hat Enterprise Linux

These instructions are for RHEL specifically. For RHEL-derived distributions like CentOS and Rocky, go to the next section.

MAJDISTVER="$(. /etc/os-release && echo "${VERSION_ID%%.*}")"
sudo subscription-manager repos --enable "codeready-builder-for-rhel-$MAJDISTVER-$(arch)-rpms"
sudo dnf install "https://dl.fedoraproject.org/pub/epel/epel-release-latest-$MAJDISTVER.noarch.rpm"
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel multiwatch openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of March 2022, nobody has written a policy for RT.)

RHEL Community Distributions: Fedora/CentOS/Rocky

sudo dnf install epel-release
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel multiwatch openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of March 2022, nobody has written a policy for RT.)

Install a database

You need access to a database server. It can be remote, or you can install a database server alongside RT. RT supports MySQL, MariaDB, Postgresql, and Oracle, and SQLite for development. Currently MariaDB and Postgreql are easiest to get and install via most Linux packaging systems.

Installing and configuring the PostgreSQL server

If you want to install a fresh PostgreSQL database server alongside RT:

Debian/Ubuntu	Red Hat/Fedora/CentOS
sudo apt install postgresql	sudo dnf install postgresql-server

In order to set up RT’s database, you will need a PostgreSQL account that can create databases and roles and be authenticated with a password. If you don’t have that, you can create it by running:

sudo createuser --createdb --createrole --login --pwprompt rt_admin

Set the password when prompted. Record this; you’ll need it later.

Enable password authentication in PostgreSQL

You need to consider this step whether you install the database locally, or use an existing one already running. RT supports connecting to PostgreSQL a few different ways, but authenticating with a username and password is simplest, and this guide is written based on that. Not all PostgreSQL installations allow this authentication method by default. You need to review your pg_hba.conf file located at:

Debian/Ubuntu	Red Hat/Fedora/CentOS
/etc/postgresql/VERSION/main/pg_hba.conf	/var/lib/pgsql/VERSION/data/pg_hba.conf

Replace VERSION with the version of your PostgreSQL database. Add these two lines above any other lines that start with host:

host  rt5  rt_user   all  md5
host  rt5  rt_admin  all  md5

This configuration will let rt_user and rt_admin authorize themselves for the rt5 database using an md5 crypted password over a network connection (possibly using the localhost loopback network). You might be able to further restrict some of these fields for improved security, but doing so is outside the scope of this install guide. Refer to the pg_hba.conf documentation for more details.

Save your changes and reload the database:

sudo systemctl reload postgresql

Installing the PostgreSQL client libraries

These are required for RT to be able to talk to any PostgreSQL server.

Debian/Ubuntu	Red Hat/Fedora/CentOS
sudo apt install libpq-dev	sudo dnf install postgresql-devel

Once this is done you can skip ahead to installing RT.

Installing and configuring the MariaDB server

If you want to install a fresh MariaDB database server alongside RT:

Debian/Ubuntu	Red Hat/Fedora/CentOS
sudo apt install mariadb-server	sudo dnf install mariadb-server

In order to set up RT’s database, you will need a MySQL superuser account. To stay consistent with PostgreSQL, I suggest setting a password for it. You can do that by running:

sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;

Record your passphrase; you’ll need it later.

Adjust MariaDB’s max_allowed_packet setting

You need to consider this step whether you install the database locally, or use an existing one already running. MariaDB’s max_allowed_packet setting functionally limits the size of attachments in RT. The default is 16MiB, which is too small for most installations. You can ultimately choose any setting you’re comfortable with; 64MiB here should allow most requests without being too open.

Debian/Ubuntu	Red Hat/Fedora/CentOS
echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf sudo systemctl reload mariadb	echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf sudo systemctl reload mariadb

Installing the MariaDB client libraries

These are required for RT to be able to talk to any MariaDB server.

Debian/Ubuntu	Red Hat/Fedora/CentOS
sudo apt install libmariadb-dev libmariadb-dev-compat	On latest versions: sudo dnf install mariadb-connector-c-devel If you're on an older version that doesn't have that package: sudo dnf install mariadb-devel

Install RT

Optional: Create RT system accounts

Creating separate RT system accounts is optional. Running configure will usually auto detect the correct group and user to use for setting permissions. See the group and user related options for configure to fine tune the permissions.

You can create this user and group if you prefer not to install as root. This account will be used throughout the install process to control access to sensitive files. Run:

sudo groupadd --system rt
sudo useradd --system --home-dir=/opt/rt5/var --gid=rt rt

Get and unpack the RT source code

Download the latest source code using the link on the RT download page, extract it using tar -xf, and cd into the source code directory to run the rest of the commands in this section. For example:

curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.3.tar.gz
tar -xf rt-5.0.3.tar.gz
cd rt-5.0.3

Pre-configure RT

The configure command will detect some information about your system in order to install RT properly, and decide which set of dependencies to install. Here’s what the different parts of our command are doing:

• PERL=… configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The /opt/rt5 part of this string should match your prefix setting (see next item). If you know you want to use a specific Perl installed on your system, you can specify its full path instead of the plain perl here.
• --prefix=/opt/rt5 sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
• --with-db-type=TYPE - Replace TYPE with Pg for PostgreSQL, or mysql for MariaDB.
• --with-web-user=rt --with-web-group=rt installs RT using the dedicated accounts we created earlier.
• The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have cded into the RT source directory. As an example of manually setting serveral options, you can run:

PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-user=rt --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime

Many of the values have default settings, like /opt/rt5 as the prefix. And the configure script will try to find things like the configured perl, so this can also work for a fairly typical RT:

./configure --enable-gd --enable-graphviz

For more background, refer to the RT configure options documentation.

Install RT and its Perl dependencies

This command will download, build, and install all of the Perl modules necessary to run RT with the configuration you set above. RT has additional documentation on setting up your perl. Here’s what the different parts of the command are doing:

• make dirs creates RT's directory structure, so we can install dependencies inside it.
• make fixdeps actually installs those dependencies.
• RT_FIX_DEPS_CMD=… tells RT to use cpanminus to install dependencies (instead of the older, default cpan command) inside RT's directory structure.
• make install installs all of RT’s files under /opt/rt5 (or the prefix directory you set earlier). It will only run if fixdeps succeeded.

Make sure you have cded into the RT source directory. To install the modules in the standard perl directories, run:

sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo"
sudo make install

If you want to install the perl libraries in the RT directories, you could run:

sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install

If it works, the command will eventually output a message that says “Congratulations. RT is now installed.” followed by instructions about configuring and setting up the database. We’ll do that next.

Configure RT

RT has many configuration options. You can put configuration options in the file /opt/rt5/etc/RT_SiteConfig.pm, or in individual files under /opt/rt5/etc/RT_SiteConfig.d/. Use an editor to save all the text below to /opt/rt5/etc/RT_SiteConfig.pm (you can just overwrite the existing file, or add this to the bottom of what’s there) and then fill in settings for your site everywhere the text EDIT WITH appears.

# Single-quote all values EXCEPT the special value `undef`
# that turns off a setting.

# rtname appears in ticket email subjects. It needs to be globally unique,
# so use your organization's domain name.
Set($rtname, 'EDIT WITH yourdomain.example.com');
# Organization is used in the database for ticket links, etc. It also needs to
# be globally unique, so use your organization's domain name.
Set($Organization, 'EDIT WITH yourdomain.example.com');
# WebDomain is domain name of the RT web server. RT uses it to construct links
# and defend against CSRFs.
Set($WebDomain, 'EDIT WITH rt.yourdomain.example.com');
# WebPort is the port where the RT web server runs. Edit the number below if
# you're not using the standard HTTPS port.
Set($WebPort, '443');
# WebPath is the path where the RT web server runs on your WebDomain.
# Edit the path below only if you're using a specific path like example.com/rt
Set($WebPath, '/rt');

# DatabaseUser is the name of the database account RT uses to read and store
# data. 'rt_user' is the default but you can change it if you like.
# DO NOT use the 'rt_admin' superuser created in the instructions above.
Set($DatabaseUser, 'rt_user');
# DatabasePassword is the password for DatabaseUser.
Set($DatabasePassword, 'EDIT WITH SomePassphraseHere');
# DatabaseHost is the hostname of the database server RT should use.
# Change 'localhost' if it lives on a different server.
Set($DatabaseHost, 'localhost');
# DatabasePort is the port number of the database server RT should use.
# `undef` means the default for that database. Change it if you're not
# using the standard port.
Set($DatabasePort, undef);
# DatabaseName is the name of RT's database hosted on DatabaseHost.
# 'rt5' is the default but you can change it if you like.
Set($DatabaseName, 'rt5');
# DatabaseAdmin is the name of the user in the database used to perform
# major administrative tasks. Change 'rt_admin' if you're using a user
# besides the one created in this guide.
Set($DatabaseAdmin, 'rt_admin');

# RT can log to syslog, stderr, and/or a dedicated file.
# Log settings are used both by the primary server and by command line
# tools like rt-crontool, rt-ldapimport, etc.
# You set all of RT's $LogTo* paramaters to a standard log level: 'debug',
# 'info', 'notice', 'warning', 'error', 'critical', 'alert', or 'emergency'.
# For a modern install, if you log to syslog, it goes
# to journald where it's easy to query and automatically gets rotated.
# Some syslogs log only warn and error, so lower levels like debug won't appear here.
Set($LogToSyslog, 'warning');

# When the RT server logs to stderr, that will go to the rt-server journal.
# Command line tools log to their own stderr. Setting this to
# 'warning' or 'error' helps ensure you get notified if RT's cron jobs
# encounter problems.
# When running with Apache, these logs will go to the Apache error log,
# which should be set up with logrotate automatically.
Set($LogToSTDERR, 'warning');

# Turn off optional features that require additional configuration.
# If you want to use these, refer to the RT_Config documentation for
# instructions on how to set them up.
Set(%GnuPG, 'Enable' => '0');
Set(%SMIME, 'Enable' => '0');

# Perl expects to find this 1 at the end of the file.
1;

RT_SiteConfig.pm is actually Perl code. RT runs the code directly to load the configuration. Any time you finish editing it, you can check that you didn’t make any syntax errors by running:

perl -c /opt/rt5/etc/RT_SiteConfig.pm

Set up RT’s database

RT includes a tool to help you set up its database. By default, it connects to the database as an administrator to create the database and user that you configured in the previous step.

The instructions from make install and RT’s README file tell you to run make initialize-database, so run:

make initialize-database

That runs the rt-setup-database command for you. If you're curious, you can see all of the options in RT's documentation.

• --action=init tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
• If you are using an existing database server and the database administrator has already created the user account and database for RT, then you can add the --skip-create option.
• If you have a less common database setup, this tool has additional options to give you finer-grained control over what steps are run and how.
• The command reads files from RT’s etc/ directory by default, so the easiest way to run it is to cd /opt/rt5 first, and then it will find the necessary files automatically.

Set up fulltext indexing

Fulltext indexing speeds up searches for ticket content, which makes RT a lot nicer to use.

• --noask uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask

Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

### EXAMPLE OUTPUT ONLY - Don't use this directly!
Set( %FullTextSearch,
    Enable     => 1,
    Indexed    => 1,
    # Additional output from rt-setup-fulltext-index should be here.
    # The configuration varies by database type.
);

Copy the output generated when you run rt-setup-fulltext-index and save it to the file /opt/rt5/etc/RT_SiteConfig.pm.

Set permissions

All of RT’s configuration files should be readable by the user that runs the web server, and no other users, in order to protect sensitive information like the database password. RT provides a command to set permissions appropriately according to your distribution and configuration. cd to the directory where you extracted the RT source code, and run:

cd rt-5.0.3
sudo make fixperms

This is done as part of the installation, so permissions should be correct, but this is helpful if you change something.

Verify the installation

If everything has gone well, then you should be able to set a password for RT’s root user. You’ll use this later to log in to the web interface and continue setting up your system. Run:

sudo /opt/rt5/sbin/rt-passwd root

Set the password when prompted. Record this; you’ll need it later.

Set up RT’s web server

Fully documenting how to set up a web server configured for your network, with SSL, is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto RT using Apache with mod_fcgid or nginx and the RT FastCGI service.

See the RT deployment guide for the latest recommendations from Best Practical on how to deploy RT.

Apache httpd

Make sure you have the necessary packages installed, are using the preform MPM, and the mod_fcgid module is enabled:

Debian/Ubuntu	Red Hat/Fedora/CentOS
sudo apt install apache2 libapache2-mod-fcgid sudo a2dismod mpm_event sudo a2dismod mpm_worker sudo systemctl restart apache2 sudo a2enmod mpm_prefork sudo systemctl restart apache2	sudo dnf install httpd

In the <VirtualHost> configuration blocks where you want to serve RT, add a configuration block like this, above any other Alias or ScriptAlias lines:

### Optional apache logs for RT
# Ensure that your log rotation scripts know about these files
# ErrorLog /opt/rt5/var/log/apache2.error
# TransferLog /opt/rt5/var/log/apache2.access
# LogLevel debug

AddDefaultCharset UTF-8

# ScriptAlias and Location should match RT's WebPath

# If WebPath is empty then use a single slash:
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# If WebPath is 'rt' then add that after the slash:
# ScriptAlias /rt /opt/rt5/sbin/rt-server.fcgi/

DocumentRoot "/opt/rt5/share/html"

# If WebPath is empty then use a single slash:
<Location />
# If WebPath is 'rt' then add that after the slash:
# <Location /rt>

    Require all granted
    Options +ExecCGI
    AddHandler fcgid-script fcgi
</Location>

If you're doing a fresh install, the default <VirtualHost> configuration location varies by distribution and whether or not you're using HTTPS:

Debian/Ubuntu	Red Hat/Fedora/CentOS
With HTTPS: /etc/apache2/sites-available/default-ssl.conf With plain HTTP: /etc/apache2/sites-available/000-default.conf	With HTTPS: /etc/httpd/conf.d/ssl.conf With plain HTTP: Write a new file /etc/httpd/conf.d/vhost_RT.conf

After you’ve edited your configuration, load it by running:

Debian/Ubuntu	Red Hat/Fedora/CentOS
sudo systemctl reload apache2	sudo systemctl reload httpd

nginx

Set up RT FastCGI service for use with nginx

Create the RT service

Run:

sudo systemctl edit --force --full rt-server.service

This opens an editor to define the RT service to systemd. Use the editor to add this text to the file:

[Unit]
Description=RT FCGI server

[Service]
# The --forks option is the number of RT servers to run in parallel.
# 3 should be good for most initial installs. You can increase this
# number later if needed for performance.
ExecStart=/usr/bin/multiwatch --forks=3 --signal=TERM -- /opt/rt5/sbin/rt-server.fcgi
StandardInput=socket
User=rt
UMask=027

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=full

Save the file and close your editor.

Create the RT socket

Run:

sudo systemctl edit --force --full rt-server.socket

This opens an editor to define the RT socket to systemd. Use the editor to add this text to the file:

[Unit]
Description=RT FCGI server socket
Wants=network.target
After=network.target
Before=apache2.service httpd.service nginx.service

[Install]
WantedBy=sockets.target

[Socket]
# ListenStream defines the address and port where the RT FastCGI server listens.
# This is NOT the web server itself, so don't make this port 80, 443, etc.
# You may edit this if you like, but note:
# Connections are unencrypted. You should only listen on a secure network
# interface.
# The server can only accept a single socket. You cannot specify more than
# one ListenStream address.
ListenStream=[::1]:5000
Accept=no
FreeBind=yes

Save the file and close your editor.

Enable the RT socket

Start the server socket and enable it on future boots:

sudo systemctl enable --now rt-server.socket

Make sure you have the necessary packages installed:

Debian/Ubuntu	Red Hat/Fedora/CentOS
sudo apt install nginx	sudo dnf install nginx

In the http server configuration blocks where you want to serve RT, add a configuration block like this, above any other location blocks:

# The location path should match the WebPath in your RT site configuration.
location / {
  include /etc/nginx/fastcgi.conf;
  # SCRIPT_NAME should match RT's WebPath, without a trailing slash.
  # This means when WebPath is /, it's the empty string "".
  fastcgi_param SCRIPT_NAME "";
  # This network location should match the ListenStream in rt-server.socket.
  fastcgi_pass localhost:5000;
}

If you're doing a fresh install, the default http server configuration location varies by distribution:

Debian/Ubuntu	Red Hat/Fedora/CentOS
Edit /etc/nginx/sites-available/default	Add a new file /etc/nginx/default.d/rt-server.conf

After you’ve edited your configuration, load it by running:

sudo systemctl reload nginx

Once this is done you can skip ahead to Verify the web interface.

Verify the web interface

You should be able to visit your web server in your browser, and be presented with RT’s login screen. You should be able to log in with username root and the password you set previously.

If the web server returns a 502 Bad Gateway response, it's having trouble connecting to the RT FCGI server. Check the error logs for your web server:

nginx	Apache on Debian/Ubuntu	httpd on Red Hat/Fedora/CentOS
/var/log/nginx/error.log	/var/log/apache2/error.log	/var/log/httpd/error_log

For all kinds of errors, you can check the logs for the RT FCGI server and its socket:

sudo journalctl --unit rt-server.\*

Set up RT’s mail server

RT both can both send and receive ticket updates via email. Unfortunately, there are too many variables to document a useful setup process here: getting this working usually requires creating DNS records, and coordinating with existing mail servers, which will be the main constraint on your setup. Instead this guide provides a brief overview of how the integration works, and where the connection points are that you likely need to work on.

Sending Mail

RT only knows how to send mail by passing it off to another program on the system. It does not connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard sendmail command, which is provided by whichever MTA you have installed (postfix, sendmail, exim, qmail, etc.). There are configuration options to send mail through different commands if you need.

The most common setup is to install and configure a proper Mail Transfer Agent (MTA) like Postfix or Exim, and then configure it to send mail to the wider Internet as you need. This works well because the MTAs are robust and well-tested; they have flexible configuration to let you send mail out by relaying to other mail servers you specify with optional authentication; and most distributions install one by default anyway. The only hard part is configuring the MTA to send mail following your site’s policies.

Other software is available that provides a slimmer version of the sendmail command that connects to an external mail server for you, like msmtp. These programs are usually easier to configure than an MTA, but they often lose email permanently if they can’t connect to the external server at the time it’s sent. (MTAs keep email queued locally until they successfully deliver it to another server.)

Receiving email

RT installs a command called rt-mailgate that receives an email on standard input and posts it to RT’s REST web interface, where it gets saved in the database and added to a ticket. You need to arrange for a way to send incoming email to this command.

The most common setup is to have an MTA on the same box as RT receive email directly, and then set up mail aliases that call this command when mail comes in. Example /etc/aliases entries look like:

rt: "|/opt/rt5/bin/rt-mailgate --queue general --action correspond --url https://rt.yourdomain.example.com/"
rt-comment: "|/opt/rt5/bin/rt-mailgate --queue general --action comment --url https://rt.yourdomain.example.com/"

This works well because, again, you’re probably running an MTA anyway; and the MTA can hold and queue mail if it comes in while RT is down for any reason, giving you a buffer against downtime.

Another common option is to periodically run a tool that fetches mail using a protocol like IMAP, like fetchmail or getmail, and passes it on to rt-mailgate. This is less common because it requires setting up another tool to run, and securely storing another set of mail server credentials. But it is useful when local policy prevents the RT server from receiving email directly.

This is much less common, but it might help to know that rt-mailgate doesn’t have to run on the same system as RT itself. It just needs to be able to connect to RT’s web interface. If you don’t have any other options, you can install the RT software on a different system that receives email, and configure that system to run rt-mailgate and pass it on to the RT server. To do that, install the RT::Client::CLI Perl package on the mail server. For example, you could install cpanminus, then run:

cpanm --sudo RT::Client::CLI

Set up RT’s background jobs

Create a file /etc/cron.d/rt with the following content. You may edit all of the time fields as you see fit. Refer to the crontab(5) man page for details about their definitions.

# Update the fulltext index with new ticket data
*/3 *   *   *   *   rt    /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
1   *   *   *   *   rt    /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
50  3   *   *   *   rt    /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50  4   *   *   Mon rt    /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50  5   *   *   *   rt    /opt/rt5/sbin/rt-email-digest -m daily

Set up RT

If you’ve gotten this far, congratulations, your RT install is really done now. You can start setting up RT with users, groups, queues, and business logic. Head back to the main page to start exploring those topics.