- Setting up the web interface
  - Standalone
  - Apache
    - prefork MPM
    - mod_fastcgi
    - mod_fcgid
    - mod_perl 2.xx
    - mod_perl 1.xx
    - Restricting the REST 1.0 mail-gateway
  - nginx
  - lighttpd
- Running RT at /rt rather than /

# Setting up the web interface

As of RT 3.9, RT's web interface speaks PSGI (http://plackperl.org) which lets you use RT with any PSGI-supported web server (which includes Apache, nginx, lighttpd, etc).

## Standalone

The standalone RT web server is backed by a pure-Perl server engine (HTTP::Server::PSGI). This standalone server is appropriate for development and testing, but is not appropriate for production use.

You should not run this server against port 80 (which is the default port) because that requires root-level privileges and may conflict with any existing listeners. So choose a high port (for example 8080) and start the standalone server with:

        /opt/rt4/sbin/rt-server --port 8080

You can also run `rt-server` with any other PSGI server, for example, to use Starman, a high performance preforking server:

        /opt/rt4/sbin/rt-server --server Starman --port 8080

## Apache

WARNING: Both `mod_speling` and `mod_cache` are known to break RT. `mod_speling` will cause RT's CSS and JS to not be loaded, making RT appear unstyled. `mod_cache` will cache cookies, making users be spontaneously logged in as other users in the system.

See also "Apache configuration" in authentication, in case you intend to use Apache to provide authentication.

### prefork MPM

Apache can run with several different Multi-Processing Modules (MPMs). RT is designed to run only with the prefork MPM. RT will run with the event MPM, but it will run very poorly and you are likely to see issues like intermittent errors when loading pages, slowness, and possible excessive memory usage.

In the past, Apache defaulted to the prefork MPM, but the packaged Apache on many newer Linux systems defaults to event, so it is important to make sure Apache is configured to use prefork on your RT server.

### mod_fastcgi

        # Tell FastCGI to put its temporary files somewhere sane; this may
        # be necessary if your distribution doesn't already set it
        #FastCgiIpcDir /tmp

        FastCgiServer /opt/rt4/sbin/rt-server.fcgi -processes 5 -idle-timeout 300

        <VirtualHost rt.example.com>
            ### Optional apache logs for RT
            # Ensure that your log rotation scripts know about these files
            # ErrorLog /opt/rt4/var/log/apache2.error
            # TransferLog /opt/rt4/var/log/apache2.access
            # LogLevel debug

            AddDefaultCharset UTF-8

            ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/

            DocumentRoot "/opt/rt4/share/html"
            <Location />
                <IfVersion >= 2.4> # For Apache 2.4
                    Require all granted
                </IfVersion>
                <IfVersion < 2.4>  # For Apache 2.2
                    Order allow,deny
                    Allow from all
                </IfVersion>

                Options +ExecCGI
                AddHandler fastcgi-script fcgi
            </Location>
        </VirtualHost>

### mod_fcgid

WARNING: Before mod_fcgid 2.3.6, the maximum request size was 1GB. Starting in 2.3.6, this is now 128Kb. This is unlikely to be large enough for any RT install that handles attachments. You can read more about FcgidMaxRequestLen at http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html#fcgidmaxrequestlen

Most distributions will have a mod_fcgid.conf or similar file with mod_fcgid configurations and you should add:

        FcgidMaxRequestLen 1073741824

to return to the old default.

        <VirtualHost rt.example.com>
            ### Optional apache logs for RT
            # Ensure that your log rotation scripts know about these files
            # ErrorLog /opt/rt4/var/log/apache2.error
            # TransferLog /opt/rt4/var/log/apache2.access
            # LogLevel debug

            AddDefaultCharset UTF-8

            ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/

            DocumentRoot "/opt/rt4/share/html"
            <Location />
                <IfVersion >= 2.4> # For Apache 2.4
                    Require all granted
                </IfVersion>
                <IfVersion < 2.4>  # For Apache 2.2
                    Order allow,deny
                    Allow from all
                </IfVersion>

                Options +ExecCGI
                AddHandler fcgid-script fcgi
            </Location>
        </VirtualHost>

### mod_perl 2.xx

WARNING: mod_perl 1.99_xx is not supported.

WARNING: Due to thread-safety limitations, all timestamps will be presented in the webserver's default time zone when using the `worker` and `event` MPMs; the `$Timezone` setting and the user's timezone preference are ignored. We suggest the `prefork` MPM or FastCGI deployment if your privileged users are in a different timezone than the one the server is configured for.

