]>
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 | |
26 | remove your C<var/mason> 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 | ||
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 | ||
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 | location /NoAuth/images { | |
187 | root /opt/rt4/share/html; | |
188 | } | |
189 | } | |
190 | ||
191 | ||
192 | =head2 lighttpd | |
193 | ||
194 | server.modules += ( "mod_fastcgi" ) | |
195 | $HTTP["host"] =~ "^rt.example.com" { | |
196 | alias.url = ( | |
197 | "/NoAuth/images/" => "/opt/rt4/share/html/NoAuth/images/", | |
198 | ) | |
199 | $HTTP["url"] !~ "^/NoAuth/images/" { | |
200 | fastcgi.server = ( | |
201 | "/" => ( | |
202 | "rt" => ( | |
203 | "port" => "9000", | |
204 | "bin-path" => "/opt/rt4/sbin/rt-server.fcgi", | |
205 | "check-local" => "disable", | |
206 | "fix-root-scriptname" => "enable", | |
207 | ) | |
208 | ) | |
209 | ) | |
210 | } | |
211 | } | |
212 | ||
213 | ||
214 | =head1 Running RT at /rt rather than / | |
215 | ||
216 | First you need to tell RT where it's located by setting C<$WebPath> in your | |
217 | F<RT_SiteConfig.pm>: | |
218 | ||
219 | # Important: don't include a trailing slash here. Read `perldoc | |
220 | # etc/RT_Config.pm` for more information. | |
221 | Set($WebPath, "/rt"); | |
222 | ||
223 | Then you need to update your Apache configuration to match. Prefix any RT | |
224 | related C<Alias>, C<ScriptAlias> and C<Location> directives with C</rt>. You | |
225 | should also make sure C<DocumentRoot> is B<not> set to | |
226 | C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>. | |
227 | ||
228 | For example: if you're using the sample FastCGI config above, you might change | |
229 | the relevant directives to: | |
230 | ||
231 | Alias /rt/NoAuth/images/ /opt/rt4/share/html/NoAuth/images/ | |
232 | ScriptAlias /rt /opt/rt4/sbin/rt-server.fcgi/ | |
233 | ||
234 | # Set DocumentRoot as appropriate for the other content you want to serve | |
235 | DocumentRoot /var/www | |
236 | ||
237 | <Location /rt> | |
238 | ... | |
239 | </Location> | |
240 | ||
241 | If you're using the sample mod_perl configuration, you only need to change the | |
242 | C<Location> directive. | |
243 | ||
244 | If you're not using Apache, please see L<Plack::Handler::FCGI> or the web | |
245 | server's own documentation for configuration examples. | |
246 |