Difference between revisions of "ManualInstallation"

From Request Tracker Wiki
Jump to navigation Jump to search
 
(modernize instructions for RT5 and contemporary distros)
(8 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Outdated}}
Prev: [[ManualRequirements]] --- Up: [[UserManual]] --- Next: [[ManualApacheConfig]]
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.


= GENERAL INSTALLATION =
This guide assumes:


== 1. Unpack ==
* 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.


== 2. Run the configure script ==
## Install the base dependencies


From within the temporary directory you just created, run the "configure" script. You'll want to read this entire section, and decide on the option switches which you will want to specify to configure, before you actually run it. Having multiple console windows available during (this or any other) install is '''exceptionally''' helpful.
These are required by RT, either to run or to install the dependencies.


To see a list of configuration options, use the "help" flag, which will show you a list of options:
{| 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>
|}


./configure --help
(Turning off SELinux enforcement is required on Red Hat-based distributions because, as of October 2021, nobody has written a policy for RT.)


We've also listed the options here. Defaults are specified in brackets.
## Install a database


Configuration:
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.
  -h, --help              display this help and exit
  --help=short        display options specific to this package
  --help=recursive    display the short help of all the included packages
  -V, --version          display version information and exit
  -q, --quiet, --silent  do not print `checking...' messages
  --cache-file=FILE  cache test results in FILE [disabled]
  -C, --config-cache      alias for `--cache-file=config.cache'
  -n, --no-create        do not create output files
  --srcdir=DIR        find the sources in DIR [configure dir or `..']


=== Installation directory ===
### Installing and configuring the PostgreSQL server


By default, `make install' will install all the files in `/opt/rt3/bin', `/opt/rt3/lib' etc. You can specify an installation prefix other than `/opt/rt3' using `--prefix', for instance `--prefix=$HOME'.
If you want to install a fresh PostgreSQL database server alongside RT:


--prefix=PREFIX        install architecture-independent files in PREFIX
{| style="width: 100%;"
                          [/opt/rt3]
! style="width: 50%;"|Debian/Ubuntu
--exec-prefix=EPREFIX  install architecture-dependent files in EPREFIX
! style="width: 50%;"|Red Hat/Fedora/CentOS
                          [PREFIX]
|-
|<pre>sudo apt install postgresql</pre>
|<pre>sudo dnf install postgresql-server</pre>
|}


=== Installation directory fine-tuning ===
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:


Here are some more configure switches you can use to fine tune exactly where the install process should put its files. If you don't know why or to where you might change these, just accept the default.
<pre>sudo createuser -sP rt_admin</pre>


--bindir=DIR          user executables [EPREFIX/bin]
Set the password when prompted. Record this; you'll need it later.
--sbindir=DIR          system admin executables [EPREFIX/sbin]
--libexecdir=DIR      program executables [EPREFIX/libexec]
--datadir=DIR          read-only architecture-independent data [PREFIX/share]
--sysconfdir=DIR      read-only single-machine data [PREFIX/etc]
--sharedstatedir=DIR  modifiable architecture-independent data [PREFIX/com]
--localstatedir=DIR    modifiable single-machine data [PREFIX/var]
--libdir=DIR          object code libraries [EPREFIX/lib]
--includedir=DIR      C header files [PREFIX/include]
--oldincludedir=DIR    C header files for non-gcc [/usr/include]
--infodir=DIR          info documentation [PREFIX/info]
--mandir=DIR          man documentation [PREFIX/man]


Optional Features:
### Installing the PostgreSQL client libraries


--disable-FEATURE      do not include FEATURE (same as --enable-FEATURE=no)
These are required for RT to be able to talk to any PostgreSQL server.
--enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
--enable-layout=LAYOUT  Use a specific directory layout (Default: RT3) Optional Packages:
--with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
--without-PACKAGE      do not use PACKAGE (same as --with-PACKAGE=no)
--with-rt-group=GROUP  group to own all files (default: rt)
--with-bin-owner=OWNER  user that will own rt executable files (default root)
--with-libs-owner=OWNER user that will own RT libraries (default root)
--with-libs-group=GROUP group that will own rt binaries (default bin)
--with-db-type=TYPE    sort of database RT will use (default: mysql; others are
                        Oracle, Informix, Pg, SQLite)
--with-db-host=HOSTNAME FQDN of database server (default: localhost)
--with-db-port=PORT    port on which the database listens on
--with-db-rt-host=HOSTNAME
                        FQDN of database server (default: localhost)
--with-db-dba=DBA      name of database administrator (default: root)
--with-db-database=DBNAME
                        name of the database to use (default: rt3)
--with-db-rt-user=DBUSER
                        name of database user (default: rt_user)
--with-db-rt-pass=PASSWORD
                        password for database user (default: rt_pass)
--with-web-user=USER    user the web server runs as (default: www)
--with-web-group=GROUP  group the web server runs as (default: www)
--disable-option-checking  ignore unrecognized --enable/--with options
--disable-FEATURE      do not include FEATURE (same as --enable-FEATURE=no)
--enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
--enable-layout=LAYOUT  Use a specific directory layout (Default: relative)
--enable-devel-mode    Turn on development aids that might hurt you in production
--enable-graphviz      Turns on support for RT's GraphViz dependency charts
--enable-gd            Turns on support for RT's GD pie and bar charts
--enable-gpg            Turns on GNU Privacy Guard (GPG) support


Some influential environment variables:
{| 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>
|}


PERL        Perl interpreter command
Once this is done you can skip ahead to installing a web server.


Use these variables to override the choices made by 'configure' or to help it to find libraries and programs with unusual names/locations.
### Installing and configuring the MariaDB server


Look at all the available flags and determine your RT install preferences, then
If you want to install a fresh MariaDB database server alongside RT:


./configure (with the flags you want)
{| 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>
|}


You might find it useful to put all your switches into a script in your build directory called <code>build</code>, so that if you need to run it more than once, or refer back to it, it's been saved somewhere. You can then do your build by merely typing
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:


./build
<pre>sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';</pre>


== 3. Dependencies ==
Record your passphrase; you'll need it later.


After you build RT, but before you can run it, you must satisfy RT's myriad dependencies. RT makes use of many components external to the distributed package, and these must all be installed before the package will run. You '''must always''' do this step on install/update or upgrade actions.
### Adjust MariaDB's max_allowed_packet setting


First of all, check for compliance, using the CPAN-based dependency checker (if you have never run CPAN on this machine as this user, see below to manually initialize it first, or else :-):
You need to consider this step whether you install the database locally, or use an existing one already running. [MariaDB's `max_allowed_packet` setting](https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet) 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.


make testdeps
{| 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>
|}


or (the long way)
### Installing the MariaDB client libraries


perl sbin/rt-test-dependencies --with-&lt;databasename&gt; --with-&lt;web-environment&gt;
These are required for RT to be able to talk to any MariaDB server.


Instead of &lt;databasename&gt;, type either mysql, postgres or oracle. Instead of &lt;web-environment&gt;, type either fastcgi, modperl1, or modperl2.
{| 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>
|}


If there are unsatisfied dependencies (that is, if you are missing stuff), you will see complaints like "such-and-such not installed". Look carefully; these don't stand out that much. Go, ye, and fix dependencies. As root:
## Install a web server with FastCGI


make fixdeps
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.


or
### Installing Apache


perl sbin/rt-test-dependencies \
{| style="width: 100%;"
--with-&lt;databasename&gt; --with-&lt;web-environment&gt; --install
! 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>
|}


'''NOTE:''' If you have having difficulties with 'make fixdeps' due to errors like:
<!-- ### Installing nginx -->


<nowiki>==&gt; Couldn't mkdir '/root/.cpan/build/tmp': File exists          &lt;==
## Install Perl packaging tools: App::cpanminus and App::Virtualenv
      </nowiki>


'''NOTE: '''Some Perl Packages are using an build routine ( like DateTime modules) , but CPAN can't handle such routines based on build so you have to install this manually.
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 `pip`, `gem`, `npm`, and similar tools. You can install it from your distribution:


Set the following environment variable to tell fixdeps to invoke CPAN as a command line tool:
{| 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>
|}


RT_FIX_DEPS_CMD='/usr/bin/perl -MCPAN -e"install %s"'
If your system doesn't have a cpanminus package available, you can install it from source following the [project instructions](https://metacpan.org/pod/App::cpanminus#INSTALLATION).


Make sure to export this variable with
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 `/opt/rt5venv`, but you can choose another location if you like.


export RT_FIX_DEPS_CMD
<pre>cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv</pre>


'''NOTE:''' if you've never run CPAN on your machine as the user whom you are building RT as, run it first or this part of the install will not be fun.
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:


perl -MCPAN -e shell
<pre>. /opt/rt5venv/bin/activate</pre>


You'll be walked through the configuration process. When you're done:
## Install RT


quit
### Get and unpack the RT source code


'''NOTE:''' if things are still messed up, you are logged in as root, right?
Download the latest source code using the link on the [RT download page](https://bestpractical.com/download-page), extract it using `tar -xf`, and `cd` into the source code directory to run the rest of the commands in this section. For example:


Alternately, you could install missing items by hand. 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>


perl -MCPAN -e 'install DBD::mysql'
### Pre-configure RT


would install DBD::mysql.
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:


'''NOTE:''' Some modules may require environment variables defined, for example <code>Apache::Request</code>.
* `PERL=/opt/rt5venv/bin/perl` ensures RT uses the virtualenv you set up.
* `--with-db-type=TYPE` - Replace `TYPE` with `Pg` for PostgreSQL, or `mysql` for MariaDB.
* `--prefix=/opt/rt5` sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
* The rest of the options tell RT to install additional dependencies for optional features.


'''NOTE:''' If you are using FastCGI, you will need to make sure that the FCGI module is installed. If not, run
Make sure you have `cd`ed into the RT source directory, and run:


perl -MCPAN -e 'install FCGI'
<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>


or something equivalent.
For more background, [refer to the RT configure options
documentation](https://docs.bestpractical.com/rt/latest/configure.html).


### Install RT and its Perl dependencies


'''NOTE:''' If you are using RHEL5, you may end up with all sorts of errors. These can be fixed by installing Scalar::Util
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:


perl -MCPAN -e 'install Scalar::Util'
* First we make sure the virtualenv is activated in our shell, so dependencies are installed there.
* `fixdeps` is RT's command to install dependencies.
* `install` installs all of RT's files under `/opt/rt5` (or the prefix directory you set in the previous step). It will only run if `fixdeps` succeeds.
* `RT_FIX_DEPS_CMD='cpanm --sudo --quiet'` tells RT to use cpanminus to install dependencies (instead of the older, default `cpan` command).


Re-check to make sure everything was installed properly:
Make sure you have `cd`ed into the RT source directory, and run:


make testdeps
<pre>. /opt/rt5venv/bin/activate
make fixdeps install RT_FIX_DEPS_CMD='cpanm --sudo --quiet'</pre>


or
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.


perl sbin/rt-test-dependencies --with-&lt;databasename&gt; --with-&lt;web-environment&gt;
### Configure RT


'''NOTE:''' Some versions of the <code>MIME::Tools</code> package will not install cleanly. Specifically, <code>MIME::Tools</code> version 5.427 is missing a dependency that will not be installed automatically by the CPAN shell. It requires <code>MIME::Base64</code> to be installed first. Otherwise, <code>MIME::Entity</code> will fail during testing and terminate the installation. Install <code>MIME::Base64</code> explicitly, either manually or using:
[RT has many configuration options.](https://docs.bestpractical.com/rt/latest/RT_Config.html) You can put configuration options in the file `/opt/rt5/etc/RT_SiteConfig.pm`, or in individual files under `/opt/rt5/etc/RT_SiteConfig.d/`. Use an editor to save all the text below to `/opt/rt5/etc/RT_SiteConfig.pm` (you can just overwrite the existing file, or add this to the bottom of what's there) and then fill in settings for your site everywhere the text `EDIT WITH` appears.


<nowiki># perl -MCPAN -e "install 'MIME::Base64'"
<pre>
     
# Single-quote all values EXCEPT the special value `undef`
      </nowiki>
# that turns off a setting.


Thereafter, installing dependencies worked without further problems for me.
# 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');


- Ed Eaglehouse
# 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');


'''NOTE:''' graphviz dependencies can be met with packages from here: http://www.graphviz.org/Download..php. On [[CentOS]] 5.4, adding the repository provided by graphviz.org and doing
# 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);


yum install graphviz graphviz-gd graphviz-devel
# 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');


cleared up all related requirements. Installing additional packages via
# Perl expects to find this 1 at the end of the file.
1;
</pre>


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


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


yum install expat expat-devel
### Set up RT's database


resolved all dependency problems. Doing 'make fixdeps' after a configure stage such as
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.


./configure --with-web-handler=modperl2 --enable-graphviz --enable-gd --enable-gpg
(The instructions from `make install` and RT's README file tell you to run `make initialize-database`. That just runs `rt-setup-database` for you. Running the tool directly makes it easier to pass the options you need.)


completed with all dependencies met.
* `--action=init` tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
* `--dba=rt_admin` provides the username of the administrator account to use to do the setup. `rt_admin` 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 `--skip-create` option.
* **If** you have a less common database setup, this tool has additional options to give you finer-grained control over what steps are run and how. Refer to [the full rt-setup-database documentation](https://docs.bestpractical.com/rt/latest/rt-setup-database.html) to learn more about those.
* The command reads files from RT's `etc/` directory by default, so the easiest way to run it is to `cd /opt/rt5` first, and then it will find the necessary files automatically.


== 4. rt group ==
Run:


Create a new Unix group called 'rt' (or whatever you gave to the --with-rt-group option to the configure script).
<pre>cd /opt/rt5
sudo sbin/rt-setup-database --action=init --dba=rt_admin</pre>


== 5. For new installations only ==
Enter the password for your database administrator account when prompted.


If you're upgrading within the RT 3.x series, '''skip to step 6''':
### Set up fulltext indexing


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


As root and from within the rt build directory, type:
* `--noask` uses the default names for the index, which will be fine for a new install and simplifies the setup.
* `--dba=rt_admin` provides the username of the administrator account to use to do the setup. `rt_admin` 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.


make install
Run:


Now you need to modify the installed [=etc/[[RT SiteConfig|RT_SiteConfig]].pm] to specify the connections to your DBMS engine (wtf shall I write here?!) and then type:
<pre>sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask --dba=rt_admin</pre>


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


For some database backends ([[MySQL]] at least) it is not able to create the database user. So you have to create that user beforehand and you have to give it rights for the database.
<pre>Set( %FullTextSearch,
    Enable    => 1,
    Indexed    => 1,
    # Additional output from rt-setup-fulltext-index should be here.
    # The configuration varies by database type.
);</pre>


For [[MySQL]] with the default [=$DatabaseUser], [=$DatabaseName] and [=$DatabasePassword], do this SQL command (as root database user):
Copy that output and save it to the file `/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm`.


GRANT ALL PRIVILEGES ON rt4.* TO 'rt_user'@'localhost' IDENTIFIED BY 'rt_pass'
### Set permissions


Replace the values 'rt4', 'rt_user', 'localhost' and 'rt_pass' by whatever is appropriate for you.
All of RT's configuration files should be readable by the user that runs the web server, and no other users, in order to protect sensitive information like the database password. RT provides a command to set permissions appropriately according to your distribution and configuration. `cd` to the directory where you extracted the RT source code, and run:


=== 5.2 Drop DB if something goes wrong ===
<pre>cd rt-5.0.2
sudo make fixperms</pre>


If the make fails, type:
### Verify the installation


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


fix whatever's broken, and start over from step "init DB" step
<pre>sudo /opt/rt5/sbin/rt-passwd root</pre>


=== 5.3 if still failing... ===
Set the password when prompted. Record this; you'll need it later.


If make install still fails, look in <code>/etc/httpd/httpd.conf</code> or <code>/etc/httpd/conf/commonhttpd.conf</code> (or wherever your httpd.conf is; this may vary by Unix distribution; <code>locate httpd.conf</code> may help) for a line that reads "Group &lt;something&gt;" and another that reads "User &lt;somebody&gt;"
## Set up RT's web server


Go to your RT source directory and type (without the brackets, substituting the right Group and User from the file you just looked at):
### Configure Apache modules


./configure --with-web-group=&lt;something&gt; --with-web-user=&lt;somebody&gt;
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.


Skip to step 7.
* `alias` (required to map URLs to RT)
* `fcgid` (required for Apache to talk to RT)
* `mpm_prefork` (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
* `ssl` (required to serve HTTPS; optional otherwise)


=== 5.4 initdb fails ===
Enable them following these instructions:


The defaults were changed in [[PostgreSQL]] 8.1 and now tables are created without [[OIDs]]. One of workarounds is to add the following block at the top of <code>etc/schema.Pg</code> file:
{| 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
-- Enforce OID creation for 8.1+
--
set default_with_oids = 't';


Once it's done "make initialize-database" will work perfectly.
Create a file at the following location. You can change the `RT` part of the filename if you like, but the file must exist in this directory and have a `.conf` suffix.


-- Added by GalaxyMaster &lt;galaxy at openwall.com&gt;
{| style="width: 100%;"
! style="width: 50%;"|Debian/Ubuntu
! style="width: 50%;"|Red Hat/Fedora/CentOS
|-
|`/etc/apache2/sites-available/RT.conf`
Then after you create the file, run: `sudo a2ensite RT`
|`/etc/httpd/conf.d/RT.conf`
|}


== 6. For an Upgrade ==
Use an editor to save all the text below to the new `RT.conf` and then fill in settings for your site everywhere the text `EDIT WITH` appears.


For upgrading within the RT 3.x series - if you are not upgrading or have already completed step 5, '''skip to step 7'''.
<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.


As root, type:
# 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


make upgrade
<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


(replace "make" with the local name for Make, if you need to)
### 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


This will build new executable files, config files and libraries without overwriting your RT database.
### 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>


It may then instruct you to update your RT system database objects
After you've edited the file, load the configuration with:


== 7. Configuration ==
{| 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>
|}


Edit [=etc/[[RT SiteConfig|RT_SiteConfig]].pm] in your RT installation directory, by specifying any values you need to change from the defaults as defined in RT_Config.pm. It is easiest to do this by copying RT_Config.pm to RT_SiteConfig.pm, and then uncommenting and changing anything you need to set, though perhaps this isn't quite the '''best''' approach.
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.


In many cases sensible defaults have been included. In others, you must supply a value. Some values (such as the RT log directory) will come from values you supplied in the Makefile. You'll find further explanation inline in the [[RT SiteConfig|RT_SiteConfig]].pm file. You should look at and consider changing the following entries:
### Verify the web interface


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


which is the password the [[DatabaseUser]] should use to access the database.
If you run into trouble, the first place to look for more information is by reading Apache's error log:


'''NOTE:''' Some [[MySQL]] users have had trouble with passwords of longer than 8 characters; if you cannot connect, try a password of 8 characters or fewer.
{| 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>
|}


$CanonicalizeEmailAddressMatch = 'subdomain.example.com$';
## Set up RT's mail server
$CanonicalizeEmailAddressReplace = 'example.com';


The $[[CanonicalizeEmailAddress]] variables allow you to keep incoming messages consistent, such as when a site removes the subdomain from an email address. In the example presented by the defaults, if messages from your organization sometimes come from exchange.example.com and sometimes from example.com, you'd set $[[CanonicalizeEmailAddressMatch]] to exchange.example.com and $[[CanonicalizeEmailAddressReplace]] to example.com
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.


$SenderMustExistInExternalDatabase = undef;
### Sending Mail


If $[[SenderMustExistInExternalDatabase]] is true, RT will refuse to auto-create non-staff accounts for unknown users filing new tickets by email if you are using the "[[LookupSenderInExternalDatabase]]" option elsewhere in [[RT SiteConfig|RT_SiteConfig]].pm. Instead, an error message will be returned and RT will forward the user's message to $[[RTOwner]] as defined in [[RT SiteConfig|RT_SiteConfig]].pm. If you are not using $[[LookupSenderInExternalDatabase]], this option has no effect. If you define an [[AutoRejectRequest]] template, RT will use this template for the rejection message.
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 `sendmail` command. There are [configuration options to send mail through different commands](https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail) if you need.


$CorrespondAddress = 'RT::CorrespondAddress.not.set';
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.
$CommentAddress = 'RT::CommentAddress.not.set';


$[[CorrespondAddress]] and $[[CommentAddress]] are the default addresses that will be listed in both From: and Reply-To: headers of reply and comment mail, respectively, sent by RT, unless they are overridden by a queue-specific address.
Other software is available that provides a slimmer version of the `sendmail` 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.)


$MailCommand = 'sendmailpipe';
### Receiving email


$[[MailCommand]] defines which method RT will use to try to send mail. We know sendmailpipe works fairly well. If sendmailpipe doesn't work well for you, try sendmail. Note that you should remove the '-t' from $[[SendmailArguments]] if you use sendmail rather than sendmailpipe. Also note that sendmailpipe and sendmail aren't the names of commands on your system, but instructions that tell RT what mail delivery subsystem to try.
RT installs a command called `rt-mailgate` that receives an email on standard input and posts it to RT's REST web interface, where it gets saved in the database and added to a ticket. You need to arrange for a way to send incoming email to this command.


*Don't forget to restart the Apache webserver after doing changes in [[RT SiteConfig|RT_SiteConfig]].pm!* This is true of any change, but we mention it here since this is the configuration option you're most likely to have to experiment with.
The most common setup is to have an MTA on the same box as RT receive email directly, and then set up mail aliases that call this command when mail comes in. Example `/etc/aliases` entries look like:


$SendmailArguments = "-oi -t";
<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>


$[[SendmailArguments]] defines what flags to pass to $Sendmail, assuming you picked sendmail or sendmailpipe as the $[[MailCommand]]. If you picked sendmailpipe, then $[[SendmailArguments]] must include the "-t" flag. The default options are good for most sendmail wrappers and workalikes.
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.


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


If you selected sendmailpipe as $[[MailCommand]], you must specify the path to your sendmail executable file in $[[SendmailPath]]. If you did not select sendmailpipe this has no effect.
This is much less common, but it might help to know that `rt-mailgate` doesn't have to run on the same system as RT itself. It just needs to be able to connect to RT's web interface. If you don't have any other options, you can install the RT software on a different system that receives email, and configure *that* system to run `rt-mailgate` and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.


In case of '''Exim''', the following configuration works:
## Set up RT's background jobs


Set($MailCommand , 'sendmail');
Create a file `/etc/cron.d/rt` with the following content. You may edit all of the time fields as you see fit. Refer to the crontab(5) man page for details about their definitions.
Set($SendmailArguments , "-bm -- &lt;your email address&gt;");
Set($SendmailPath, "/usr/sbin/exim4");
Set($NotifyActor, 1);
$Timezone = 'US/Eastern';


$Timezone is used to convert times entered by users into GMT and back again. It should be set to a timezone recognized by your local Unix box, and -- in general -- you should pick the timezone the majority of your users reside in.
<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>


$UseFriendlyToLine = 0;
You can run all these jobs as the same user that runs your web server, rather than root. Run:


RT can set a "friendly", rather than blank, To: header when sending messages to Ccs or [[AdminCcs]]. This feature does not work with Sendmail(tm)-brand sendmail. If you are using sendmail, rather than postfix, qmail, exim, or some other program, you must disable this option (by setting it to 0 rather than 1).
{| 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>
|}


$WebPath = "";
## Set up RT


A variable used to help RT construct [[URLs]] that point back to RT. If you've put RT somewhere other than at the root of your webserver, you need to define a [[WebPath]]. RT uses this in the construction of relative [[URLs]]. $[[WebPath]] requires a leading / but no trailing /
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.
 
Example: if your installation is at
 
http://www.fsck.com/rt/
 
set this to "/rt".
 
$WebBaseURL = "http://not.configured:80";
 
A variable used to help RT construct [[URLs]] that point back to RT. $[[WebBaseURL]] is the base of the URL. it should usually include the scheme, the host, and the port if non-standard.
 
Example: "https://fsck.com" or "http://fsck.com:88"
 
$[[WebBaseURL]] doesn't need a trailing /
 
$WebURL = $WebBaseURL . $WebPath . "/";
 
A variable used to help RT construct [[URLs]] that point back to RT. [=$[[WebURL]]] is the combination of [=$[[WebBaseURL]]] and [=$[[WebPath]]]. Generally, you shouldn't change it.
 
$WebImagesURL = $WebURL . "/NoAuth/images/";
 
[=$[[WebImagesURL]]] points to the base URL where RT can find its images. If you're running the [[FastCGI]] version of the RT web interface, you should make RT's [=[[WebRT]]/html/[[NoAuth]]/images] directory available on a static web server and supply that URL as [=$[[WebImagesUrl]]] -- alternately, you can tell Apache not to run it through [[FastCGI]].
 
== THEN ==
 
Configure web server, read [[ManualApacheConfig]]
 
----
 
Prev: [[ManualRequirements]] --- Up: [[UserManual]] --- Next: [[ManualApacheConfig]]
[[Category:RT User Manual]]

Revision as of 17:08, 4 October 2021

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.
    1. Install the base dependencies

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

Debian/Ubuntu Red Hat/Fedora/CentOS
sudo apt install autoconf build-essential curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz perl w3m
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

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

    1. 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.

      1. Installing and configuring the PostgreSQL server

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

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

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

sudo createuser -sP rt_admin

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

      1. Installing the PostgreSQL client libraries

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

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

Once this is done you can skip ahead to installing a web server.

      1. Installing and configuring the MariaDB server

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

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

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

sudo mysql
mysql# GRANT ALL PRIVELEGES WITH GRANT OPTION ON rt5 TO rt_admin@localhost IDENTIFIED BY 'YourPassphraseHere';

Record your passphrase; you'll need it later.

      1. Adjust MariaDB's max_allowed_packet setting

You need to consider this step whether you install the database locally, or use an existing one already running. [MariaDB's `max_allowed_packet` setting](https://mariadb.com/kb/en/server-system-variables/#max_allowed_packet) functionally limits the size of attachments in RT. The default is 16MiB, which is too small for most installations. You can ultimately choose any setting you're comfortable with; 64MiB here should allow most requests without being too open.

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

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

Debian/Ubuntu Red Hat/Fedora/CentOS
sudo apt install libmariadb3
sudo dnf install mariadb-devel
    1. 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.

      1. Installing Apache
Debian/Ubuntu Red Hat/Fedora/CentOS
sudo apt install apache2 libapache2-mod-fcgid
sudo dnf install httpd mod_fcgid mod_ssl


    1. 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 `pip`, `gem`, `npm`, and similar tools. You can install it from your distribution:

Debian/Ubuntu Red Hat/Fedora/CentOS
sudo apt install cpanminus
sudo dnf install perl-App-cpanminus

If your system doesn't have a cpanminus package available, you can install it from source following the [project instructions](https://metacpan.org/pod/App::cpanminus#INSTALLATION).

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 `/opt/rt5venv`, but you can choose another location if you like.

cpanm --sudo App::Virtualenv
sudo virtualenv.pl --create --empty /opt/rt5venv

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:

. /opt/rt5venv/bin/activate
    1. Install RT
      1. Get and unpack the RT source code

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

curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz
tar -xf rt-5.0.2.tar.gz
cd rt-5.0.2
      1. 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:

  • `PERL=/opt/rt5venv/bin/perl` ensures RT uses the virtualenv you set up.
  • `--with-db-type=TYPE` - Replace `TYPE` with `Pg` for PostgreSQL, or `mysql` for MariaDB.
  • `--prefix=/opt/rt5` sets the directory where RT will install all of its libraries, tools, and supporting files. You can choose another path if you like.
  • The rest of the options tell RT to install additional dependencies for optional features.

Make sure you have `cd`ed into the RT source directory, and run:

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

For more background, [refer to the RT configure options documentation](https://docs.bestpractical.com/rt/latest/configure.html).

      1. 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.
  • `fixdeps` is RT's command to install dependencies.
  • `install` installs all of RT's files under `/opt/rt5` (or the prefix directory you set in the previous step). It will only run if `fixdeps` succeeds.
  • `RT_FIX_DEPS_CMD='cpanm --sudo --quiet'` tells RT to use cpanminus to install dependencies (instead of the older, default `cpan` command).

Make sure you have `cd`ed into the RT source directory, and run:

. /opt/rt5venv/bin/activate
make fixdeps install RT_FIX_DEPS_CMD='cpanm --sudo --quiet'

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.

      1. Configure RT

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

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

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

# 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;

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

perl -c /opt/rt5/etc/RT_SiteConfig.pm
      1. Set up RT's database

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

(The instructions from `make install` and RT's README file tell you to run `make initialize-database`. That just runs `rt-setup-database` for you. Running the tool directly makes it easier to pass the options you need.)

  • `--action=init` tells the tool to create the user, the database, the tables inside it, and insert core data RT needs to function.
  • `--dba=rt_admin` provides the username of the administrator account to use to do the setup. `rt_admin` 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 `--skip-create` option.
  • **If** you have a less common database setup, this tool has additional options to give you finer-grained control over what steps are run and how. Refer to [the full rt-setup-database documentation](https://docs.bestpractical.com/rt/latest/rt-setup-database.html) to learn more about those.
  • The command reads files from RT's `etc/` directory by default, so the easiest way to run it is to `cd /opt/rt5` first, and then it will find the necessary files automatically.

Run:

cd /opt/rt5
sudo sbin/rt-setup-database --action=init --dba=rt_admin

Enter the password for your database administrator account when prompted.

      1. Set up fulltext indexing

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

  • `--noask` uses the default names for the index, which will be fine for a new install and simplifies the setup.
  • `--dba=rt_admin` provides the username of the administrator account to use to do the setup. `rt_admin` 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:

sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask --dba=rt_admin

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

Set( %FullTextSearch,
    Enable     => 1,
    Indexed    => 1,
    # Additional output from rt-setup-fulltext-index should be here.
    # The configuration varies by database type.
);

Copy that output and save it to the file `/opt/rt5/etc/RT_SiteConfig.d/FulltextIndex.pm`.

      1. Set permissions

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

cd rt-5.0.2
sudo make fixperms
      1. Verify the installation

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

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

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

    1. Set up RT's web server
      1. 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.

  • `alias` (required to map URLs to RT)
  • `fcgid` (required for Apache to talk to RT)
  • `mpm_prefork` (Apache requires you to select an MPM. RT is designed to work with the prefork module.)
  • `ssl` (required to serve HTTPS; optional otherwise)

Enable them following these instructions:

Debian/Ubuntu Red Hat/Fedora/CentOS
sudo a2dismod mpm_event
sudo a2enmod fcgid
sudo a2enmod mpm_prefork
sudo a2enmod ssl
echo LoadModule mpm_prefork_module modules/mod_mpm_prefork.so | sudo tee /etc/httpd/conf.modules.d/00-mpm.conf
      1. Configure an Apache VirtualHost

Create a file at the following location. You can change the `RT` part of the filename if you like, but the file must exist in this directory and have a `.conf` suffix.

Debian/Ubuntu Red Hat/Fedora/CentOS
`/etc/apache2/sites-available/RT.conf`

Then after you create the file, run: `sudo a2ensite RT`

`/etc/httpd/conf.d/RT.conf`

Use an editor to save all the text below to the new `RT.conf` and then fill in settings for your site everywhere the text `EDIT WITH` appears.

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

After you've edited the file, load the configuration with:

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

If this command reports an error, double-check the configuration file for typos, especially in option names, file paths, and the

pairs. Edit again and reload the configuration until it succeeds without output.

      1. Verify the web interface

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

If you run into trouble, the first place to look for more information is by reading Apache's error log:

Debian/Ubuntu Red Hat/Fedora/CentOS
sudo less /var/log/apache2/error.log
sudo less /var/log/httpd/error.log
    1. 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.

      1. 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 `sendmail` command. There are [configuration options to send mail through different commands](https://docs.bestpractical.com/rt/latest/RT_Config.html#Outgoing-mail) if you need.

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

Other software is available that provides a slimmer version of the `sendmail` command that connects to an external mail server for you, like 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.)

      1. Receiving email

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

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

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

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

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

This is much less common, but it might help to know that `rt-mailgate` doesn't have to run on the same system as RT itself. It just needs to be able to connect to RT's web interface. If you don't have any other options, you can install the RT software on a different system that receives email, and configure *that* system to run `rt-mailgate` and pass it on to the RT server. To do that, just repeat the installation instructions above, skipping the steps about installing the database and web server.

    1. Set up RT's background jobs

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

# Update the fulltext index with new ticket data
*/3	*	*	*	*	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

You can run all these jobs as the same user that runs your web server, rather than root. Run:

Debian/Ubuntu Red Hat/Fedora/CentOS
sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt
sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt
    1. 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.