NOTE: RT 3.8 and below suggested use of `SetHandler perl-script`; this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse to start, to prevent difficulties sending mail from RT. Change to `SetHandler modperl`, as the example below uses.

        <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 />
                <IfVersion >= 2.4> # For Apache 2.4
                    Require all granted
                </IfVersion>
                <IfVersion < 2.4>  # For Apache 2.2
                    Order allow,deny
                    Allow from all
                </IfVersion>

                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>

### mod_perl 1.xx

WARNING: mod_perl 1.99_xx is not supported.

To run RT using mod_perl 1.xx please see Plack::Handler::Apache1 for configuration examples.

### Restricting the REST 1.0 mail-gateway

RT processes email via a REST 1.0 endpoint. If you accept email on the same server as your running RT, you can restrict this endpoint to localhost only with a configuration like the following:

        # Accept requests only from localhost
        <Location /REST/1.0/NoAuth/mail-gateway>
            Require local
        </Location>

If you run `bin/rt-mailgate` on a separate server, you can update the above to allow additional IP addresses.

        <Location /REST/1.0/NoAuth/mail-gateway>
            Require ip 127.0.0.1 ::1 192.0.2.0  # Add your actual IPs
        </Location>

See the Apache documentation for additional configuration options.

After adding this configuration, test receiving email and confirm your `bin/rt-mailgate` utility and `/etc/aliases` configurations can successfully submit email to RT.

## nginx

`nginx` requires that you start RT's fastcgi process externally, for example using `spawn-fcgi`:

        spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \
            -- /opt/rt4/sbin/rt-server.fcgi

With the nginx configuration:

        server {
            listen 80;
            server_name rt.example.com;
            access_log  /var/log/nginx/access.log;

            location / {
                fastcgi_param  QUERY_STRING       $query_string;
                fastcgi_param  REQUEST_METHOD     $request_method;
                fastcgi_param  CONTENT_TYPE       $content_type;
                fastcgi_param  CONTENT_LENGTH     $content_length;

                fastcgi_param  SCRIPT_NAME        "";
                fastcgi_param  PATH_INFO          $uri;
                fastcgi_param  REQUEST_URI        $request_uri;
                fastcgi_param  DOCUMENT_URI       $document_uri;
                fastcgi_param  DOCUMENT_ROOT      $document_root;
                fastcgi_param  SERVER_PROTOCOL    $server_protocol;

                fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
                fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;

                fastcgi_param  REMOTE_ADDR        $remote_addr;
                fastcgi_param  REMOTE_PORT        $remote_port;
                fastcgi_param  SERVER_ADDR        $server_addr;
                fastcgi_param  SERVER_PORT        $server_port;
                fastcgi_param  SERVER_NAME        $server_name;
                fastcgi_pass 127.0.0.1:9000;
            }
        }

## lighttpd

        server.modules += ( "mod_fastcgi" )
        $HTTP["host"] =~ "^rt.example.com" {
            fastcgi.server = (
                "/" => (
                    "rt" => (
                        "socket"      => "/opt/rt4/var/socket",
                        "bin-path"    => "/opt/rt4/sbin/rt-server.fcgi",
                        "check-local" => "disable",
                        "fix-root-scriptname" => "enable",
                    )
                )
            )
        }

# Running RT at /rt rather than /

First you need to tell RT where it's located by setting `$WebPath` in your RT_SiteConfig.pm:

        # Important: don't include a trailing slash here.  Read `perldoc
        # etc/RT_Config.pm` for more information.
        Set($WebPath, "/rt");

Then you need to update your Apache configuration to match. Prefix any RT related `ScriptAlias` and `Location` directives with `/rt`. You should also make sure `DocumentRoot` is not set to `/opt/rt4/share/html/`, otherwise RT's source will be served from `/`.

For example: if you're using the sample FastCGI config above, you might change the relevant directives to:

        ScriptAlias /rt /opt/rt4/sbin/rt-server.fcgi/

        # Set DocumentRoot as appropriate for the other content you want to serve
        DocumentRoot /var/www

        <Location /rt>
            ...
        </Location>

If you're using the sample mod_perl configuration, you only need to change the `Location` directive.

If you're not using Apache, please see Plack::Handler::FCGI or the web server's own documentation for configuration examples.

← Back to index