Request Tracker Wiki - User contributions [en]

ManualInstallation

2022-10-21T19:48:36Z

Brett: update LogToSTDERR explanation to match the rest of the deployment strategy

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|On latest versions:
<pre>sudo dnf install mariadb-connector-c-devel</pre>
If you're on an older version that doesn't have that package:
<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create RT system accounts ===

This account will be used throughout the install process to control access to sensitive files. Run:

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

=== Get and unpack the RT source code ===

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

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

=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-user=rt --with-web-group=rt</code> 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 <code>cd</code>ed into the RT source directory, and run:

<pre>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</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# 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.
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;
</pre>

<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.3
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Start the server socket and enable it on future boots:

<pre>sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
ProxyFCGISetEnvIf true SCRIPT_NAME ""
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, install the [https://metacpan.org/pod/RT::Client::CLI RT::Client::CLI] Perl package on the mail server. For example, you could install cpanminus, then run:

<pre>cpanm --sudo RT::Client::CLI</pre>

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# 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
</pre>

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-10-12T17:45:55Z

Brett: small extra niceties in cron job scheduling

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|On latest versions:
<pre>sudo dnf install mariadb-connector-c-devel</pre>
If you're on an older version that doesn't have that package:
<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create RT system accounts ===

This account will be used throughout the install process to control access to sensitive files. Run:

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

=== Get and unpack the RT source code ===

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

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

=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-user=rt --with-web-group=rt</code> 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 <code>cd</code>ed into the RT source directory, and run:

<pre>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</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>

<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.3
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Start the server socket and enable it on future boots:

<pre>sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
ProxyFCGISetEnvIf true SCRIPT_NAME ""
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, install the [https://metacpan.org/pod/RT::Client::CLI RT::Client::CLI] Perl package on the mail server. For example, you could install cpanminus, then run:

<pre>cpanm --sudo RT::Client::CLI</pre>

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# 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
</pre>

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-10-12T17:20:59Z

Brett: update rt-mailgate install instructions for 5.0.3

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|On latest versions:
<pre>sudo dnf install mariadb-connector-c-devel</pre>
If you're on an older version that doesn't have that package:
<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create RT system accounts ===

This account will be used throughout the install process to control access to sensitive files. Run:

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

=== Get and unpack the RT source code ===

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

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

=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-user=rt --with-web-group=rt</code> 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 <code>cd</code>ed into the RT source directory, and run:

<pre>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</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>

<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.3
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Start the server socket and enable it on future boots:

<pre>sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
ProxyFCGISetEnvIf true SCRIPT_NAME ""
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, install the [https://metacpan.org/pod/RT::Client::CLI RT::Client::CLI] Perl package on the mail server. For example, you could install cpanminus, then run:

<pre>cpanm --sudo RT::Client::CLI</pre>

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * rt /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * rt /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 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
</pre>

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-10-12T17:17:01Z

Brett: update for 5.0.3 release

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|On latest versions:
<pre>sudo dnf install mariadb-connector-c-devel</pre>
If you're on an older version that doesn't have that package:
<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create RT system accounts ===

This account will be used throughout the install process to control access to sensitive files. Run:

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

=== Get and unpack the RT source code ===

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

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

=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-user=rt --with-web-group=rt</code> 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 <code>cd</code>ed into the RT source directory, and run:

<pre>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</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>

<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.3
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Start the server socket and enable it on future boots:

<pre>sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
ProxyFCGISetEnvIf true SCRIPT_NAME ""
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * rt /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * rt /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 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
</pre>

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-10-12T17:15:38Z

Brett: prefer a static User to avoid NoNewPrivileges and problems with sendmailpipe

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|On latest versions:
<pre>sudo dnf install mariadb-connector-c-devel</pre>
If you're on an older version that doesn't have that package:
<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create RT system accounts ===

This account will be used throughout the install process to control access to sensitive files. Run:

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

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>

=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-user=rt --with-web-group=rt</code> 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 <code>cd</code>ed into the RT source directory, and run:

<pre>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</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>

<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Start the server socket and enable it on future boots:

<pre>sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
ProxyFCGISetEnvIf true SCRIPT_NAME ""
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * rt /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * rt /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 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
</pre>

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-09-07T17:17:41Z

Brett: note new Red Hat name for MariaDB libraries

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|On latest versions:
<pre>sudo dnf install mariadb-connector-c-devel</pre>
If you're on an older version that doesn't have that package:
<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create an RT system group ===

This group will be used throughout the install process to control access to sensitive files. Run:

<pre>sudo groupadd --system rt</pre>

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-group=rt</code> installs RT using the dedicated group we created earlier.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
DynamicUser=true
SupplementaryGroups=rt
UMask=027

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=full
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Load the new services into RT, start the server socket, and enable it on future boots:

<pre>sudo systemctl daemon-reload
sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
ProxyFCGISetEnvIf true SCRIPT_NAME ""
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

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

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-08-03T13:03:46Z

Brett: refer to the better-maintained msmtp

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create an RT system group ===

This group will be used throughout the install process to control access to sensitive files. Run:

<pre>sudo groupadd --system rt</pre>

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-group=rt</code> installs RT using the dedicated group we created earlier.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
DynamicUser=true
SupplementaryGroups=rt
UMask=027

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=full
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Load the new services into RT, start the server socket, and enable it on future boots:

<pre>sudo systemctl daemon-reload
sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
ProxyFCGISetEnvIf true SCRIPT_NAME ""
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

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

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-05-18T15:54:45Z

Brett: remove service security options that interfere with calling suid/guid executables (e.g., for sendmail)

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create an RT system group ===

This group will be used throughout the install process to control access to sensitive files. Run:

<pre>sudo groupadd --system rt</pre>

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-group=rt</code> installs RT using the dedicated group we created earlier.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
DynamicUser=true
SupplementaryGroups=rt
UMask=027

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=full
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Load the new services into RT, start the server socket, and enable it on future boots:

<pre>sudo systemctl daemon-reload
sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
ProxyFCGISetEnvIf true SCRIPT_NAME ""
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

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

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-05-11T02:30:03Z

Brett: more correct comments about RT's SCRIPT_NAME, httpd version

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create an RT system group ===

This group will be used throughout the install process to control access to sensitive files. Run:

<pre>sudo groupadd --system rt</pre>

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-group=rt</code> installs RT using the dedicated group we created earlier.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
DynamicUser=true
SupplementaryGroups=rt
UMask=027
# If you have RT plugins or customizations that write to other locations on
# the filesystem, add more ReadWritePaths lines as needed.
ReadWritePaths=/opt/rt5/var

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=strict
NoNewPrivileges=true
LockPersonality=true
MemoryDenyWriteExecute=true
PrivateDevices=true
ProtectKernelModules=true
ProtectKernelTunables=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
RestrictNamespaces=true
RestrictRealtime=true
SystemCallErrorNumber=EPERM
SystemCallFilter=@system-service
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Load the new services into RT, start the server socket, and enable it on future boots:

<pre>sudo systemctl daemon-reload
sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# SCRIPT_NAME should match RT's WebPath, without a trailing slash.
# This means when WebPath is /, it's the empty string "".
ProxyFCGISetEnvIf true SCRIPT_NAME ""
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

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

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-05-11T02:25:58Z

Brett: more correct comments about RT's SCRIPT_NAME

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create an RT system group ===

This group will be used throughout the install process to control access to sensitive files. Run:

<pre>sudo groupadd --system rt</pre>

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-group=rt</code> installs RT using the dedicated group we created earlier.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
DynamicUser=true
SupplementaryGroups=rt
UMask=027
# If you have RT plugins or customizations that write to other locations on
# the filesystem, add more ReadWritePaths lines as needed.
ReadWritePaths=/opt/rt5/var

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=strict
NoNewPrivileges=true
LockPersonality=true
MemoryDenyWriteExecute=true
PrivateDevices=true
ProtectKernelModules=true
ProtectKernelTunables=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
RestrictNamespaces=true
RestrictRealtime=true
SystemCallErrorNumber=EPERM
SystemCallFilter=@system-service
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Load the new services into RT, start the server socket, and enable it on future boots:

<pre>sudo systemctl daemon-reload
sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# 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;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# RT requires an empty SCRIPT_NAME to serve static files.
ProxyFCGISetEnvIf true SCRIPT_NAME
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

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

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-05-02T19:28:11Z

Brett: update to deploy the RT FCGI server separately

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.

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

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

=== Red Hat Enterprise Linux ===

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

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

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

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:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install RT ==

=== Create an RT system group ===

This group will be used throughout the install process to control access to sensitive files. Run:

<pre>sudo groupadd --system rt</pre>

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--with-web-group=rt</code> installs RT using the dedicated group we created earlier.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-web-group=rt --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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 if you're using a specific path.
Set($WebPath, '/');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT FastCGI service ==

=== Create the RT service ===

Run:

<pre>sudo systemctl edit --force --full rt-server.service</pre>

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

<pre>[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
DynamicUser=true
SupplementaryGroups=rt
UMask=027
# If you have RT plugins or customizations that write to other locations on
# the filesystem, add more ReadWritePaths lines as needed.
ReadWritePaths=/opt/rt5/var

CapabilityBoundingSet=
DevicePolicy=closed
PrivateMounts=true
PrivateNetwork=false
PrivateTmp=true
PrivateUsers=true
ProtectControlGroups=true
ProtectHome=true
ProtectSystem=strict
NoNewPrivileges=true
LockPersonality=true
MemoryDenyWriteExecute=true
PrivateDevices=true
ProtectKernelModules=true
ProtectKernelTunables=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
RestrictNamespaces=true
RestrictRealtime=true
SystemCallErrorNumber=EPERM
SystemCallFilter=@system-service
</pre>

Save the file and close your editor.

=== Create the RT socket ===

Run:

<pre>sudo systemctl edit --force --full rt-server.socket</pre>

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

<pre>[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
</pre>

Save the file and close your editor.

=== Enable the RT socket ===

Load the new services into RT, start the server socket, and enable it on future boots:

<pre>sudo systemctl daemon-reload
sudo systemctl enable --now rt-server.socket</pre>

== Set up RT’s web server ==

Fully documenting how to set up a web server configured for your network with encryption is outside the scope of this guide. This page only highlights the configuration you need to pass web requests onto the RT FastCGI service.

=== nginx ===

Make sure you have the necessary packages installed:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install nginx</pre>
|<pre>sudo dnf install nginx</pre>
|}

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

<pre>
# The location path should match the WebPath in your RT site configuration.
location / {
include /etc/nginx/fastcgi.conf;
# RT requires an empty SCRIPT_NAME to serve static files.
fastcgi_param SCRIPT_NAME "";
# This network location should match the ListenStream in rt-server.socket.
fastcgi_pass localhost:5000;
}
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|Edit <code>/etc/nginx/sites-available/default</code>
|Add a new file <code>/etc/nginx/default.d/rt-server.conf</code>
|}

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

<pre>sudo systemctl reload nginx</pre>

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

=== Apache httpd ===

Make sure you have the necessary packages installed, and the proxy_fcgi module enabled:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2
sudo a2enmod proxy
sudo a2enmod proxy_fcgi</pre>
|<pre>sudo dnf install httpd</pre>
|}

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

<pre>
# RT requires an empty SCRIPT_NAME to serve static files.
ProxyFCGISetEnvIf true SCRIPT_NAME
# The location path in the first argument should match the WebPath in your
# RT site configuration. The network location after fcgi:// should match
# the ListenStream in rt-server.socket.
ProxyPass / fcgi://localhost:5000/
</pre>

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|With HTTPS: <code>/etc/apache2/sites-available/default-ssl.conf</code>
With plain HTTP: <code>/etc/apache2/sites-available/000-default.conf</code>
|With HTTPS: <code>/etc/httpd/conf.d/ssl.conf</code>
With plain HTTP: Write a new file <code>/etc/httpd/conf.d/vhost_RT.conf</code>
|}

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

=== 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 <code>root</code> 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:

{| style="width: 100%;"
! style="width: 33%;"|nginx
! style="width: 33%;"|Apache on Debian/Ubuntu
! style="width: 33%;"|httpd on Red Hat/Fedora/CentOS
|-
|<pre>/var/log/nginx/error.log</pre>
|<pre>/var/log/apache2/error.log</pre>
|<pre>/var/log/httpd/error_log</pre>
|}

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

<pre>sudo journalctl --unit rt-server.\*</pre>

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

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

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-25T14:27:01Z

Brett: clean up httpd config a little

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.

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

<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz openssl perl w3m</pre>

=== Red Hat Enterprise Linux ===

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

<pre>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 openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0</pre>

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
</Location>
AddDefaultCharset UTF-8
AddHandler fcgid-script fcgi
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-24T16:10:57Z

Brett: revert back to recommending w3m, with instructions for how to enable it on different RH distros

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.

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

<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz openssl perl w3m</pre>

=== Red Hat Enterprise Linux ===

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

<pre>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 openssl openssl-devel w3m
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0</pre>

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

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

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-24T16:06:10Z

Brett: add instructions to disable SELinux permanently

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo sed -i~ '/^SELINUX=/ c SELINUX=disabled' /etc/selinux/config
sudo setenforce 0</pre>
|}

