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