Dev to 4.0.11
[usit-rt.git] / docs / web_deployment.pod
CommitLineData
84fb5b46
MKG
1=head1 Setting up the web interface
2
3As 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
5server (which includes Apache, nginx, lighttpd, etc).
6
7=head2 Standalone
8
9The standalone RT web server is backed by a pure-Perl server engine
10(L<HTTP::Server::PSGI>). This standalone server is appropriate for development
11and testing, but is not appropriate for production use.
12
13You should not run this server against port 80 (which is the default port)
14because that requires root-level privileges and may conflict with any existing
15listeners. So choose a high port (for example 8080) and start the standalone
16server with:
17
18 /opt/rt4/sbin/rt-server --port 8080
19
20You can also run C<rt-server> with any other PSGI server, for example,
21to use L<Starman>, a high performance preforking server:
22
23 /opt/rt4/sbin/rt-server --server Starman --port 8080
24
25B<NOTICE>: After you run the standalone server as root, you will need to
dab09ea8 26remove your C<var/mason_data> directory, or the non-standalone servers
84fb5b46
MKG
27(Apache, etc), which run as a non-privileged user, will not be able to
28write to it and will not work.
29
30
31=head2 Apache
32
33B<WARNING>: Both C<mod_speling> and C<mod_cache> are known to break RT.
34C<mod_speling> will cause RT's CSS and JS to not be loaded, making RT
35appear unstyled. C<mod_cache> will cache cookies, making users be
36spontaneously logged in as other users in the system.
37
38=head3 mod_fastcgi
39
40 # Tell FastCGI to put its temporary files somewhere sane; this may
41 # be necessary if your distribution doesn't already set it
42 #FastCgiIpcDir /tmp
43
44 FastCgiServer /opt/rt4/sbin/rt-server.fcgi -processes 5 -idle-timeout 300
45
46 <VirtualHost rt.example.com>
47 ### Optional apache logs for RT
48 # Ensure that your log rotation scripts know about these files
49 # ErrorLog /opt/rt4/var/log/apache2.error
50 # TransferLog /opt/rt4/var/log/apache2.access
51 # LogLevel debug
52
53 AddDefaultCharset UTF-8
54
55 Alias /NoAuth/images/ /opt/rt4/share/html/NoAuth/images/
56 ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/
57
58 DocumentRoot "/opt/rt4/share/html"
59 <Location />
60 Order allow,deny
61 Allow from all
62
63 Options +ExecCGI
64 AddHandler fastcgi-script fcgi
65 </Location>
66 </VirtualHost>
67
68=head3 mod_fcgid
69
b5747ff2
MKG
70B<WARNING>: Before mod_fcgid 2.3.6, the maximum request size was 1GB.
71Starting in 2.3.6, this is now 128Kb. This is unlikely to be large
72enough for any RT install that handles attachments. You can read more
73about FcgidMaxRequestLen at
74L<http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html#fcgidmaxrequestlen>
75
76Most distributions will have a mod_fcgid.conf or similar file with
77mod_fcgid configurations and you should add:
78
79 FcgidMaxRequestLen 1073741824
80
81to return to the old default.
82
84fb5b46
MKG
83 <VirtualHost rt.example.com>
84 ### Optional apache logs for RT
85 # Ensure that your log rotation scripts know about these files
86 # ErrorLog /opt/rt4/var/log/apache2.error
87 # TransferLog /opt/rt4/var/log/apache2.access
88 # LogLevel debug
89
90 AddDefaultCharset UTF-8
91
92 Alias /NoAuth/images/ /opt/rt4/share/html/NoAuth/images/
93 ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/
94
95 DocumentRoot "/opt/rt4/share/html"
96 <Location />
97 Order allow,deny
98 Allow from all
99
100 Options +ExecCGI
101 AddHandler fcgid-script fcgi
102 </Location>
103 </VirtualHost>
104
105=head3 mod_perl 2.xx
106
107B<WARNING: mod_perl 1.99_xx is not supported.>
108
109B<WARNING>: Due to thread-safety limitations, all timestamps will be
110presented in the webserver's default time zone when using the C<worker>
111and C<event> MPMs; the C<$Timezone> setting and the user's timezone
112preference are ignored. We suggest the C<prefork> MPM or FastCGI
113deployment if your privileged users are in a different timezone than the
114one the server is configured for.
115
403d7b0b 116B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
c36a7e1d
MKG
117this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse
118to start, to prevent difficulties sending mail from RT. Change to
119C<SetHandler modperl>, as the example below uses.
403d7b0b 120
84fb5b46
MKG
121 <VirtualHost rt.example.com>
122 ### Optional apache logs for RT
123 # ErrorLog /opt/rt4/var/log/apache2.error
124 # TransferLog /opt/rt4/var/log/apache2.access
125 # LogLevel debug
126
127 AddDefaultCharset UTF-8
128
129 DocumentRoot "/opt/rt4/share/html"
130 <Location />
131 Order allow,deny
132 Allow from all
133
134 SetHandler modperl
135 PerlResponseHandler Plack::Handler::Apache2
136 PerlSetVar psgi_app /opt/rt4/sbin/rt-server
137 </Location>
138 <Perl>
139 use Plack::Handler::Apache2;
140 Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server");
141 </Perl>
142 </VirtualHost>
143
144=head3 mod_perl 1.xx
145
146B<WARNING: mod_perl 1.99_xx is not supported.>
147
148To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for
149configuration examples.
150
151
152=head2 nginx
153
154C<nginx> requires that you start RT's fastcgi process externally, for
155example using C<spawn-fcgi>:
156
157 spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \
158 -- /opt/rt4/sbin/rt-server.fcgi
159
160With the nginx configuration:
161
162 server {
163 listen 80;
164 server_name rt.example.com;
165 access_log /var/log/nginx/access.log;
166
167 location / {
168 fastcgi_param QUERY_STRING $query_string;
169 fastcgi_param REQUEST_METHOD $request_method;
170 fastcgi_param CONTENT_TYPE $content_type;
171 fastcgi_param CONTENT_LENGTH $content_length;
172
173 fastcgi_param SCRIPT_NAME "";
174 fastcgi_param PATH_INFO $uri;
175 fastcgi_param REQUEST_URI $request_uri;
176 fastcgi_param DOCUMENT_URI $document_uri;
177 fastcgi_param DOCUMENT_ROOT $document_root;
178 fastcgi_param SERVER_PROTOCOL $server_protocol;
179
180 fastcgi_param GATEWAY_INTERFACE CGI/1.1;
181 fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;
182
183 fastcgi_param REMOTE_ADDR $remote_addr;
184 fastcgi_param REMOTE_PORT $remote_port;
185 fastcgi_param SERVER_ADDR $server_addr;
186 fastcgi_param SERVER_PORT $server_port;
187 fastcgi_param SERVER_NAME $server_name;
188 fastcgi_pass 127.0.0.1:9000;
189 }
190
191 location /NoAuth/images {
192 root /opt/rt4/share/html;
193 }
194 }
195
196
197=head2 lighttpd
198
199 server.modules += ( "mod_fastcgi" )
200 $HTTP["host"] =~ "^rt.example.com" {
201 alias.url = (
202 "/NoAuth/images/" => "/opt/rt4/share/html/NoAuth/images/",
203 )
204 $HTTP["url"] !~ "^/NoAuth/images/" {
205 fastcgi.server = (
206 "/" => (
207 "rt" => (
208 "port" => "9000",
209 "bin-path" => "/opt/rt4/sbin/rt-server.fcgi",
210 "check-local" => "disable",
211 "fix-root-scriptname" => "enable",
212 )
213 )
214 )
215 }
216 }
217
218
219=head1 Running RT at /rt rather than /
220
221First you need to tell RT where it's located by setting C<$WebPath> in your
222F<RT_SiteConfig.pm>:
223
224 # Important: don't include a trailing slash here. Read `perldoc
225 # etc/RT_Config.pm` for more information.
226 Set($WebPath, "/rt");
227
228Then you need to update your Apache configuration to match. Prefix any RT
229related C<Alias>, C<ScriptAlias> and C<Location> directives with C</rt>. You
230should also make sure C<DocumentRoot> is B<not> set to
231C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>.
232
233For example: if you're using the sample FastCGI config above, you might change
234the relevant directives to:
235
236 Alias /rt/NoAuth/images/ /opt/rt4/share/html/NoAuth/images/
237 ScriptAlias /rt /opt/rt4/sbin/rt-server.fcgi/
238
239 # Set DocumentRoot as appropriate for the other content you want to serve
240 DocumentRoot /var/www
241
242 <Location /rt>
243 ...
244 </Location>
245
246If you're using the sample mod_perl configuration, you only need to change the
247C<Location> directive.
248
249If you're not using Apache, please see L<Plack::Handler::FCGI> or the web
250server's own documentation for configuration examples.
251