(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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-10T18:06:39Z

Brett: narrow max_allowed_packet section

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[server]\nmax_allowed_packet=64M' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-04T19:26:08Z

Brett: reorganize to simplify flow

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=…</code> configures RT to run under Perl with some options that load its dependencies from a dedicated directory. The <code>/opt/rt5</code> part of this string should match your <code>prefix</code> 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 <code>perl</code> here.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --prefix=/opt/rt5 --with-db-type=TYPE --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-04T19:15:00Z

Brett: configure with `env -S perl -I` instead of setting PERL5LIB

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL="/usr/bin/env -S perl -I/opt/rt5/local/lib/perl5" ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

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

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
make fixdeps RT_FIX_DEPS_CMD="cpanm --sudo --local-lib-contained=/opt/rt5/local"
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-03T21:41:46Z

Brett: remove unsupported quotes from PERL_CPANM_OPT

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Set up RT's install environment ===

These steps set things up so we can install RT's Perl dependencies alongside RT itself. Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5</pre>

Next we write an environment file that configures Perl tools, including RT itself, to load and install libraries under the RT install directory. Use an editor to save all the text below to <code>/opt/rt5/RT.env</code>. If you're using a different installation prefix, you should edit the line that sets <code>RTHOME</code> to the directory you chose. Otherwise, you shouldn't need to make any changes to this file.

<pre># RT.env
# When you want to do maintenance on RT (like installing or upgrading
# dependencies or plugins), load this file in your shell by running:
# . /opt/rt5/RT.env
# This will set the necessary environment variables to load and
# install Perl modules under the RT installation directory.
export RTHOME="/opt/rt5"
export PERL5LIB="$RTHOME/local/lib${PERL5LIB:+:$PERL5LIB}"
export PERL_CPANM_OPT="${PERL_CPANM_OPT:+$PERL_CPANM_OPT }--sudo --local-lib-contained=$RTHOME/local"</pre>

=== 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. Here’s what the different parts of the command are doing:

* First we load the environment we set up in the last step, to install dependencies in RT's install directories.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=cpanm</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> installed all the necessary libraries under <code>PERL5LIB</code>.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5/RT.env
make fixdeps RT_FIX_DEPS_CMD=cpanm
sudo make install PERL5LIB="$PERL5LIB"</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-03T15:20:51Z

Brett: fix MariaDB GRANT typo

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVILEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Set up RT's install environment ===

These steps set things up so we can install RT's Perl dependencies alongside RT itself. Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5</pre>

Next we write an environment file that configures Perl tools, including RT itself, to load and install libraries under the RT install directory. Use an editor to save all the text below to <code>/opt/rt5/RT.env</code>. If you're using a different installation prefix, you should edit the line that sets <code>RTHOME</code> to the directory you chose. Otherwise, you shouldn't need to make any changes to this file.

<pre># RT.env
# When you want to do maintenance on RT (like installing or upgrading
# dependencies or plugins), load this file in your shell by running:
# . /opt/rt5/RT.env
# This will set the necessary environment variables to load and
# install Perl modules under the RT installation directory.
export RTHOME="/opt/rt5"
export PERL5LIB="$RTHOME/local/lib${PERL5LIB:+:$PERL5LIB}"
export PERL_CPANM_OPT="${PERL_CPANM_OPT:+$PERL_CPANM_OPT }--sudo --local-lib-contained=\"$RTHOME/local\""</pre>

=== 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. Here’s what the different parts of the command are doing:

* First we load the environment we set up in the last step, to install dependencies in RT's install directories.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=cpanm</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> installed all the necessary libraries under <code>PERL5LIB</code>.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5/RT.env
make fixdeps RT_FIX_DEPS_CMD=cpanm
sudo make install PERL5LIB="$PERL5LIB"</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-03T15:20:35Z

Brett: fix MariaDB GRANT database syntax

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVELEGES ON rt5.* TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Set up RT's install environment ===

These steps set things up so we can install RT's Perl dependencies alongside RT itself. Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5</pre>

Next we write an environment file that configures Perl tools, including RT itself, to load and install libraries under the RT install directory. Use an editor to save all the text below to <code>/opt/rt5/RT.env</code>. If you're using a different installation prefix, you should edit the line that sets <code>RTHOME</code> to the directory you chose. Otherwise, you shouldn't need to make any changes to this file.

<pre># RT.env
# When you want to do maintenance on RT (like installing or upgrading
# dependencies or plugins), load this file in your shell by running:
# . /opt/rt5/RT.env
# This will set the necessary environment variables to load and
# install Perl modules under the RT installation directory.
export RTHOME="/opt/rt5"
export PERL5LIB="$RTHOME/local/lib${PERL5LIB:+:$PERL5LIB}"
export PERL_CPANM_OPT="${PERL_CPANM_OPT:+$PERL_CPANM_OPT }--sudo --local-lib-contained=\"$RTHOME/local\""</pre>

=== 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. Here’s what the different parts of the command are doing:

* First we load the environment we set up in the last step, to install dependencies in RT's install directories.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=cpanm</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> installed all the necessary libraries under <code>PERL5LIB</code>.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5/RT.env
make fixdeps RT_FIX_DEPS_CMD=cpanm
sudo make install PERL5LIB="$PERL5LIB"</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-03T15:10:20Z

Brett: MariaDB GRANT needs a database selected

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql mysql
MariaDB [mysql]> GRANT ALL PRIVELEGES ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Set up RT's install environment ===

These steps set things up so we can install RT's Perl dependencies alongside RT itself. Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5</pre>

Next we write an environment file that configures Perl tools, including RT itself, to load and install libraries under the RT install directory. Use an editor to save all the text below to <code>/opt/rt5/RT.env</code>. If you're using a different installation prefix, you should edit the line that sets <code>RTHOME</code> to the directory you chose. Otherwise, you shouldn't need to make any changes to this file.

<pre># RT.env
# When you want to do maintenance on RT (like installing or upgrading
# dependencies or plugins), load this file in your shell by running:
# . /opt/rt5/RT.env
# This will set the necessary environment variables to load and
# install Perl modules under the RT installation directory.
export RTHOME="/opt/rt5"
export PERL5LIB="$RTHOME/local/lib${PERL5LIB:+:$PERL5LIB}"
export PERL_CPANM_OPT="${PERL_CPANM_OPT:+$PERL_CPANM_OPT }--sudo --local-lib-contained=\"$RTHOME/local\""</pre>

=== 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. Here’s what the different parts of the command are doing:

* First we load the environment we set up in the last step, to install dependencies in RT's install directories.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=cpanm</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> installed all the necessary libraries under <code>PERL5LIB</code>.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5/RT.env
make fixdeps RT_FIX_DEPS_CMD=cpanm
sudo make install PERL5LIB="$PERL5LIB"</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-03T15:08:16Z

Brett: `make install` needs to know PERL5LIB

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Set up RT's install environment ===

These steps set things up so we can install RT's Perl dependencies alongside RT itself. Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5</pre>

Next we write an environment file that configures Perl tools, including RT itself, to load and install libraries under the RT install directory. Use an editor to save all the text below to <code>/opt/rt5/RT.env</code>. If you're using a different installation prefix, you should edit the line that sets <code>RTHOME</code> to the directory you chose. Otherwise, you shouldn't need to make any changes to this file.

<pre># RT.env
# When you want to do maintenance on RT (like installing or upgrading
# dependencies or plugins), load this file in your shell by running:
# . /opt/rt5/RT.env
# This will set the necessary environment variables to load and
# install Perl modules under the RT installation directory.
export RTHOME="/opt/rt5"
export PERL5LIB="$RTHOME/local/lib${PERL5LIB:+:$PERL5LIB}"
export PERL_CPANM_OPT="${PERL_CPANM_OPT:+$PERL_CPANM_OPT }--sudo --local-lib-contained=\"$RTHOME/local\""</pre>

=== 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. Here’s what the different parts of the command are doing:

* First we load the environment we set up in the last step, to install dependencies in RT's install directories.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=cpanm</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> installed all the necessary libraries under <code>PERL5LIB</code>.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5/RT.env
make fixdeps RT_FIX_DEPS_CMD=cpanm
sudo make install PERL5LIB="$PERL5LIB"</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-03-03T15:07:08Z

Brett: fix MariaDB GRANT syntax

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere' WITH GRANT OPTION;</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Set up RT's install environment ===

These steps set things up so we can install RT's Perl dependencies alongside RT itself. Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5</pre>

Next we write an environment file that configures Perl tools, including RT itself, to load and install libraries under the RT install directory. Use an editor to save all the text below to <code>/opt/rt5/RT.env</code>. If you're using a different installation prefix, you should edit the line that sets <code>RTHOME</code> to the directory you chose. Otherwise, you shouldn't need to make any changes to this file.

<pre># RT.env
# When you want to do maintenance on RT (like installing or upgrading
# dependencies or plugins), load this file in your shell by running:
# . /opt/rt5/RT.env
# This will set the necessary environment variables to load and
# install Perl modules under the RT installation directory.
export RTHOME="/opt/rt5"
export PERL5LIB="$RTHOME/local/lib${PERL5LIB:+:$PERL5LIB}"
export PERL_CPANM_OPT="${PERL_CPANM_OPT:+$PERL_CPANM_OPT }--sudo --local-lib-contained=\"$RTHOME/local\""</pre>

=== 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. Here’s what the different parts of the command are doing:

* First we load the environment we set up in the last step, to install dependencies in RT's install directories.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=cpanm</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> succeeds.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5/RT.env
make fixdeps RT_FIX_DEPS_CMD=cpanm
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-25T22:43:55Z

Brett: add a section about writing an environment file - to help with later maintenance

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html refer to the RT configure options documentation].

