Revision as of 09:45, 16 September 2011

Prev: ManualInstallation --- Up: UserManual --- Next: ManualEmailConfig

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 .tar.gz packages.

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.

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

The PerformanceTuning page has some info about the FastCGI vs. mod_perl. Read the Myths section.

Other options

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.

Checking dependencies

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>

Starting from RT 3.8 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.

SiteConfig

RT config has several options to define web server URLs layout WebBaseURL, WebPath and WebURL. The first two are the most important things you must configure:

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 /rt, /helpdesk or 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 /helpdesk.

That's all: once you've chosen layout and configured RT's config you can configure apache server.

Configuring Apache

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.

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

This line will take all requests of form "http://example.com/foo/" into "http://example.com/foo/index.html"

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:

DocumentRoot /opt/rt3/share/html

and add in its place:

Alias /rt "/opt/rt3/share/html"

Lastly, change the Location path from:

<Location />

to

<Location /rt>

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>

You will also need to modify the $WebPath variable in etc/RT_SiteConfig.pm in your RT installation directory. For the above example you would use:

$WebPath = "/rt";

Remember that $WebPath requires a leading / but no trailing /. $WebPath, your Apache alias, and your Apache Location should all contain the same string.

Testing

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:

apachectl stop

Try to use a browser to go to your RT server's website. You shouldn't be able to do it. Restart Apache:

./httpd start

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.

Troubleshooting

Note: Read the entry in the FAQ about MaxRequestsPerChild.

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

At this point you can either delete "PerlModule Apache::DBI" from apache config, or figure out how to install it -- SuSE, for example, provides it as a package to match their Apache2 package.

This feature is *optional*. Read ApacheConfig for more info about "mod_perl and caching connections to the DB".