Putting 4.2.0 on top of 4.0.17
[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
84fb5b46
MKG
55 ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/
56
57 DocumentRoot "/opt/rt4/share/html"
58 <Location />
59 Order allow,deny
60 Allow from all
61
62 Options +ExecCGI
63 AddHandler fastcgi-script fcgi
64 </Location>
65 </VirtualHost>
66
67=head3 mod_fcgid
68
b5747ff2
MKG
69B<WARNING>: Before mod_fcgid 2.3.6, the maximum request size was 1GB.
70Starting in 2.3.6, this is now 128Kb. This is unlikely to be large
71enough for any RT install that handles attachments. You can read more
72about FcgidMaxRequestLen at
73L<http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html#fcgidmaxrequestlen>
74
75Most distributions will have a mod_fcgid.conf or similar file with
76mod_fcgid configurations and you should add:
77
78 FcgidMaxRequestLen 1073741824
79
80to return to the old default.
81
84fb5b46
MKG
82 <VirtualHost rt.example.com>
83 ### Optional apache logs for RT
84 # Ensure that your log rotation scripts know about these files
85 # ErrorLog /opt/rt4/var/log/apache2.error
86 # TransferLog /opt/rt4/var/log/apache2.access
87 # LogLevel debug
88
89 AddDefaultCharset UTF-8
90
84fb5b46
MKG
91 ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/
92
93 DocumentRoot "/opt/rt4/share/html"
94 <Location />
95 Order allow,deny
96 Allow from all
97
98 Options +ExecCGI
99 AddHandler fcgid-script fcgi
100 </Location>
101 </VirtualHost>
102
103=head3 mod_perl 2.xx
104
105B<WARNING: mod_perl 1.99_xx is not supported.>
106
107B<WARNING>: Due to thread-safety limitations, all timestamps will be
108presented in the webserver's default time zone when using the C<worker>
109and C<event> MPMs; the C<$Timezone> setting and the user's timezone
110preference are ignored. We suggest the C<prefork> MPM or FastCGI
111deployment if your privileged users are in a different timezone than the
112one the server is configured for.
113
403d7b0b 114B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
c36a7e1d
MKG
115this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse
116to start, to prevent difficulties sending mail from RT. Change to
117C<SetHandler modperl>, as the example below uses.
403d7b0b 118
84fb5b46
MKG
119 <VirtualHost rt.example.com>
120 ### Optional apache logs for RT
121 # ErrorLog /opt/rt4/var/log/apache2.error
122 # TransferLog /opt/rt4/var/log/apache2.access
123 # LogLevel debug
124
125 AddDefaultCharset UTF-8
126
127 DocumentRoot "/opt/rt4/share/html"
128 <Location />
129 Order allow,deny
130 Allow from all
131
132 SetHandler modperl
133 PerlResponseHandler Plack::Handler::Apache2
134 PerlSetVar psgi_app /opt/rt4/sbin/rt-server
135 </Location>
136 <Perl>
137 use Plack::Handler::Apache2;
138 Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server");
139 </Perl>
140 </VirtualHost>
141
142=head3 mod_perl 1.xx
143
144B<WARNING: mod_perl 1.99_xx is not supported.>
145
146To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for
147configuration examples.
148
149
150=head2 nginx
151
152C<nginx> requires that you start RT's fastcgi process externally, for
153example using C<spawn-fcgi>:
154
155 spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \
156 -- /opt/rt4/sbin/rt-server.fcgi
157
158With the nginx configuration:
159
160 server {
161 listen 80;
162 server_name rt.example.com;
163 access_log /var/log/nginx/access.log;
164
165 location / {
166 fastcgi_param QUERY_STRING $query_string;
167 fastcgi_param REQUEST_METHOD $request_method;
168 fastcgi_param CONTENT_TYPE $content_type;
169 fastcgi_param CONTENT_LENGTH $content_length;
170
171 fastcgi_param SCRIPT_NAME "";
172 fastcgi_param PATH_INFO $uri;
173 fastcgi_param REQUEST_URI $request_uri;
174 fastcgi_param DOCUMENT_URI $document_uri;
175 fastcgi_param DOCUMENT_ROOT $document_root;
176 fastcgi_param SERVER_PROTOCOL $server_protocol;
177
178 fastcgi_param GATEWAY_INTERFACE CGI/1.1;
179 fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;
180
181 fastcgi_param REMOTE_ADDR $remote_addr;
182 fastcgi_param REMOTE_PORT $remote_port;
183 fastcgi_param SERVER_ADDR $server_addr;
184 fastcgi_param SERVER_PORT $server_port;
185 fastcgi_param SERVER_NAME $server_name;
186 fastcgi_pass 127.0.0.1:9000;
187 }
84fb5b46
MKG
188 }
189
190
191=head2 lighttpd
192
193 server.modules += ( "mod_fastcgi" )
194 $HTTP["host"] =~ "^rt.example.com" {
af59614d
MKG
195 fastcgi.server = (
196 "/" => (
197 "rt" => (
198 "port" => "9000",
199 "bin-path" => "/opt/rt4/sbin/rt-server.fcgi",
200 "check-local" => "disable",
201 "fix-root-scriptname" => "enable",
84fb5b46
MKG
202 )
203 )
af59614d 204 )
84fb5b46
MKG
205 }
206
207
208=head1 Running RT at /rt rather than /
209
210First you need to tell RT where it's located by setting C<$WebPath> in your
211F<RT_SiteConfig.pm>:
212
213 # Important: don't include a trailing slash here. Read `perldoc
214 # etc/RT_Config.pm` for more information.
215 Set($WebPath, "/rt");
216
217Then you need to update your Apache configuration to match. Prefix any RT
af59614d 218related C<ScriptAlias> and C<Location> directives with C</rt>. You
84fb5b46
MKG
219should also make sure C<DocumentRoot> is B<not> set to
220C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>.
221
222For example: if you're using the sample FastCGI config above, you might change
223the relevant directives to:
224
84fb5b46
MKG
225 ScriptAlias /rt /opt/rt4/sbin/rt-server.fcgi/
226
227 # Set DocumentRoot as appropriate for the other content you want to serve
228 DocumentRoot /var/www
229
230 <Location /rt>
231 ...
232 </Location>
233
234If you're using the sample mod_perl configuration, you only need to change the
235C<Location> directive.
236
237If you're not using Apache, please see L<Plack::Handler::FCGI> or the web
238server's own documentation for configuration examples.
239