RT 5.0.7 Documentation
Web deployment
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/rt5/sbin/rt-server --port 8080You can also run rt-server with any other PSGI server, for example, to use Starman, a high performance preforking server:
/opt/rt5/sbin/rt-server --server Starman --port 8080To listen on IPv6 too, you can install IO::Socket::INET6 and use Starman exactly like the above command.
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.
mod_fcgid
Apache can run with several different Multi-Processing Modules (MPMs). To use mod_fcgid, you need to run it with the prefork MPM. Most Linux distributions today use the event MPM by default, so it is important to make sure Apache is configured to use prefork on your RT server. If you do not use prefork MPM, RT will start okay but fail under production load, either because the web server crashes or performance severely degrades.
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 1073741824to 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/rt5/var/log/apache2.error
# TransferLog /opt/rt5/var/log/apache2.access
# LogLevel debug
AddDefaultCharset UTF-8
ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/
DocumentRoot "/opt/rt5/share/html"
<Location />
Require all granted
Options +ExecCGI
AddHandler fcgid-script fcgi
</Location>
</VirtualHost>mod_proxy_fcgi
This Apache module supports proxying requests via the FastCGI protocol. In addition to running Apache, you also need to start RT FCGI processes separately with a command like this:
/opt/rt5/sbin/rt-server.fcgi --listen /opt/rt5/var/rt.sock --nproc 10In this configuration, RT runs with Plack::Handler::FCGI and supports any arguments documented there.
Below is the corresponding Apache configuration:
<VirtualHost rt.example.com>
AddDefaultCharset UTF-8
ProxyPass / unix:/opt/rt5/var/rt.sock|fcgi://localhost/
ProxyFCGIBackendType GENERIC
ProxyFCGISetEnvIf "true" SCRIPT_NAME ""
</VirtualHost>Note that the SCRIPT_NAME directive is needed to avoid issues with URIs not being properly encoded, causing errors with URIs that have spaces.
In our testing we have found that this method shares more memory between RT FCGI processes, so it can allow you to run more RT processes with less memory. This comes at the cost of some extra management of the FCGI processes, which mod_fcgid handles for you.
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/rt5/var/log/apache2.error
# TransferLog /opt/rt5/var/log/apache2.access
# LogLevel debug
AddDefaultCharset UTF-8
DocumentRoot "/opt/rt5/share/html"
<Location />
Require all granted
SetHandler modperl
PerlResponseHandler Plack::Handler::Apache2
PerlSetVar psgi_app /opt/rt5/sbin/rt-server
</Location>
<Perl>
use Plack::Handler::Apache2;
Plack::Handler::Apache2->preload("/opt/rt5/sbin/rt-server");
</Perl>
</VirtualHost>Token Authentication
If you plan to set up token-based access, possibly to use RT::REST2, add the following directive to your RT Apache configuration to allow RT to access the Authorization header.
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1More information is available in RT::Authen::Token.
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/rt5/sbin/rt-server.fcgiWith the nginx configuration:
server {
listen 80;
server_name rt.example.com;
access_log /var/log/nginx/access.log;
location / {
client_max_body_size 100M;
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;
}
}The default nginx value for client_max_body_size is 1M, which is too small for most RT systems that accept attachments. The 100M value above is a suggestion. Adjust this to accept the largest attachments you expect to allow via email and the web UI.
lighttpd
server.modules += ( "mod_fastcgi" )
$HTTP["host"] =~ "^rt.example.com" {
fastcgi.server = (
"/" => (
"rt" => (
"socket" => "/opt/rt5/var/socket",
"bin-path" => "/opt/rt5/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/rt5/share/html/, otherwise RT's source will be served from /.
For example: if you're using the sample mod_fcgid config above, you might change the relevant directives to:
ScriptAlias /rt /opt/rt5/sbin/rt-server.fcgi/
# Set DocumentRoot as appropriate for the other content you want to serve
DocumentRoot /var/www
<Location /rt>
...
</Location>If you are using mod_proxy_fcgi, change these:
ProxyPass /rt/ unix:/opt/rt5/var/rt.sock|fcgi://localhost/
<Location /rt>
ProxyFCGISetEnvIf "true" SCRIPT_NAME "/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