=== Set up RT's install environment ===

These steps set things up so we can install RT's Perl dependencies alongside RT itself. Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5</pre>

Next we write an environment file that configures Perl tools, including RT itself, to load and install libraries under the RT install directory. Use an editor to save all the text below to <code>/opt/rt5/RT.env</code>. If you're using a different installation prefix, you should edit the line that sets <code>RTHOME</code> to the directory you chose. Otherwise, you shouldn't need to make any changes to this file.

<pre># RT.env
# When you want to do maintenance on RT (like installing or upgrading
# dependencies or plugins), load this file in your shell by running:
# . /opt/rt5/RT.env
# This will set the necessary environment variables to load and
# install Perl modules under the RT installation directory.
export RTHOME="/opt/rt5"
export PERL5LIB="$RTHOME/local/lib${PERL5LIB:+:$PERL5LIB}"
export PERL_CPANM_OPT="${PERL_CPANM_OPT:+$PERL_CPANM_OPT }--sudo --local-lib-contained=\"$RTHOME/local\""</pre>

=== 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. Here’s what the different parts of the command are doing:

* First we load the environment we set up in the last step, to install dependencies in RT's install directories.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD=cpanm</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set earlier). It will only run if <code>fixdeps</code> succeeds.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5/RT.env
make fixdeps RT_FIX_DEPS_CMD=cpanm
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-14T14:29:55Z

