]>
Commit | Line | Data |
---|---|---|
84fb5b46 MKG |
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 | |
dab09ea8 | 26 | remove 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 |
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 | ||
b5747ff2 MKG |
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 | ||
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 | ||
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 | ||
403d7b0b | 116 | B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>; |
c36a7e1d MKG |
117 | this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse |
118 | to start, to prevent difficulties sending mail from RT. Change to | |
119 | C<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 | ||
146 | B<WARNING: mod_perl 1.99_xx is not supported.> | |
147 | ||
148 | To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for | |
149 | configuration examples. | |
150 | ||
151 | ||
152 | =head2 nginx | |
153 | ||
154 | C<nginx> requires that you start RT's fastcgi process externally, for | |
155 | example 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 | ||
160 | With 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 | ||
221 | First you need to tell RT where it's located by setting C<$WebPath> in your | |
222 | F<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 | ||
228 | Then you need to update your Apache configuration to match. Prefix any RT | |
229 | related C<Alias>, C<ScriptAlias> and C<Location> directives with C</rt>. You | |
230 | should also make sure C<DocumentRoot> is B<not> set to | |
231 | C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>. | |
232 | ||
233 | For example: if you're using the sample FastCGI config above, you might change | |
234 | the 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 | ||
246 | If you're using the sample mod_perl configuration, you only need to change the | |
247 | C<Location> directive. | |
248 | ||
249 | If you're not using Apache, please see L<Plack::Handler::FCGI> or the web | |
250 | server's own documentation for configuration examples. | |
251 |