rt/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> 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
  70     <VirtualHost rt.example.com>
  71         ### Optional apache logs for RT
  72         # Ensure that your log rotation scripts know about these files
  73         # ErrorLog /opt/rt4/var/log/apache2.error
  74         # TransferLog /opt/rt4/var/log/apache2.access
  75         # LogLevel debug
  76
  77         AddDefaultCharset UTF-8
  78
  79         Alias /NoAuth/images/ /opt/rt4/share/html/NoAuth/images/
  80         ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/
  81
  82         DocumentRoot "/opt/rt4/share/html"
  83         <Location />
  84             Order allow,deny
  85             Allow from all
  86
  87             Options +ExecCGI
  88             AddHandler fcgid-script fcgi
  89         </Location>
  90     </VirtualHost>
  91
  92 =head3 mod_perl 2.xx
  93
  94 B<WARNING: mod_perl 1.99_xx is not supported.>
  95
  96 B<WARNING>: Due to thread-safety limitations, all timestamps will be
  97 presented in the webserver's default time zone when using the C<worker>
  98 and C<event> MPMs; the C<$Timezone> setting and the user's timezone
  99 preference are ignored.  We suggest the C<prefork> MPM or FastCGI
 100 deployment if your privileged users are in a different timezone than the
 101 one the server is configured for.
 102
 103     <VirtualHost rt.example.com>
 104         ### Optional apache logs for RT
 105         # ErrorLog /opt/rt4/var/log/apache2.error
 106         # TransferLog /opt/rt4/var/log/apache2.access
 107         # LogLevel debug
 108
 109         AddDefaultCharset UTF-8
 110
 111         DocumentRoot "/opt/rt4/share/html"
 112         <Location />
 113             Order allow,deny
 114             Allow from all
 115
 116             SetHandler modperl
 117             PerlResponseHandler Plack::Handler::Apache2
 118             PerlSetVar psgi_app /opt/rt4/sbin/rt-server
 119         </Location>
 120         <Perl>
 121             use Plack::Handler::Apache2;
 122             Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server");
 123         </Perl>
 124     </VirtualHost>
 125
 126 =head3 mod_perl 1.xx
 127
 128 B<WARNING: mod_perl 1.99_xx is not supported.>
 129
 130 To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for
 131 configuration examples.
 132
 133
 134 =head2 nginx
 135
 136 C<nginx> requires that you start RT's fastcgi process externally, for
 137 example using C<spawn-fcgi>:
 138
 139     spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \
 140         -- /opt/rt4/sbin/rt-server.fcgi
 141
 142 With the nginx configuration:
 143
 144     server {
 145         listen 80;
 146         server_name rt.example.com;
 147         access_log  /var/log/nginx/access.log;
 148
 149         location / {
 150             fastcgi_param  QUERY_STRING       $query_string;
 151             fastcgi_param  REQUEST_METHOD     $request_method;
 152             fastcgi_param  CONTENT_TYPE       $content_type;
 153             fastcgi_param  CONTENT_LENGTH     $content_length;
 154
 155             fastcgi_param  SCRIPT_NAME        "";
 156             fastcgi_param  PATH_INFO          $uri;
 157             fastcgi_param  REQUEST_URI        $request_uri;
 158             fastcgi_param  DOCUMENT_URI       $document_uri;
 159             fastcgi_param  DOCUMENT_ROOT      $document_root;
 160             fastcgi_param  SERVER_PROTOCOL    $server_protocol;
 161
 162             fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
 163             fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;
 164
 165             fastcgi_param  REMOTE_ADDR        $remote_addr;
 166             fastcgi_param  REMOTE_PORT        $remote_port;
 167             fastcgi_param  SERVER_ADDR        $server_addr;
 168             fastcgi_param  SERVER_PORT        $server_port;
 169             fastcgi_param  SERVER_NAME        $server_name;
 170             fastcgi_pass 127.0.0.1:9000;
 171         }
 172
 173         location /NoAuth/images {
 174             root /opt/rt4/share/html;
 175         }
 176     }
 177
 178
 179 =head2 lighttpd
 180
 181     server.modules += ( "mod_fastcgi" )
 182     $HTTP["host"] =~ "^rt.example.com" {
 183         alias.url = (
 184             "/NoAuth/images/" => "/opt/rt4/share/html/NoAuth/images/",
 185         )
 186         $HTTP["url"] !~ "^/NoAuth/images/" {
 187             fastcgi.server = (
 188                 "/" => (
 189                     "rt" => (
 190                         "port"        => "9000",
 191                         "bin-path"    => "/opt/rt4/sbin/rt-server.fcgi",
 192                         "check-local" => "disable",
 193                         "fix-root-scriptname" => "enable",
 194                     )
 195                 )
 196             )
 197         }
 198     }
 199
 200
 201 =head1 Running RT at /rt rather than /
 202
 203 First you need to tell RT where it's located by setting C<$WebPath> in your
 204 F<RT_SiteConfig.pm>:
 205
 206     # Important: don't include a trailing slash here.  Read `perldoc
 207     # etc/RT_Config.pm` for more information.
 208     Set($WebPath, "/rt");
 209
 210 Then you need to update your Apache configuration to match.  Prefix any RT
 211 related C<Alias>, C<ScriptAlias> and C<Location> directives with C</rt>.  You
 212 should also make sure C<DocumentRoot> is B<not> set to
 213 C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>.
 214
 215 For example: if you're using the sample FastCGI config above, you might change
 216 the relevant directives to:
 217
 218     Alias /rt/NoAuth/images/ /opt/rt4/share/html/NoAuth/images/
 219     ScriptAlias /rt /opt/rt4/sbin/rt-server.fcgi/
 220
 221     # Set DocumentRoot as appropriate for the other content you want to serve
 222     DocumentRoot /var/www
 223
 224     <Location /rt>
 225         ...
 226     </Location>
 227
 228 If you're using the sample mod_perl configuration, you only need to change the
 229 C<Location> directive.
 230
 231 If you're not using Apache, please see L<Plack::Handler::FCGI> or the web
 232 server's own documentation for configuration examples.
 233