diff options
Diffstat (limited to 'rt/docs/web_deployment.pod')
| -rw-r--r-- | rt/docs/web_deployment.pod | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/rt/docs/web_deployment.pod b/rt/docs/web_deployment.pod new file mode 100644 index 000000000..65065c5cd --- /dev/null +++ b/rt/docs/web_deployment.pod @@ -0,0 +1,233 @@ +=head1 Setting up the web interface + +As of RT 3.9, RT's web interface speaks PSGI +(L<http://plackperl.org>) which lets you use RT with any PSGI-supported web +server (which includes Apache, nginx, lighttpd, etc). + +=head2 Standalone + +The standalone RT web server is backed by a pure-Perl server engine +(L<HTTP::Server::PSGI>). This standalone server is appropriate for development +and testing, but is not appropriate for production use. + +You should not run this server against port 80 (which is the default port) +because that requires root-level privileges and may conflict with any existing +listeners. So choose a high port (for example 8080) and start the standalone +server with: + + /opt/rt4/sbin/rt-server --port 8080 + +You can also run C<rt-server> with any other PSGI server, for example, +to use L<Starman>, a high performance preforking server: + + /opt/rt4/sbin/rt-server --server Starman --port 8080 + +B<NOTICE>: After you run the standalone server as root, you will need to +remove your C<var/mason> directory, or the non-standalone servers +(Apache, etc), which run as a non-privileged user, will not be able to +write to it and will not work. + + +=head2 Apache + +B<WARNING>: Both C<mod_speling> and C<mod_cache> are known to break RT. +C<mod_speling> will cause RT's CSS and JS to not be loaded, making RT +appear unstyled. C<mod_cache> will cache cookies, making users be +spontaneously logged in as other users in the system. + +=head3 mod_fastcgi + + # Tell FastCGI to put its temporary files somewhere sane; this may + # be necessary if your distribution doesn't already set it + #FastCgiIpcDir /tmp + + FastCgiServer /opt/rt4/sbin/rt-server.fcgi -processes 5 -idle-timeout 300 + + <VirtualHost rt.example.com> + ### Optional apache logs for RT + # Ensure that your log rotation scripts know about these files + # ErrorLog /opt/rt4/var/log/apache2.error + # TransferLog /opt/rt4/var/log/apache2.access + # LogLevel debug + + AddDefaultCharset UTF-8 + + Alias /NoAuth/images/ /opt/rt4/share/html/NoAuth/images/ + ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/ + + DocumentRoot "/opt/rt4/share/html" + <Location /> + Order allow,deny + Allow from all + + Options +ExecCGI + AddHandler fastcgi-script fcgi + </Location> + </VirtualHost> + +=head3 mod_fcgid + + <VirtualHost rt.example.com> + ### Optional apache logs for RT + # Ensure that your log rotation scripts know about these files + # ErrorLog /opt/rt4/var/log/apache2.error + # TransferLog /opt/rt4/var/log/apache2.access + # LogLevel debug + + AddDefaultCharset UTF-8 + + Alias /NoAuth/images/ /opt/rt4/share/html/NoAuth/images/ + ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/ + + DocumentRoot "/opt/rt4/share/html" + <Location /> + Order allow,deny + Allow from all + + Options +ExecCGI + AddHandler fcgid-script fcgi + </Location> + </VirtualHost> + +=head3 mod_perl 2.xx + +B<WARNING: mod_perl 1.99_xx is not supported.> + +B<WARNING>: Due to thread-safety limitations, all timestamps will be +presented in the webserver's default time zone when using the C<worker> +and C<event> MPMs; the C<$Timezone> setting and the user's timezone +preference are ignored. We suggest the C<prefork> MPM or FastCGI +deployment if your privileged users are in a different timezone than the +one the server is configured for. + + <VirtualHost rt.example.com> + ### Optional apache logs for RT + # ErrorLog /opt/rt4/var/log/apache2.error + # TransferLog /opt/rt4/var/log/apache2.access + # LogLevel debug + + AddDefaultCharset UTF-8 + + DocumentRoot "/opt/rt4/share/html" + <Location /> + Order allow,deny + Allow from all + + SetHandler modperl + PerlResponseHandler Plack::Handler::Apache2 + PerlSetVar psgi_app /opt/rt4/sbin/rt-server + </Location> + <Perl> + use Plack::Handler::Apache2; + Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server"); + </Perl> + </VirtualHost> + +=head3 mod_perl 1.xx + +B<WARNING: mod_perl 1.99_xx is not supported.> + +To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for +configuration examples. + + +=head2 nginx + +C<nginx> requires that you start RT's fastcgi process externally, for +example using C<spawn-fcgi>: + + spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \ + -- /opt/rt4/sbin/rt-server.fcgi + +With the nginx configuration: + + server { + listen 80; + server_name rt.example.com; + access_log /var/log/nginx/access.log; + + location / { + fastcgi_param QUERY_STRING $query_string; + fastcgi_param REQUEST_METHOD $request_method; + fastcgi_param CONTENT_TYPE $content_type; + fastcgi_param CONTENT_LENGTH $content_length; + + fastcgi_param SCRIPT_NAME ""; + fastcgi_param PATH_INFO $uri; + fastcgi_param REQUEST_URI $request_uri; + fastcgi_param DOCUMENT_URI $document_uri; + fastcgi_param DOCUMENT_ROOT $document_root; + fastcgi_param SERVER_PROTOCOL $server_protocol; + + fastcgi_param GATEWAY_INTERFACE CGI/1.1; + fastcgi_param SERVER_SOFTWARE nginx/$nginx_version; + + fastcgi_param REMOTE_ADDR $remote_addr; + fastcgi_param REMOTE_PORT $remote_port; + fastcgi_param SERVER_ADDR $server_addr; + fastcgi_param SERVER_PORT $server_port; + fastcgi_param SERVER_NAME $server_name; + fastcgi_pass 127.0.0.1:9000; + } + + location /NoAuth/images { + root /opt/rt4/share/html; + } + } + + +=head2 lighttpd + + server.modules += ( "mod_fastcgi" ) + $HTTP["host"] =~ "^rt.example.com" { + alias.url = ( + "/NoAuth/images/" => "/opt/rt4/share/html/NoAuth/images/", + ) + $HTTP["url"] !~ "^/NoAuth/images/" { + fastcgi.server = ( + "/" => ( + "rt" => ( + "port" => "9000", + "bin-path" => "/opt/rt4/sbin/rt-server.fcgi", + "check-local" => "disable", + "fix-root-scriptname" => "enable", + ) + ) + ) + } + } + + +=head1 Running RT at /rt rather than / + +First you need to tell RT where it's located by setting C<$WebPath> in your +F<RT_SiteConfig.pm>: + + # Important: don't include a trailing slash here. Read `perldoc + # etc/RT_Config.pm` for more information. + Set($WebPath, "/rt"); + +Then you need to update your Apache configuration to match. Prefix any RT +related C<Alias>, C<ScriptAlias> and C<Location> directives with C</rt>. You +should also make sure C<DocumentRoot> is B<not> set to +C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>. + +For example: if you're using the sample FastCGI config above, you might change +the relevant directives to: + + Alias /rt/NoAuth/images/ /opt/rt4/share/html/NoAuth/images/ + ScriptAlias /rt /opt/rt4/sbin/rt-server.fcgi/ + + # Set DocumentRoot as appropriate for the other content you want to serve + DocumentRoot /var/www + + <Location /rt> + ... + </Location> + +If you're using the sample mod_perl configuration, you only need to change the +C<Location> directive. + +If you're not using Apache, please see L<Plack::Handler::FCGI> or the web +server's own documentation for configuration examples. + |