Brett: restore lost line break

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-14T14:29:03Z

Brett: wording clarification

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the directory listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200 # mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-14T14:28:03Z

Brett: improve Red Hat VirtualHost filename

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/vhost_RT.conf</code>
(This filename needs to come after <code>ssl.conf</code> in the listing.)
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200 # mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-13T22:14:48Z

Brett: rt_admin needs createrole on PostgreSQL too

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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:

<pre>sudo createuser --createdb --createrole --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/zz_RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200 # mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-13T22:13:57Z

Brett: improve PostgreSQL createuser options

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser --createdb --login --pwprompt rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/zz_RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200 # mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-13T22:12:29Z

Brett: fix markup typo

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/zz_RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200 # mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<code><Section></code> pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-13T20:38:26Z

Brett: set FcgidIOTimeout

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/zz_RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# The default mod_fcgid timeout is 40 seconds.
# We increase it here to allow for large ticket searches, etc.
FcgidIOTimeout 200 # mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-13T20:38:09Z

Brett: move mod_fcgid settings inside the VirtualHost

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/zz_RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-13T20:33:52Z

Brett: remove unnecessary httpd Listen directive

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/zz_RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-13T20:30:27Z

Brett: add section about disabling default VirtualHosts

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Disable default VirtualHosts (optional) ===

If this web server is dedicated to RT, then you should disable the VirtualHosts that are included with the stock configuration. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dissite 000-default
sudo a2dissite default-ssl</pre>
|<pre>sudo sed -i~ '/^<VirtualHost\b/ , /^<\/VirtualHost\b/ d' /etc/httpd/conf.d/ssl.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/zz_RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-13T20:22:59Z

Brett: ensure httpd RT config loads after ssl.conf on Red Hat

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/zz_RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-07T22:36:56Z

Brett: `make install` needs to know PERL5LIB

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds. Setting <code>PERL5LIB</code> tells it where you installed those dependencies.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install PERL5LIB=/opt/rt5/local/lib</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2022-01-07T22:35:35Z

