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 =head2 Apache
  26
  27 B<WARNING>: Both C<mod_speling> and C<mod_cache> are known to break RT.
  28 C<mod_speling> will cause RT's CSS and JS to not be loaded, making RT
  29 appear unstyled. C<mod_cache> will cache cookies, making users be
  30 spontaneously logged in as other users in the system.
  31
  32 See also L<authentication/Apache configuration>, in case you intend to
  33 use Apache to provide authentication.
  34
  35 =head3 mod_fastcgi
  36
  37     # Tell FastCGI to put its temporary files somewhere sane; this may
  38     # be necessary if your distribution doesn't already set it
  39     #FastCgiIpcDir /tmp
  40
  41     FastCgiServer /opt/rt4/sbin/rt-server.fcgi -processes 5 -idle-timeout 300
  42
  43     <VirtualHost rt.example.com>
  44         ### Optional apache logs for RT
  45         # Ensure that your log rotation scripts know about these files
  46         # ErrorLog /opt/rt4/var/log/apache2.error
  47         # TransferLog /opt/rt4/var/log/apache2.access
  48         # LogLevel debug
  49
  50         AddDefaultCharset UTF-8
  51
  52         ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/
  53
  54         DocumentRoot "/opt/rt4/share/html"
  55         <Location />
  56             <IfVersion >= 2.4> # For Apache 2.4
  57                 Require all granted
  58             </IfVersion>
  59             <IfVersion < 2.4>  # For Apache 2.2
  60                 Order allow,deny
  61                 Allow from all
  62             </IfVersion>
  63
  64             Options +ExecCGI
  65             AddHandler fastcgi-script fcgi
  66         </Location>
  67     </VirtualHost>
  68
  69 =head3 mod_fcgid
  70
  71 B<WARNING>: Before mod_fcgid 2.3.6, the maximum request size was 1GB.
  72 Starting in 2.3.6, this is now 128Kb.  This is unlikely to be large
  73 enough for any RT install that handles attachments.  You can read more
  74 about FcgidMaxRequestLen at
  75 L<http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html#fcgidmaxrequestlen>
  76
  77 Most distributions will have a mod_fcgid.conf or similar file with
  78 mod_fcgid configurations and you should add:
  79
  80     FcgidMaxRequestLen 1073741824
  81
  82 to return to the old default.
  83
  84     <VirtualHost rt.example.com>
  85         ### Optional apache logs for RT
  86         # Ensure that your log rotation scripts know about these files
  87         # ErrorLog /opt/rt4/var/log/apache2.error
  88         # TransferLog /opt/rt4/var/log/apache2.access
  89         # LogLevel debug
  90
  91         AddDefaultCharset UTF-8
  92
  93         ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/
  94
  95         DocumentRoot "/opt/rt4/share/html"
  96         <Location />
  97             <IfVersion >= 2.4> # For Apache 2.4
  98                 Require all granted
  99             </IfVersion>
 100             <IfVersion < 2.4>  # For Apache 2.2
 101                 Order allow,deny
 102                 Allow from all
 103             </IfVersion>
 104
 105             Options +ExecCGI
 106             AddHandler fcgid-script fcgi
 107         </Location>
 108     </VirtualHost>
 109
 110 =head3 mod_perl 2.xx
 111
 112 B<WARNING: mod_perl 1.99_xx is not supported.>
 113
 114 B<WARNING>: Due to thread-safety limitations, all timestamps will be
 115 presented in the webserver's default time zone when using the C<worker>
 116 and C<event> MPMs; the C<$Timezone> setting and the user's timezone
 117 preference are ignored.  We suggest the C<prefork> MPM or FastCGI
 118 deployment if your privileged users are in a different timezone than the
 119 one the server is configured for.
 120
 121 B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
 122 this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse
 123 to start, to prevent difficulties sending mail from RT.  Change to
 124 C<SetHandler modperl>, as the example below uses.
 125
 126     <VirtualHost rt.example.com>
 127         ### Optional apache logs for RT
 128         # ErrorLog /opt/rt4/var/log/apache2.error
 129         # TransferLog /opt/rt4/var/log/apache2.access
 130         # LogLevel debug
 131
 132         AddDefaultCharset UTF-8
 133
 134         DocumentRoot "/opt/rt4/share/html"
 135         <Location />
 136             <IfVersion >= 2.4> # For Apache 2.4
 137                 Require all granted
 138             </IfVersion>
 139             <IfVersion < 2.4>  # For Apache 2.2
 140                 Order allow,deny
 141                 Allow from all
 142             </IfVersion>
 143
 144             SetHandler modperl
 145             PerlResponseHandler Plack::Handler::Apache2
 146             PerlSetVar psgi_app /opt/rt4/sbin/rt-server
 147         </Location>
 148         <Perl>
 149             use Plack::Handler::Apache2;
 150             Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server");
 151         </Perl>
 152     </VirtualHost>
 153
 154 =head3 mod_perl 1.xx
 155
 156 B<WARNING: mod_perl 1.99_xx is not supported.>
 157
 158 To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for
 159 configuration examples.
 160
 161
 162 =head2 nginx
 163
 164 C<nginx> requires that you start RT's fastcgi process externally, for
 165 example using C<spawn-fcgi>:
 166
 167     spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \
 168         -- /opt/rt4/sbin/rt-server.fcgi
 169
 170 With the nginx configuration:
 171
 172     server {
 173         listen 80;
 174         server_name rt.example.com;
 175         access_log  /var/log/nginx/access.log;
 176
 177         location / {
 178             fastcgi_param  QUERY_STRING       $query_string;
 179             fastcgi_param  REQUEST_METHOD     $request_method;
 180             fastcgi_param  CONTENT_TYPE       $content_type;
 181             fastcgi_param  CONTENT_LENGTH     $content_length;
 182
 183             fastcgi_param  SCRIPT_NAME        "";
 184             fastcgi_param  PATH_INFO          $uri;
 185             fastcgi_param  REQUEST_URI        $request_uri;
 186             fastcgi_param  DOCUMENT_URI       $document_uri;
 187             fastcgi_param  DOCUMENT_ROOT      $document_root;
 188             fastcgi_param  SERVER_PROTOCOL    $server_protocol;
 189
 190             fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
 191             fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;
 192
 193             fastcgi_param  REMOTE_ADDR        $remote_addr;
 194             fastcgi_param  REMOTE_PORT        $remote_port;
 195             fastcgi_param  SERVER_ADDR        $server_addr;
 196             fastcgi_param  SERVER_PORT        $server_port;
 197             fastcgi_param  SERVER_NAME        $server_name;
 198             fastcgi_pass 127.0.0.1:9000;
 199         }
 200     }
 201
 202
 203 =head2 lighttpd
 204
 205     server.modules += ( "mod_fastcgi" )
 206     $HTTP["host"] =~ "^rt.example.com" {
 207         fastcgi.server = (
 208             "/" => (
 209                 "rt" => (
 210                     "socket"      => "/opt/rt4/var/socket",
 211                     "bin-path"    => "/opt/rt4/sbin/rt-server.fcgi",
 212                     "check-local" => "disable",
 213                     "fix-root-scriptname" => "enable",
 214                 )
 215             )
 216         )
 217     }
 218
 219
 220 =head1 Running RT at /rt rather than /
 221
 222 First you need to tell RT where it's located by setting C<$WebPath> in your
 223 F<RT_SiteConfig.pm>:
 224
 225     # Important: don't include a trailing slash here.  Read `perldoc
 226     # etc/RT_Config.pm` for more information.
 227     Set($WebPath, "/rt");
 228
 229 Then you need to update your Apache configuration to match.  Prefix any RT
 230 related C<ScriptAlias> and C<Location> directives with C</rt>.  You
 231 should also make sure C<DocumentRoot> is B<not> set to
 232 C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>.
 233
 234 For example: if you're using the sample FastCGI config above, you might change
 235 the relevant directives to:
 236
 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.