1 =head1 Setting up the web interface
3 As of RT 3.9, RT's web interface speaks PSGI
4 (L<http://plackperl.org>) which lets you use RT with any PSGI-supported web
5 server (which includes Apache, nginx, lighttpd, etc).
9 The standalone RT web server is backed by a pure-Perl server engine
10 (L<HTTP::Server::PSGI>). This standalone server is appropriate for development
11 and testing, but is not appropriate for production use.
13 You should not run this server against port 80 (which is the default port)
14 because that requires root-level privileges and may conflict with any existing
15 listeners. So choose a high port (for example 8080) and start the standalone
18 /opt/rt4/sbin/rt-server --port 8080
20 You can also run C<rt-server> with any other PSGI server, for example,
21 to use L<Starman>, a high performance preforking server:
23 /opt/rt4/sbin/rt-server --server Starman --port 8080
27 B<WARNING>: Both C<mod_speling> and C<mod_cache> are known to break RT.
28 C<mod_speling> will cause RT's CSS and JS to not be loaded, making RT
29 appear unstyled. C<mod_cache> will cache cookies, making users be
30 spontaneously logged in as other users in the system.
32 See also L<authentication/Apache configuration>, in case you intend to
33 use Apache to provide authentication.
37 # Tell FastCGI to put its temporary files somewhere sane; this may
38 # be necessary if your distribution doesn't already set it
41 FastCgiServer /opt/rt4/sbin/rt-server.fcgi -processes 5 -idle-timeout 300
43 <VirtualHost rt.example.com>
44 ### Optional apache logs for RT
45 # Ensure that your log rotation scripts know about these files
46 # ErrorLog /opt/rt4/var/log/apache2.error
47 # TransferLog /opt/rt4/var/log/apache2.access
50 AddDefaultCharset UTF-8
52 ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/
54 DocumentRoot "/opt/rt4/share/html"
56 <IfVersion >= 2.4> # For Apache 2.4
59 <IfVersion < 2.4> # For Apache 2.2
65 AddHandler fastcgi-script fcgi
71 B<WARNING>: Before mod_fcgid 2.3.6, the maximum request size was 1GB.
72 Starting in 2.3.6, this is now 128Kb. This is unlikely to be large
73 enough for any RT install that handles attachments. You can read more
74 about FcgidMaxRequestLen at
75 L<http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html#fcgidmaxrequestlen>
77 Most distributions will have a mod_fcgid.conf or similar file with
78 mod_fcgid configurations and you should add:
80 FcgidMaxRequestLen 1073741824
82 to return to the old default.
84 <VirtualHost rt.example.com>
85 ### Optional apache logs for RT
86 # Ensure that your log rotation scripts know about these files
87 # ErrorLog /opt/rt4/var/log/apache2.error
88 # TransferLog /opt/rt4/var/log/apache2.access
91 AddDefaultCharset UTF-8
93 ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/
95 DocumentRoot "/opt/rt4/share/html"
97 <IfVersion >= 2.4> # For Apache 2.4
100 <IfVersion < 2.4> # For Apache 2.2
106 AddHandler fcgid-script fcgi
112 B<WARNING: mod_perl 1.99_xx is not supported.>
114 B<WARNING>: Due to thread-safety limitations, all timestamps will be
115 presented in the webserver's default time zone when using the C<worker>
116 and C<event> MPMs; the C<$Timezone> setting and the user's timezone
117 preference are ignored. We suggest the C<prefork> MPM or FastCGI
118 deployment if your privileged users are in a different timezone than the
119 one the server is configured for.
121 B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
122 this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse
123 to start, to prevent difficulties sending mail from RT. Change to
124 C<SetHandler modperl>, as the example below uses.
126 <VirtualHost rt.example.com>
127 ### Optional apache logs for RT
128 # ErrorLog /opt/rt4/var/log/apache2.error
129 # TransferLog /opt/rt4/var/log/apache2.access
132 AddDefaultCharset UTF-8
134 DocumentRoot "/opt/rt4/share/html"
136 <IfVersion >= 2.4> # For Apache 2.4
139 <IfVersion < 2.4> # For Apache 2.2
145 PerlResponseHandler Plack::Handler::Apache2
146 PerlSetVar psgi_app /opt/rt4/sbin/rt-server
149 use Plack::Handler::Apache2;
150 Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server");
156 B<WARNING: mod_perl 1.99_xx is not supported.>
158 To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for
159 configuration examples.
164 C<nginx> requires that you start RT's fastcgi process externally, for
165 example using C<spawn-fcgi>:
167 spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \
168 -- /opt/rt4/sbin/rt-server.fcgi
170 With the nginx configuration:
174 server_name rt.example.com;
175 access_log /var/log/nginx/access.log;
178 fastcgi_param QUERY_STRING $query_string;
179 fastcgi_param REQUEST_METHOD $request_method;
180 fastcgi_param CONTENT_TYPE $content_type;
181 fastcgi_param CONTENT_LENGTH $content_length;
183 fastcgi_param SCRIPT_NAME "";
184 fastcgi_param PATH_INFO $uri;
185 fastcgi_param REQUEST_URI $request_uri;
186 fastcgi_param DOCUMENT_URI $document_uri;
187 fastcgi_param DOCUMENT_ROOT $document_root;
188 fastcgi_param SERVER_PROTOCOL $server_protocol;
190 fastcgi_param GATEWAY_INTERFACE CGI/1.1;
191 fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;
193 fastcgi_param REMOTE_ADDR $remote_addr;
194 fastcgi_param REMOTE_PORT $remote_port;
195 fastcgi_param SERVER_ADDR $server_addr;
196 fastcgi_param SERVER_PORT $server_port;
197 fastcgi_param SERVER_NAME $server_name;
198 fastcgi_pass 127.0.0.1:9000;
205 server.modules += ( "mod_fastcgi" )
206 $HTTP["host"] =~ "^rt.example.com" {
210 "socket" => "/opt/rt4/var/socket",
211 "bin-path" => "/opt/rt4/sbin/rt-server.fcgi",
212 "check-local" => "disable",
213 "fix-root-scriptname" => "enable",
220 =head1 Running RT at /rt rather than /
222 First you need to tell RT where it's located by setting C<$WebPath> in your
225 # Important: don't include a trailing slash here. Read `perldoc
226 # etc/RT_Config.pm` for more information.
227 Set($WebPath, "/rt");
229 Then you need to update your Apache configuration to match. Prefix any RT
230 related C<ScriptAlias> and C<Location> directives with C</rt>. You
231 should also make sure C<DocumentRoot> is B<not> set to
232 C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>.
234 For example: if you're using the sample FastCGI config above, you might change
235 the relevant directives to:
237 ScriptAlias /rt /opt/rt4/sbin/rt-server.fcgi/
239 # Set DocumentRoot as appropriate for the other content you want to serve
240 DocumentRoot /var/www
246 If you're using the sample mod_perl configuration, you only need to change the
247 C<Location> directive.
249 If you're not using Apache, please see L<Plack::Handler::FCGI> or the web
250 server's own documentation for configuration examples.