Brett: enable powertools repo required for some dependencies

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf config-manager --set-enabled powertools
sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

CustomizingWithCallbacks

2022-01-06T21:34:37Z

Brett: formatting cleanups

= Callbacks =

== Introduction ==

RT uses Callbacks for adding extensions into the Web GUI without modifying html code. Wikipedia defines a callback as “executable code that is passed as an argument to other code. It allows a lower-level software layer to call a subroutine (or function) defined in a higher-level layer." So callback in RT is a code that you can put into right place and it will be called when a user opens a page.

Callbacks are called on different places and have to be placed into directories

<pre><rt root>/local/html/Callbacks/<any directory>/<normal path to html-page>/<CallbackName></pre>

* <rt root> - we suppose you know where your RT is installed
* local - local directory for your customizations, [[CustomizingWithLocalDir]].
* html - directory with Mason components.
* Callbacks - directory for your Callbacks, create if it doesn't exist. It's Callbacks (lowercase "b") not CallBacks (uppercase "B"), not callbacks.
* <any directory> - one directory with any name you like. Call it MyCallbacks, his_callbacks or boo. The assumption is that you will group your callbacks, based on logic of your choosing. You can have many different callback groups, and the callback will be run for each of them.
* <normal path to html-page> - if a call you want to hook on is in <code>html/X/Y.html</code> file then you should create <code>X/Y.html</code> directory.
* <CallbackName> - name of the callback, each page may have multiple callbacks. By default is 'Default', but might be different. Read more about names below.

Places where callbacks are called look in the following way (RT 3.8):

$m->callback(
TicketObj => $TicketObj,
ARGSRef => \%ARGS,
CallbackName => 'Initial',
);

This is example from Ticket/Display.html in RT 3.8.7, full path to your code may look like this:

/opt/rt3/local/html/Callbacks/MyCallbacks/Ticket/Display.html/Initial

Arguments passed to callback function are passed into your code and you can use them to explore situation and modify behaviour.

== Finding callbacks ==

You can find all callbacks using grep command:

cd /opt/rt3/
find share/html | xargs grep '\->callback'

In RT 3.6 and older syntax is slightly different, old syntax is still valid and supported:

cd /opt/rt3/
find share/html | xargs grep 'Elements/Callback'

In RT 4.2.x these are most of them: [[RT_4.2_Callbacks]]

In RT-Assets 1.01 these are most of them: [[RT-Assets_1.01_Callbacks]]

== CallbackName ==

Each Mason component may call multiple callbacks, so each callback has a name. The name of the callback you figure out from arguments used to call $m->callback. Understandably, the argument to define a callback name is 'CallbackName' and if it's absent then 'Default' is used.

For example, the following callback call in Modify.html lacks a name, so its name (by default) is Default
<source lang="perl">
$m->callback( TicketObj => $TicketObj, CustomFields => $CustomFields, ARGSRef => \%ARGS );
</source>

== Sample callbacks ==

* [http://page.mi.fu-berlin.de/~pape/rt3/Callbacks/ Samples] from [[DirkPape]].
* [[AddCustomStyleSheet]]
* [[HideTransactions]]: Hide all transactions created by the system user.
* [[ShowPerQueueInstructions]]
* [[RequireCFResolve]]: Require CF value before resolve
* [[ToggleCFs]]: Hide certain Custom Fields unless a "control" CF is set to a specific value. Allows decluttering the user interface in the common case and exposes additional detail (CFs) when needed.

== Comments ==

There are some drawbacks, when customizing RT with the "Local" principle: If you have many customizations it is difficult to propagate customizations across version changes. This is mainly because

* when using the 'local' directory, you overlay '''files'''. If the original file is changed in a new release, e. g. a bug is fixed or a feature is added, you will not profit from this changes immediately, because your overlay is used.
* when using a XXX_Local.pm, you overlay '''methods''' and the same drawback as above will hit you if the method has been changed across releases.

For both customisation methods hold: They are not local enough! If you overlay, it might be possible that you overlay code (that you did not change) from earlier versions, that have been corrected or adopted to other changes in new versions and that is not compatible with the new version. Hence version upgrades may be complicated. I added two Sections above with customization methods I prefer, because we do many customizations, these are Patches and Callbacks. --[[DirkPape]]

==== GaryOberbrunner ====

Here's a sample [[ShowMessageStanza]] callback. Put this in /opt/rt3/share/html/Callbacks/*/Ticket/Elements/ShowMessageStanza/Default :

<%init>
my $val = $$content;
use bytes;
# Auto link 12-digit hex strings to a search page
$val =~ s{[0-9a-f]{12}}{<a href="http://my.example.com/search?$&">$&<\/a>}gi;
$$content = $val;
</%init>
<%args>
$content => undef
</%args>

Note that the stanza will appear in $$content, you just modify it in place. Thanks to Toby Darling for the code!

==Troubleshooting==
Did you clear your Mason cache? (See [[ClearMasonCache|CleanMasonCache]])

Did you restart your webserver process?

Are your Mason component settings accurate (in the web UI, visit Tools -> System Configuration and scroll down)?

Are your file and directory permissions for your new callback set properly?

Are you sure you have your callback arguments correct? Beware 'TicketObj' vs. 'Ticket' being passed!

ManualInstallation

2021-12-26T23:15:01Z

Brett: tweak logging configuration to account for command line tools

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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, I recommend logging primarily to syslog, so it goes
# to journald where it's easy to query and automatically gets rotated.
Set($LogToSyslog, 'info');

# When the RT server logs to stderr, that usually goes to your web server's
# error log. 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.
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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>

=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2021-12-23T19:32:10Z

Brett: remove the need for App::virtualenv by installing modules under /opt/rt5/local

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-App-cpanminus graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}



== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* <code>make dirs</code> sets up RT's directory structure. We do this first to install dependencies under it.
* <code>make fixdeps</code> actually installs those dependencies.
* <code>RT_FIX_DEPS_CMD='cpanm …'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command), and to install them where RT will automatically load them.
* <code>make install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>sudo make dirs
sudo ln -s . /opt/rt5/local/lib/perl5
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet --local-lib=/opt/rt5/local'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2021-12-23T19:08:43Z

Brett: recommend lynx over w3m—it's better maintained and packaged

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel lynx openssl openssl-devel
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2021-12-23T19:07:52Z

Brett: openssl is required; install it

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz openssl perl w3m</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel openssl openssl-devel w3m
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

AutomatedTests

2021-12-17T22:05:51Z

Brett: add docs

== Test Prerequisites ==

