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_data> 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 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
  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 B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
 117 this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse
 118 to start, to prevent difficulties sending mail from RT.  Change to
 119 C<SetHandler modperl>, as the example below uses.
 120
 121     <VirtualHost rt.example.com>
 122         ### Optional apache logs for RT
 123         # ErrorLog /opt/rt4/var/log/apache2.error
 124         # TransferLog /opt/rt4/var/log/apache2.access
 125         # LogLevel debug
 126
 127         AddDefaultCharset UTF-8
 128
 129         DocumentRoot "/opt/rt4/share/html"
 130         <Location />
 131             Order allow,deny
 132             Allow from all
 133
 134             SetHandler modperl
 135             PerlResponseHandler Plack::Handler::Apache2
 136             PerlSetVar psgi_app /opt/rt4/sbin/rt-server
 137         </Location>
 138         <Perl>
 139             use Plack::Handler::Apache2;
 140             Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server");
 141         </Perl>
 142     </VirtualHost>
 143
 144 =head3 mod_perl 1.xx
 145
 146 B<WARNING: mod_perl 1.99_xx is not supported.>
 147
 148 To run RT using mod_perl 1.xx please see L<Plack::Handler::Apache1> for
 149 configuration examples.
 150
 151
 152 =head2 nginx
 153
 154 C<nginx> requires that you start RT's fastcgi process externally, for
 155 example using C<spawn-fcgi>:
 156
 157     spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \
 158         -- /opt/rt4/sbin/rt-server.fcgi
 159
 160 With the nginx configuration:
 161
 162     server {
 163         listen 80;
 164         server_name rt.example.com;
 165         access_log  /var/log/nginx/access.log;
 166
 167         location / {
 168             fastcgi_param  QUERY_STRING       $query_string;
 169             fastcgi_param  REQUEST_METHOD     $request_method;
 170             fastcgi_param  CONTENT_TYPE       $content_type;
 171             fastcgi_param  CONTENT_LENGTH     $content_length;
 172
 173             fastcgi_param  SCRIPT_NAME        "";
 174             fastcgi_param  PATH_INFO          $uri;
 175             fastcgi_param  REQUEST_URI        $request_uri;
 176             fastcgi_param  DOCUMENT_URI       $document_uri;
 177             fastcgi_param  DOCUMENT_ROOT      $document_root;
 178             fastcgi_param  SERVER_PROTOCOL    $server_protocol;
 179
 180             fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
 181             fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;
 182
 183             fastcgi_param  REMOTE_ADDR        $remote_addr;
 184             fastcgi_param  REMOTE_PORT        $remote_port;
 185             fastcgi_param  SERVER_ADDR        $server_addr;
 186             fastcgi_param  SERVER_PORT        $server_port;
 187             fastcgi_param  SERVER_NAME        $server_name;
 188             fastcgi_pass 127.0.0.1:9000;
 189         }
 190
 191         location /NoAuth/images {
 192             root /opt/rt4/share/html;
 193         }
 194     }
 195
 196
 197 =head2 lighttpd
 198
 199     server.modules += ( "mod_fastcgi" )
 200     $HTTP["host"] =~ "^rt.example.com" {
 201         alias.url = (
 202             "/NoAuth/images/" => "/opt/rt4/share/html/NoAuth/images/",
 203         )
 204         $HTTP["url"] !~ "^/NoAuth/images/" {
 205             fastcgi.server = (
 206                 "/" => (
 207                     "rt" => (
 208                         "port"        => "9000",
 209                         "bin-path"    => "/opt/rt4/sbin/rt-server.fcgi",
 210                         "check-local" => "disable",
 211                         "fix-root-scriptname" => "enable",
 212                     )
 213                 )
 214             )
 215         }
 216     }
 217
 218
 219 =head1 Running RT at /rt rather than /
 220
 221 First you need to tell RT where it's located by setting C<$WebPath> in your
 222 F<RT_SiteConfig.pm>:
 223
 224     # Important: don't include a trailing slash here.  Read `perldoc
 225     # etc/RT_Config.pm` for more information.
 226     Set($WebPath, "/rt");
 227
 228 Then you need to update your Apache configuration to match.  Prefix any RT
 229 related C<Alias>, C<ScriptAlias> and C<Location> directives with C</rt>.  You
 230 should also make sure C<DocumentRoot> is B<not> set to
 231 C</opt/rt4/share/html/>, otherwise RT's source will be served from C</>.
 232
 233 For example: if you're using the sample FastCGI config above, you might change
 234 the relevant directives to:
 235
 236     Alias /rt/NoAuth/images/ /opt/rt4/share/html/NoAuth/images/
 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.
 251