Difference between revisions of "ManualInstallation"
(`make install` needs to know PERL5LIB)
(ensure httpd RT config loads after ssl.conf on Red Hat)
|Line 338:||Line 338:|
Then after you create the file, run: <code>sudo a2ensite RT</code>
Then after you create the file, run: <code>sudo a2ensite RT</code>
Revision as of 16:22, 13 January 2022
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.
sudo apt install autoconf build-essential cpanminus curl libexpat-dev libgd-dev libssl-dev libz-dev gnupg graphviz lynx openssl perl
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
(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:
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.
Enable password authentication in PostgreSQL
You need to consider this step whether you install the database locally, or use an existing one already running. RT supports connecting to PostgreSQL a few different ways, but authenticating with a username and password is simplest, and this guide is written based on that. Not all PostgreSQL installations allow this authentication method by default. You need to review your
pg_hba.conf file located at:
VERSION with the version of your PostgreSQL database. Add these two lines above any other lines that start with
host rt5 rt_user all md5 host rt5 rt_admin all md5
This configuration will let
rt_admin authorize themselves for the
rt5 database using an
md5 crypted password over a network connection (possibly using the localhost loopback network). You might be able to further restrict some of these fields for improved security, but doing so is outside the scope of this install guide. Refer to the pg_hba.conf documentation for more details.
Save your changes and reload the database:
sudo systemctl reload postgresql
Installing the PostgreSQL client libraries
These are required for RT to be able to talk to any PostgreSQL server.
sudo apt install libpq-dev
sudo dnf install postgresql-devel
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:
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.
Adjust MariaDB’s max_allowed_packet setting
You need to consider this step whether you install the database locally, or use an existing one already running. MariaDB’s
max_allowed_packet setting functionally limits the size of attachments in RT. The default is 16MiB, which is too small for most installations. You can ultimately choose any setting you’re comfortable with; 64MiB here should allow most requests without being too open.
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
Installing the MariaDB client libraries
These are required for RT to be able to talk to any MariaDB server.
sudo apt install libmariadb-dev libmariadb-dev-compat
sudo dnf install mariadb-devel
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.
sudo apt install apache2 libapache2-mod-fcgid
sudo dnf install httpd mod_fcgid mod_ssl
Get and unpack the RT source code
Download the latest source code using the link on the RT download page, extract it using
tar -xf, and
cd into the source code directory to run the rest of the commands in this section. For example:
curl -O https://download.bestpractical.com/pub/rt/release/rt-5.0.2.tar.gz tar -xf rt-5.0.2.tar.gz cd rt-5.0.2
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:
Pgfor PostgreSQL, or
--prefix=/opt/rt5sets 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
cded into the RT source directory, and run:
./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.
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:
make dirssets up RT's directory structure. We do this first to install dependencies under it.
make fixdepsactually installs those dependencies.
RT_FIX_DEPS_CMD='cpanm …'tells RT to use cpanminus to install dependencies (instead of the older, default
cpancommand), and to install them where RT will automatically load them.
make installinstalls all of RT’s files under
/opt/rt5(or the prefix directory you set in the previous step). It will only run if
PERL5LIBtells it where you installed those dependencies.
Make sure you have
cded into the RT source directory, and run:
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
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.
RT has many configuration options. You can put configuration options in the file
/opt/rt5/etc/RT_SiteConfig.pm, or in individual files under
/opt/rt5/etc/RT_SiteConfig.d/. Use an editor to save all the text below to
/opt/rt5/etc/RT_SiteConfig.pm (you can just overwrite the existing file, or add this to the bottom of what’s there) and then fill in settings for your site everywhere the text
EDIT WITH appears.
# Single-quote all values EXCEPT the special value `undef` # that turns off a setting. # rtname appears in ticket email subjects. It needs to be globally unique, # so use your organization's domain name. Set($rtname, 'EDIT WITH yourdomain.example.com'); # Organization is used in the database for ticket links, etc. It also needs to # be globally unique, so use your organization's domain name. Set($Organization, 'EDIT WITH yourdomain.example.com'); # WebDomain is domain name of the RT web server. RT uses it to construct links # and defend against CSRFs. Set($WebDomain, 'EDIT WITH rt.yourdomain.example.com'); # WebPort is the port where the RT web server runs. Edit the number below if # you're not using the standard HTTPS port. Set($WebPort, '443'); # 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;
RT_SiteConfig.pm is actually Perl code. RT runs the code directly to load the configuration. Any time you finish editing it, you can check that you didn’t make any syntax errors by running:
perl -c /opt/rt5/etc/RT_SiteConfig.pm
Set up RT’s database
RT includes a tool to help you set up its database. By default, it connects to the database as an administrator to create the database and user that you configured in the previous step.
(The instructions from
make install and RT’s README file tell you to run
make initialize-database. That just runs
rt-setup-database for you. Running the tool directly makes it easier to pass the options you need.)
--action=inittells 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
- 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 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/rt5first, and then it will find the necessary files automatically.
cd /opt/rt5 sudo sbin/rt-setup-database --action=init
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.
--noaskuses the default names for the index, which will be fine for a new install and simplifies the setup.
sudo /opt/rt5/sbin/rt-setup-fulltext-index --noask
Enter the password for your database administrator account when prompted. The end of the process will output some RT configuration that looks like this:
### EXAMPLE OUTPUT ONLY - Don't use this directly! Set( %FullTextSearch, Enable => 1, Indexed => 1, # Additional output from rt-setup-fulltext-index should be here. # The configuration varies by database type. );
Copy the output generated when you run
rt-setup-fulltext-index and save it to the file
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
Verify the installation
If everything has gone well, then you should be able to set a password for RT’s
root user. You’ll use this later to log in to the web interface and continue setting up your system. Run:
sudo /opt/rt5/sbin/rt-passwd root
Set the password when prompted. Record this; you’ll need it later.
Set up RT’s web server
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:
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
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
Then after you create the file, run:
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/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
After you’ve edited the file, load the configuration with:
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
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:
sudo less /var/log/apache2/error.log
sudo less /var/log/httpd/error.log
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.
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 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.)
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.
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:
sudo sed -i 's/\broot\b/www-data/' /etc/cron.d/rt
sudo sed -i 's/\broot\b/apache/' /etc/cron.d/rt
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.