The best way to set up RT for running tests (both its own and extensions') is by running the following from a source checkout:

<pre>./configure.ac --with-db-type=TYPE --enable-layout=inplace [other options ...]
mkdir -p var</pre>

Then make sure all your dependencies are in place by running <code>make testdeps</code>. (If you need help with that part, check out [[ManualInstallation]].) If you're at that point and just want to get running as fast as possible, skip down to "Environment Variables to Control Tests." The next couple of sections give more background about what's going on.

=== Why a real database? ===

RT does include database-specific tests to check that various integrations work as expected. There's no good way to abstract these, so the test suite selects and runs the tests appropriate for your database.

=== Why an inplace layout? ===

The RT tests read the configuration file <code>RT_Config.pm</code> located in the directory named at <code>$RT::Generated::EtcPath</code>. If you use the default relative layout, or another layout intended for production like FHS, the tests will try to read your production configuration. That's probably not what you want.

Note that the tests '''only''' read <code>RT_Config.pm</code>. They do '''not''' read <code>RT_SiteConfig.pm</code> or files under <code>RT_SiteConfig.d</code>. You cannot change the behavior of tests by editing configuration there.

(This is another reason you need to specify a database type on the configure line: so it gets put into <code>RT_Config.pm</code>. There are environment variables to control most database parameters you need, but not the database type.)

== Environment Variables to Control Tests ==

=== Test RT Configuration ===

Except on SQLite, the tests need permission to create new databases; to create new users in the database; and to grant rights to those users. To run the tests at all, you '''must''' set the environment variables <code>RT_DBA_USER</code> and <code>RT_DBA_PASSWORD</code> with the username and password, respectively, of a database account that has all those rights.

The tests write a small <code>RT_SiteConfig.pm</code> it uses to configure itself. You can control some of the settings with environment variables. Refer to [https://docs.bestpractical.com/rt/latest/RT_Config.html the RT_Config documentation] for full details.

{| class="wikitable" style="width: 100%;"
! Environment variable
! Corresponding RT_SiteConfig setting
|-
|<code>RT_TEST_DB_SID</code>
|<code>$DatabaseName</code> (intended for Oracle only)
|-
|<code>RT_TEST_DB_HOST</code>
|<code>$DatabaseHost</code>
|-
|<code>RT_TEST_RT_HOST</code>
|<code>$DatabaseRTHost</code>
|-
|<code>RT_TEST_DEVEL</code>
|<code>$DevelMode</code>
|-
|<code>RT_TEST_PLUGINS</code>
|<code>@Plugins</code> (split on spaces)
|}

=== Test Selection ===

A few tests are skipped unless you do/n't set an environment variable.

{| class="wikitable" style="width: 100%;"
! Environment variable
! Controls tests
|-
|<code>RT_TEST_HEAVY</code>
|Set a string here to run tests that require relatively expensive database queries.
|-
|<code>RT_TEST_SMIME_REVOCATION</code>
|Set a string here to run SMIME revocation tests. Doing so downloads a certificate revocation list (CRL) from the public Internet.
|-
|<code>SKIP_GPG_TESTS</code>
|Set a string here to skip tests that run GnuPG
|}

=== Test Run Environment ===

{| class="wikitable" style="width: 100%;"
! Environment variable
! Controls tests
|-
|<code>RTHOME</code>
|Path to the RT source code checkout you use for testing. The core RT tests don't use this, but extensions usually do.
|-
|<code>RT_TEST_PARALLEL</code>
|Set a string here to notify the test suite that you're running tests in parallel. This changes some of the logic around database creation and elsewhere to avoid contention. You can set this even if you only have a single test runner.
You may also find some references to <code>RT_TEST_PARALLEL_NUM</code>. This is used by RT's Makefile to control how many test runners run in parallel. If you don't go through RT's Makefile, then nothing else uses that variable.
|-
|<code>RT_TEST_APACHE</code>
|Path to the <code>httpd</code> executable on your system
|-
|<code>RT_TEST_APXS</code>
|Path to the <code>apxs</code> executable on your system
|-
|<code>RT_TEST_APACHE_MODULES</code>
|Path to the directory where your httpd module <code>.so</code> files live
|}

== Running the Tests ==

Once you've set and exported all the environment variables you need, run the tests with <code>prove</code> from your source directory:

<pre>RT_TEST_PARALLEL=1 prove -w --lib --recurse --jobs=NUMBER t</pre>

{| class="wikitable" style="width: 100%;"
! Option
! Purpose
|-
|<code>-w</code>
|Enable warnings
|-
|<code>--lib</code>
|Load libraries from the <code>lib</code> directory (i.e., your source checkout)
|-
|<code>--recurse</code>
|Recurse through the path argument(s) to find and run all test <code>.t</code> files
|-
|<code>--jobs=NUMBER</code>
|Run <code>NUMBER</code> test runners in parallel
|-
|<code>t</code>
|Run tests under this path. You can specify other directories (some extensions have tests in <code>xt</code>), specific subdirectories, or even individual files.
|}

ManualInstallation

2021-12-08T17:06:37Z

Brett: emphasize that example rt-setup-fulltext-index output is just for illustration

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz perl w3m</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel openssl-devel w3m
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>### 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.
);</pre>
Copy the output generated when you run <code>rt-setup-fulltext-index</code> and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2021-12-08T17:03:47Z

Brett: suggest using $DatabaseAdmin

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz perl w3m</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel openssl-devel w3m
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> 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 adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy that output and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2021-12-06T22:52:15Z

Brett: add a section about enabling PostgreSQL password auth

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz perl w3m</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel openssl-devel w3m
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
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 <code>pg_hba.conf</code> file located at:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>/etc/postgresql/VERSION/main/pg_hba.conf</pre>
|<pre>/var/lib/pgsql/VERSION/data/pg_hba.conf</pre>
|}

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

<pre>host rt5 rt_user all md5
host rt5 rt_admin all md5</pre>

