]>
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 | ||
84fb5b46 MKG |
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 | ||
b5747ff2 MKG |
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 | ||
84fb5b46 MKG |
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 | ||
84fb5b46 MKG |
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 | ||
403d7b0b | 114 | B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>; |
c36a7e1d MKG |
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. | |
403d7b0b | 118 | |
84fb5b46 MKG |
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 | } | |
84fb5b46 MKG |
188 | } |
189 | ||
190 | ||
191 | =head2 lighttpd | |
192 | ||
193 | server.modules += ( "mod_fastcgi" ) | |
194 | $HTTP["host"] =~ "^rt.example.com" { | |
af59614d MKG |
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", | |
84fb5b46 MKG |
202 | ) |
203 | ) | |
af59614d | 204 | ) |
84fb5b46 MKG |
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 | |
af59614d | 218 | related C<ScriptAlias> and C<Location> directives with C</rt>. You |
84fb5b46 MKG |
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 | ||
84fb5b46 MKG |
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 |