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