This configuration will let <code>rt_user</code> and <code>rt_admin</code> authorize themselves for the <code>rt5</code> database using an <code>md5</code> 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 [https://www.postgresql.org/docs/current/auth-pg-hba-conf.html the pg_hba.conf documentation] for more details.

Save your changes and reload the database:

<pre>sudo systemctl reload postgresql</pre>

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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');

# RT can log to syslog, stderr, and/or a dedicated file. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.
* '''If''' you are using an existing database server and the database adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy that output and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2021-11-30T15:42:31Z

Brett: remove the deprecated SSLCertificateChainFile

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz perl w3m</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel openssl-devel w3m
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
Set the password when prompted. Record this; you’ll need it later.

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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');

# RT can log to syslog, stderr, and/or a dedicated file. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.
* '''If''' you are using an existing database server and the database adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy that output and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2021-11-16T15:19:08Z

Brett: make install requires sudo

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz perl w3m</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel openssl-devel w3m
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
Set the password when prompted. Record this; you’ll need it later.

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps RT_FIX_DEPS_CMD='cpanm --sudo --quiet'
sudo make install</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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');

# RT can log to syslog, stderr, and/or a dedicated file. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.
* '''If''' you are using an existing database server and the database adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy that output and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/cert.pem
SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

== 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. [[Main Page|Head back to the main page]] to start exploring those topics.

ManualInstallation

2021-11-01T20:36:34Z

Brett: Fix Debian DB library package names

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz perl w3m</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel openssl-devel w3m
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
Set the password when prompted. Record this; you’ll need it later.

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq-dev</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb-dev libmariadb-dev-compat</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps install RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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');

# RT can log to syslog, stderr, and/or a dedicated file. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.
* '''If''' you are using an existing database server and the database adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy that output and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/cert.pem
SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

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

ManualInstallation

2021-10-26T19:17:25Z

Brett: convert to wiki markup

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.

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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz perl w3m</pre>
|<pre>sudo dnf install patch tar which gcc gcc-c++ perl-core perl-ExtUtils-MakeMaker graphviz expat-devel gd-devel openssl-devel w3m
sudo setenforce 0</pre>
|}

(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, 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 a few different databases, but the best supported options are PostgreSQL and MariaDB.

=== Installing and configuring the PostgreSQL server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}

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

<pre>sudo createuser -sP rt_admin</pre>
Set the password when prompted. Record this; you’ll need it later.

=== Installing the PostgreSQL client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libpq5</pre>
|<pre>sudo dnf install postgresql-devel</pre>
|}

Once this is done you can skip ahead to installing a web server.

=== Installing and configuring the MariaDB server ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install mariadb-server</pre>
|<pre>sudo dnf install mariadb-server</pre>
|}

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:

<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>
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. [https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet MariaDB’s <code>max_allowed_packet</code> 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.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/mysql/conf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|<pre>echo -e '[client-server]\nmax_allowed_packet=64M\n' | sudo tee /etc/my.cnf.d/max_allowed_packet.cnf
sudo systemctl reload mariadb</pre>
|}

=== Installing the MariaDB client libraries ===

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

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install libmariadb3</pre>
|<pre>sudo dnf install mariadb-devel</pre>
|}

== Install a web server with FastCGI ==

FastCGI is the best way to host RT’s web interface today. Installing the web server before RT makes the installation process simpler, because RT will be able to automatically some details about your web server like what user it runs as.

=== Installing Apache ===

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install apache2 libapache2-mod-fcgid</pre>
|<pre>sudo dnf install httpd mod_fcgid mod_ssl</pre>
|}


== Install Perl packaging tools: App::cpanminus and App::Virtualenv ==

App::cpanminus is a tool for installing and managing Perl modules from the popular CPAN repository. It does a lot of the same tasks, and follows a lot of the same UI conventions, as <code>pip</code>, <code>gem</code>, <code>npm</code>, and similar tools. You can install it from your distribution:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo apt install cpanminus</pre>
|<pre>sudo dnf install perl-App-cpanminus</pre>
|}

