355f6cea378b45f7a7271c0974d73c2d8f0e291e
[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 B<NOTICE>: After you run the standalone server as root, you will need to
26 remove your C<var/mason_data> directory, or the non-standalone servers
27 (Apache, etc), which run as a non-privileged user, will not be able to
28 write to it and will not work.
29
30
31 =head2 Apache
32
33 B<WARNING>: Both C<mod_speling> and C<mod_cache> are known to break RT.
34 C<mod_speling> will cause RT's CSS and JS to not be loaded, making RT
35 appear unstyled. C<mod_cache> will cache cookies, making users be
36 spontaneously 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
70 B<WARNING>: Before mod_fcgid 2.3.6, the maximum request size was 1GB.
71 Starting in 2.3.6, this is now 128Kb.  This is unlikely to be large
72 enough for any RT install that handles attachments.  You can read more
73 about FcgidMaxRequestLen at
74 L<http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html#fcgidmaxrequestlen>
75
76 Most distributions will have a mod_fcgid.conf or similar file with
77 mod_fcgid configurations and you should add:
78
79     FcgidMaxRequestLen 1073741824
80
81 to return to the old default.
82
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
107 B<WARNING: mod_perl 1.99_xx is not supported.>
108
109 B<WARNING>: Due to thread-safety limitations, all timestamps will be
110 presented in the webserver's default time zone when using the C<worker>
111 and C<event> MPMs; the C<$Timezone> setting and the user's timezone
112 preference are ignored.  We suggest the C<prefork> MPM or FastCGI
113 deployment if your privileged users are in a different timezone than the
114 one the server is configured for.
115
116 B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
117 this is incorrect for RT 4, and will lead to difficulties sending
118 outgoing mail from RT.  Ensure that you use C<SetHandler modperl>.
119
120     <VirtualHost rt.example.com>
121         ### Optional apache logs for RT
122         # ErrorLog /opt/rt4/var/log/apache2.error
123         # TransferLog /opt/rt4/var/log/apache2.access
124         # LogLevel debug
125
126         AddDefaultCharset UTF-8
127
128         DocumentRoot "/opt/rt4/share/html"
129         <Location />
130             Order allow,deny
131             Allow from all
132
133             SetHandler modperl
134             PerlResponseHandler Plack::Handler::Apache2
135             PerlSetVar psgi_app /opt/rt4/sbin/rt-server
136         </Location>
137         <Perl>
138             use Plack::Handler::Apache2;
139             Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server");
140         </Perl>
141     </VirtualHost>
142
143 =head3 mod_perl 1.xx
144
145 B<WARNING: mod_perl 1.99_xx is not supported.>
146
147 To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for
148 configuration examples.
149
150
151 =head2 nginx
152
153 C<nginx> requires that you start RT's fastcgi process externally, for
154 example using C<spawn-fcgi>:
155
156     spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \
157         -- /opt/rt4/sbin/rt-server.fcgi
158
159 With the nginx configuration:
160
161     server {
162         listen 80;
163         server_name rt.example.com;
164         access_log  /var/log/nginx/access.log;
165
166         location / {
167             fastcgi_param  QUERY_STRING       $query_string;
168             fastcgi_param  REQUEST_METHOD     $request_method;
169             fastcgi_param  CONTENT_TYPE       $content_type;
170             fastcgi_param  CONTENT_LENGTH     $content_length;
171
172             fastcgi_param  SCRIPT_NAME        "";
173             fastcgi_param  PATH_INFO          $uri;
174             fastcgi_param  REQUEST_URI        $request_uri;
175             fastcgi_param  DOCUMENT_URI       $document_uri;
176             fastcgi_param  DOCUMENT_ROOT      $document_root;
177             fastcgi_param  SERVER_PROTOCOL    $server_protocol;
178
179             fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
180             fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;
181
182             fastcgi_param  REMOTE_ADDR        $remote_addr;
183             fastcgi_param  REMOTE_PORT        $remote_port;
184             fastcgi_param  SERVER_ADDR        $server_addr;
185             fastcgi_param  SERVER_PORT        $server_port;
186             fastcgi_param  SERVER_NAME        $server_name;
187             fastcgi_pass 127.0.0.1:9000;
188         }
189
190         location /NoAuth/images {
191             root /opt/rt4/share/html;
192         }
193     }
194
195
196 =head2 lighttpd
197
198     server.modules += ( "mod_fastcgi" )
199     $HTTP["host"] =~ "^rt.example.com" {
200         alias.url = (
201             "/NoAuth/images/" => "/opt/rt4/share/html/NoAuth/images/",
202         )
203         $HTTP["url"] !~ "^/NoAuth/images/" {
204             fastcgi.server = (
205                 "/" => (
206                     "rt" => (
207                         "port"        => "9000",
208                         "bin-path"    => "/opt/rt4/sbin/rt-server.fcgi",
209                         "check-local" => "disable",
210                         "fix-root-scriptname" => "enable",
211                     )
212                 )
213             )
214         }
215     }
216
217
218 =head1 Running RT at /rt rather than /
219
220 First you need to tell RT where it's located by setting C<$WebPath> in your
221 F<RT_SiteConfig.pm>:
222
223     # Important: don't include a trailing slash here.  Read `perldoc
224     # etc/RT_Config.pm` for more information.
225     Set($WebPath, "/rt");
226
227 Then you need to update your Apache configuration to match.  Prefix any RT
228 related C<Alias>, C<ScriptAlias> and C<Location> directives with C</rt>.  You
229 should also make sure C<DocumentRoot> is B<not> set to
230 C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>.
231
232 For example: if you're using the sample FastCGI config above, you might change
233 the relevant directives to:
234
235     Alias /rt/NoAuth/images/ /opt/rt4/share/html/NoAuth/images/
236     ScriptAlias /rt /opt/rt4/sbin/rt-server.fcgi/
237
238     # Set DocumentRoot as appropriate for the other content you want to serve
239     DocumentRoot /var/www
240
241     <Location /rt>
242         ...
243     </Location>
244
245 If you're using the sample mod_perl configuration, you only need to change the
246 C<Location> directive.
247
248 If you're not using Apache, please see L<Plack::Handler::FCGI> or the web
249 server's own documentation for configuration examples.
250