Putting 4.2.0 on top of 4.0.17
[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         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
69 B<WARNING>: Before mod_fcgid 2.3.6, the maximum request size was 1GB.
70 Starting in 2.3.6, this is now 128Kb.  This is unlikely to be large
71 enough for any RT install that handles attachments.  You can read more
72 about FcgidMaxRequestLen at
73 L<http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html#fcgidmaxrequestlen>
74
75 Most distributions will have a mod_fcgid.conf or similar file with
76 mod_fcgid configurations and you should add:
77
78     FcgidMaxRequestLen 1073741824
79
80 to return to the old default.
81
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
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
105 B<WARNING: mod_perl 1.99_xx is not supported.>
106
107 B<WARNING>: Due to thread-safety limitations, all timestamps will be
108 presented in the webserver's default time zone when using the C<worker>
109 and C<event> MPMs; the C<$Timezone> setting and the user's timezone
110 preference are ignored.  We suggest the C<prefork> MPM or FastCGI
111 deployment if your privileged users are in a different timezone than the
112 one the server is configured for.
113
114 B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
115 this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse
116 to start, to prevent difficulties sending mail from RT.  Change to
117 C<SetHandler modperl>, as the example below uses.
118
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
144 B<WARNING: mod_perl 1.99_xx is not supported.>
145
146 To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for
147 configuration examples.
148
149
150 =head2 nginx
151
152 C<nginx> requires that you start RT's fastcgi process externally, for
153 example 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
158 With 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         }
188     }
189
190
191 =head2 lighttpd
192
193     server.modules += ( "mod_fastcgi" )
194     $HTTP["host"] =~ "^rt.example.com" {
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",
202                 )
203             )
204         )
205     }
206
207
208 =head1 Running RT at /rt rather than /
209
210 First you need to tell RT where it's located by setting C<$WebPath> in your
211 F<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
217 Then you need to update your Apache configuration to match.  Prefix any RT
218 related C<ScriptAlias> and C<Location> directives with C</rt>.  You
219 should also make sure C<DocumentRoot> is B<not> set to
220 C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>.
221
222 For example: if you're using the sample FastCGI config above, you might change
223 the relevant directives to:
224
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
234 If you're using the sample mod_perl configuration, you only need to change the
235 C<Location> directive.
236
237 If you're not using Apache, please see L<Plack::Handler::FCGI> or the web
238 server's own documentation for configuration examples.
239