If your system doesn’t have a cpanminus package available, you can install it from source following the [https://metacpan.org/pod/App::cpanminus#INSTALLATION project instructions].

App::Virtualenv is a tool to create a dedicated space where you install and manage a self-contained set of Perl modules. (If you’re familiar with Python virtual environments, the concept is the same and App::Virtualenv follows a lot of the same usage patterns.) Using it helps avoid situations where changes to distribution packages might potentially break RT. This guide will illustrate creating and using a virtual environment for RT in <code>/opt/rt5venv</code>, but you can choose another location if you like.

<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>
Now whenever you want to work on RT (by installing it, upgrading dependencies, installing new extensions, etc.), you need to activate the virtualenv in your shell. This sets various environment variables that your shell uses to work on Perl modules in the right place. You activate the virtualenv by running:

<pre>. /opt/rt5venv/bin/activate</pre>
== Install RT ==

=== Get and unpack the RT source code ===

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

<pre>curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2</pre>
=== Pre-configure RT ===

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

* <code>PERL=/opt/rt5venv/bin/perl</code> ensures RT uses the virtualenv you set up.
* <code>--with-db-type=TYPE</code> - Replace <code>TYPE</code> with <code>Pg</code> for PostgreSQL, or <code>mysql</code> for MariaDB.
* <code>--prefix=/opt/rt5</code> sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>PERL=/opt/rt5venv/bin/perl ./configure --with-db-type=TYPE --prefix=/opt/rt5 --with-attachment-store=disk --enable-externalauth --enable-gd --enable-graphviz --enable-gpg --enable-smime</pre>
For more background, [https://docs.bestpractical.com/rt/latest/configure.html 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. Here’s what the different parts of the command are doing:

* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* <code>fixdeps</code> is RT’s command to install dependencies.
* <code>install</code> installs all of RT’s files under <code>/opt/rt5</code> (or the prefix directory you set in the previous step). It will only run if <code>fixdeps</code> succeeds.
* <code>RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</code> tells RT to use cpanminus to install dependencies (instead of the older, default <code>cpan</code> command).

Make sure you have <code>cd</code>ed into the RT source directory, and run:

<pre>. /opt/rt5venv/bin/activate
make fixdeps install RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</pre>
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 ===

[https://docs.bestpractical.com/rt/latest/RT_Config.html RT has many configuration options.] You can put configuration options in the file <code>/opt/rt5/etc/RT_SiteConfig.pm</code>, or in individual files under <code>/opt/rt5/etc/RT_SiteConfig.d/</code>. Use an editor to save all the text below to <code>/opt/rt5/etc/RT_SiteConfig.pm</code> (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 <code>EDIT WITH</code> appears.

<pre>
# 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');

# 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');

# RT can log to syslog, stderr, and/or a dedicated file. For a modern install,
# I recommend logging to syslog, so it goes to journald where it's easy to
# query and automatically gets rotated. You set both these paramaters to a
# standard log level: 'debug', 'info', 'notice', 'warning', 'error',
# 'critical', 'alert', or 'emergency'.
Set($LogToSyslog, 'info');
Set($LogToSTDERR, undef);

# 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;
</pre>
<code>RT_SiteConfig.pm</code> 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:

<pre>perl -c /opt/rt5/etc/RT_SiteConfig.pm</pre>
=== 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 <code>make install</code> and RT’s README file tell you to run <code>make initialize-database</code>. That just runs <code>rt-setup-database</code> for you. Running the tool directly makes it easier to pass the options you need.)

* <code>--action=init</code> tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.
* '''If''' you are using an existing database server and the database adminstrator has already created the user account and database for RT, then you can add the <code>--skip-create</code> 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. Refer to [https://docs.bestpractical.com/rt/latest/rt-setup-database.html the full rt-setup-database documentation] to learn more about those.
* The command reads files from RT’s <code>etc/</code> directory by default, so the easiest way to run it is to <code>cd /opt/rt5</code> first, and then it will find the necessary files automatically.

Run:

<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted.

=== Set up fulltext indexing ===

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

* <code>--noask</code> uses the default names for the index, which will be fine for a new install and simplifies the setup.
* <code>--dba=rt_admin</code> provides the username of the administrator account to use to do the setup. <code>rt_admin</code> is the name we used earlier to set up a new database server. You can specify a different value if your database has a different adminsitrator account.

Run:

<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask --dba=rt_admin</pre>
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:

<pre>Set( %FullTextSearch,
Enable => 1,
Indexed => 1,
# Additional output from rt-setup-fulltext-index should be here.
# The configuration varies by database type.
);</pre>
Copy that output and save it to the file <code>/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm</code>.

=== 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. <code>cd</code> to the directory where you extracted the RT source code, and run:

<pre>cd rt-5.0.2
sudo make fixperms</pre>
=== Verify the installation ===

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

<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>
Set the password when prompted. Record this; you’ll need it later.

== Set up RT’s web server ==

=== Configure Apache modules ===

You will need to have the following modules enabled in Apache to run RT. You should already have these installed if you followed the instructions above.

* <code>alias</code> (required to map URLs to RT)
* <code>fcgid</code> (required for Apache to talk to RT)
* <code>mpm_prefork</code> (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* <code>ssl</code> (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl</pre>
| <pre>echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf</pre>
|}

=== Configure an Apache VirtualHost ===

Create a file at the following location. You can change the <code>RT</code> part of the filename if you like, but the file must exist in this directory and have a <code>.conf</code> suffix.

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<code>/etc/apache2/sites-available/RT.conf</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
|<code>/etc/httpd/conf.d/RT.conf</code>
|}

Use an editor to save all the text below to the new <code>RT.conf</code> and then fill in settings for your site everywhere the text <code>EDIT WITH</code> appears.

<pre>
### Server-level settings
# These settings affect all of Apache. It is okay to put them here if Apache
# only hosts RT. If you are hosting other sites in the same Apache instance,
# you may need to put these settings in another file like
# (Debian/Ubuntu) /etc/apache2/conf-available/RT.conf
# (Red Hat/Fedora/CentOS) /etc/httpd/conf.d/RTserver.conf
# ... and ensure they do not conflict with settings required by other sites.

# mod_fcgid only allows 128KiB requests by default. This is too small for users
# to upload files to RT. You can ultimately choose any setting you're
# comfortable with; 70MiB here should allow most requests without being too
# open.
FcgidMaxRequestLen 73400320

<IfModule mod_ssl.c>
# Listen on the standard HTTPS port.
# You can change this to a nonstandard port if you must.
Listen 443
</IfModule>
### End server-level settings

### Primary RT VirtualHost
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTPS connections on all interfaces.
<VirtualHost *:443>
# EDIT HERE with the domain name of the web server.
ServerName rt.yourdomain.example.com
<IfModule mod_ssl.c>
SSLEngine on
# These specify the paths to the SSL certificate and private key Apache
# should use. These example paths are common for Let's Encrypt. If you
# don't use Let's Encrypt, the standard location for these files is under
# (Debian/Ubuntu) /etc/ssl
# (Red Hat/Fedora/CentOS) /etc/pki/tls
# EDIT HERE with the appropriate paths for your server
SSLCertificateFile /etc/letsencrypt/live/example.com/cert.pem
SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
</IfModule>
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
AddDefaultCharset UTF-8
DocumentRoot /opt/rt5/share/html
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
</VirtualHost>
### End primary RT VirtualHost

### Optional HTTPS Redirect VirtualHost
# Most modern servers support HTTPS and want all web traffic to go through it.
# This VirtualHost redirects normal HTTP traffic to HTTPS.
# You can delete this whole section if you don't want or need this.
<IfModule mod_ssl.c>
# You can change both the bind address and/or the port here as required.
# This default will listen for HTTP connections on all interfaces.
<VirtualHost *:80>
SSLEngine off
# EDIT HERE both lines below with the domain name of your web server.
ServerName rt.yourdomain.example.com
Redirect permanent / https://rt.yourdomain.example.com/
</VirtualHost>
</IfModule>
### End optional HTTPS Redirect VirtualHost
</pre>
After you’ve edited the file, load the configuration with:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo systemctl reload apache2</pre>
|<pre>sudo systemctl reload httpd</pre>
|}

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the
<Section>
pairs. Edit again and reload the configuration until it succeeds without output.

=== 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 <code>root</code> and the password you set previously.

If you run into trouble, the first place to look for more information is by reading Apache’s error log:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo less /var/log/apache2/error.log</pre>
|<pre>sudo less /var/log/httpd/error.log</pre>
|}

== 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 cannot connect or authenticate directly to external mail servers. In the default configuration, RT runs the standard <code>sendmail</code> command. There are [https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail 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 <code>sendmail</code> command that connects to an external mail server for you, like ssmtp. 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 <code>rt-mailgate</code> 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 <code>/etc/aliases</code> entries look like:

<pre>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/"</pre>
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 <code>rt-mailgate</code>. 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 <code>rt-mailgate</code> 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 <code>rt-mailgate</code> and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

== Set up RT’s background jobs ==

Create a file <code>/etc/cron.d/rt</code> 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.

<pre>
# Update the fulltext index with new ticket data
*/3 * * * * root /opt/rt5/sbin/rt-fulltext-indexer
# Email out dashboards that users have subscribed to
0 * * * * root /opt/rt5/sbin/rt-email-dashboards
# Clean old sessions from the database
10 3 * * * root /opt/rt5/sbin/rt-clean-sessions --older 8d
# Email out weekly digests for users who have requested it
50 4 * * Mon root /opt/rt5/sbin/rt-email-digest -m weekly
# Email out daily digests for users who have requested it
50 5 * * * root /opt/rt5/sbin/rt-email-digest -m daily
</pre>
You can run all these jobs as the same user that runs your web server, rather than root. Run:

{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|<pre>sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt</pre>
|<pre>sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt</pre>
|}

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