Unofficial Installation Guide
This is an unofficial installation guide. It may be outdated or apply only to very specific configurations and versions. The official and maintained installation steps for RT are in the README and UPGRADING documents included in the official
|This page 'ManualApacheConfig' is tagged as OUTDATED|
|This page contains out of date and possibly misleading information or instructions such as installation methods or configuration examples that no longer apply. Please consider this warning when reading the page below.|
|If you have checked or updated this page and found the content to be suitable, please remove this notice by editing the page and remove the Outdated template tag.|
NOTE: The information on this page is outdated. It is superseded by the documentation in docs/web_deployment.pod in the base RT tarball.
Apache + mod_perl2 guide updated for RT4
SETTING UP THE WEB INTERFACE
Choosing a web handler
A note of caution: Do not use symbolic links in the Apache conf directory structures.
RT's web interface is written using HTML::Mason, which works with the mod_perl embedded perl interpreter within Apache httpd. Alternatively, support for the FastCGI interface is also provided as 'bin/mason_handler.fcgi'. Setting up either of these can be fairly intricate; don't get discouraged if it takes you some time to get this right -- though it's not nearly as difficult as it used to be.
FastCGI vs. mod_perl
Both work fine. Each have some strong and weak points.
You cannot run multiple instances of RT under one server with mod_perl, even in multiple vhosts; since mod_perl embeds a perl process in apache, but only one, whichever configuration is loaded last will clobber all other ones. If you need to run more than once instance of RT on the same server, you will need to run them with fastcgi.
If you have something already installed then use it. Otherwise here are a few notes to help choose:
- apache 1.x is for those who are already using it and don't want to upgrade
- use whatever version of apache is installed on your system
- have no experience with FastCGI or mod_perl then just throw a coin to choose between -- or pick whichever one is provided as a package by your distribution
- a few warnings about mod_perl:
- If your system has only mod_perl 1.9x (development version before mod_perl 2 release) and you don't know how to or don't want to build mod_perl from scratch then just ignore it and DON'T TRY TO USE RT with mod_perl 1.9x, jump to FastCGI (this is unlikely to be the case on new installs, as mod_perl 2 has been out for some number of years now).
- If you have apache 2.x then you need mod_perl 2.x as well. mod_perl 1.x just won't work with apache 2.x
- If you have apache 1.x then you need mod_perl 1.xx where xx is not 9x
Other options as well exist, like speedycgi, FastCGI+nginx, FastCGI+lighttpd... But Apache+FastCGI and Apache+mod_perl these are two major variants perl developers pay attention to as they are most common. If it's your first install then make your life easier and choose a common solution. Later you may find time to experiment with others.
Once you've made your choice then test dependencies again to make sure everything is there for web environment of choice:
- # without arguments to get list of options
- perl sbin/rt-test-dependencies
- perl sbin/rt-test-dependencies --with-<your choice>
You can choose web handler during ./configure step using its option. Check ./configure --help
Choosing web layout
Before you start your install, you have to decide which URL will be the base for your RT instance. Will it be http://rt.example.com/ or do you prefer http://www.example.com/rt/ ? RT can't get this info from apache config or preconfigure your server for any possible setup, so it's your task to decide and configure both ends.
If you decide to use rt.example.com, and you're sharing the webserver with other domains using VirtualHosts, then you'll have additional configuration to perform.
- WebBaseURL - it's the base URL for the server that serves RT web interface, it should contain scheme (http or https), server name and port (if it's not standard value 80), for example http://rt.example.com, https://rt.example.com and http://www.example.com are valid and sane values. Note that there is no trailing slash and it's root URL of the server.
- WebPath - it's URL path relative to the root of the server (WebBaseURL option) that has leading slash and no trailing slash, for example
/helpdeskor empty value.
We discussed these in the ManualInstallation section, previously, but here are some examples to recap:
- You want http://rt.example.com/ as RT main page then WebBaseURL should be http://rt.example.com and WebPath should be empty.
- You want http://www.example.com/helpdesk/ as RT main page then WebBaseURL should be http://www.example.com and WebPath should be
That's all: once you've chosen layout and configured RT's config you can configure apache server.
You've made several choices above and now you're ready to configure your server. These days (2008) apache is installed in a different way on different distributions. Usually configuration files are in /etc/apache* or /etc/httpd
You'll need to add a few lines to your httpd.conf telling it to use RT's web interface and how to handle it. Search below for a variant matching your choices. If you can not find it here then search on other pages and move here example or ask on MailingLists, but don't forget mention that you came from this page and it has no example for your case, so people can update it.
Note: RT will not load without a valid virtual host name
apache2 + mod_perl2 and RT4 on http://rt.example.com/
<VirtualHost rt.example.com> # Optional apache logs for RT # ErrorLog /opt/rt4/var/log/apache2.error # TransferLog /opt/rt4/var/log/apache2.access # LogLevel debug AddDefaultCharset UTF-8 DocumentRoot "/opt/rt4/share/html" <Location /> Order allow,deny Allow from all SetHandler modperl PerlResponseHandler Plack::Handler::Apache2 PerlSetVar psgi_app /opt/rt4/sbin/rt-server </Location> <Perl> use Plack::Handler::Apache2; Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server"); </Perl> </VirtualHost>
apache2 + mod_perl2 and RT on http://rt.example.com/
Note: This only works for RT3
# ip based virtual host Listen ip_of_the_rt.example.com:80 <VirtualHost ip_of_the_rt.example.com:80> ServerName rt.example.com ServerAdmin Email.Address@example.com DocumentRoot /opt/rt3/share/html AddDefaultCharset UTF-8 PerlRequire /opt/rt3/bin/webmux.pl <Directory /opt/rt3/share/html> Order allow,deny Allow from all SetHandler perl-script PerlResponseHandler RT::Mason </Directory> </VirtualHost>
apache2 + mod_perl2 and RT on http://www.example.com/rt/
Listen ip_of_the_www.example.com:80 <VirtualHost ip_of_the_www.example.com:80> ServerName www.example.com ServerAdmin Email.Address@example.com # config for your main content DocumentRoot /www/www.example.com <Directory /www/www.example.com> # here and in other places goes config # of your main host </Directory> # as RT is out of document root then we want alias # and should define directory access Alias /rt/ /opt/rt3/share/html/ <Directory /opt/rt3/share/html/> Order allow,deny Allow from all </Directory> PerlRequire /opt/rt3/bin/webmux.pl <Location /rt/> AddDefaultCharset UTF-8 SetHandler perl-script PerlHandler RT::Mason </Location> </VirtualHost>
Some historical notes people left, some make sense, some are wrong, for refactoring
NOTE: If you are running Apache 2, the recommended configuration directive is:
RedirectMatch permanent (.*)/$ http://example.com$1/index.html
in your VirtualHost section
NOTE: If "your.ip.address" above is the same as your webserver's IP and you're not planning to assign a unique IP address or alias (CNAME) for RT, you should realize that the above VirtualHost configuration works when RT is the only content provided at the root of the webserver. If your webserver has existing content or you plan to add content later, you'll probably want to place RT in a directory other than the root of the webserver. If you choose to use "http://fsck.com/rt/", you'll want to modify the VirtualHost configuration as follows:
Comment with '#' or remove the following line:
and add in its place:
Alias /rt "/opt/rt3/share/html"
Lastly, change the Location path from:
That gives a configuration similar to
Alias /rt "/opt/rt3/share/html" PerlModule Apache::DBI PerlRequire /opt/rt3/bin/webmux.pl <Directory /opt/rt3/share/html> AllowOverride All Options ExecCGI FollowSymLinks <IfModule mod_access.c> Order allow,deny Allow from all </IfModule> </Directory> <Location /rt> RewriteEngine On RedirectMatch permanent (.*)/$ $1/index.html AddDefaultCharset UTF-8 SetHandler perl-script PerlHandler RT::Mason </Location>
$WebPath = "/rt";
Next, stop Apache. This will vary by system but might look something like this:
cd /etc/init.d ./httpd stop
or, if your distro includes it:
Try to use a browser to go to your RT server's website. You shouldn't be able to do it. Restart Apache:
Now, you should be able to go to your RT URL and get the login screen.
Once this works, you may move on to setting up your email gateway.
client denied by server configuration
If you receive a "client denied by server configuration: /opt/rt3/share/html" in your Apache error.log or a "403 Forbidden" error then also add the following to your VirtualHost section:
<Directory "/opt/rt3/share/html"> Order allow,deny Allow from all </Directory>
(the above hint for 403/denied was found on http://wiki.bestpractical.com/view/FastCGIConfiguration)
Can't locate Apache/DBI.pm in ...
This feature is *optional*. Read ApacheConfig for more info about "mod_perl and caching connections to the DB".