=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/rt5/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/rt5/sbin/rt-server --server Starman --port 8080

To listen on IPv6 too, you can install L<IO::Socket::INET6> and use
L<Starman> exactly like the above command.

=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.

See also L<authentication/Apache Configuration>, in case you intend to
use Apache to provide authentication.

=head3 mod_fcgid

Apache can run with several different
L<Multi-Processing Modules (MPMs)|https://httpd.apache.org/docs/2.4/mpm.html>.
To use mod_fcgid, you need to run it with the L<prefork MPM|https://httpd.apache.org/docs/2.4/mod/prefork.html>.
Most Linux distributions today use the event MPM by default, so it is
important to make sure Apache is configured to use prefork on your RT
server. If you do not use prefork MPM, RT will start okay but fail under
production load, either because the web server crashes or performance
severely degrades.

B<WARNING>: Before mod_fcgid 2.3.6, the maximum request size was 1GB.
Starting in 2.3.6, this is now 128Kb.  This is unlikely to be large
enough for any RT install that handles attachments.  You can read more
about FcgidMaxRequestLen at
L<http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html#fcgidmaxrequestlen>

Most distributions will have a mod_fcgid.conf or similar file with
mod_fcgid configurations and you should add:

    FcgidMaxRequestLen 1073741824

to return to the old default.

    <VirtualHost rt.example.com>
        ### Optional apache logs for RT
        # Ensure that your log rotation scripts know about these files
        # ErrorLog /opt/rt5/var/log/apache2.error
        # TransferLog /opt/rt5/var/log/apache2.access
        # LogLevel debug

        AddDefaultCharset UTF-8

        ScriptAlias / /opt/rt5/sbin/rt-server.fcgi/

        DocumentRoot "/opt/rt5/share/html"
        <Location />
            Require all granted
            Options +ExecCGI
            AddHandler fcgid-script fcgi
        </Location>
    </VirtualHost>

=head3 mod_proxy_fcgi

This Apache module supports proxying requests via the FastCGI protocol.
In addition to running Apache, you also need to start RT FCGI processes
separately with a command like this:

    /opt/rt5/sbin/rt-server.fcgi --listen /opt/rt5/var/rt.sock --nproc 10

In this configuration, RT runs with L<Plack::Handler::FCGI> and supports any
arguments documented there.

Below is the corresponding Apache configuration:

    <VirtualHost rt.example.com>
        AddDefaultCharset UTF-8

        ProxyPass / unix:/opt/rt5/var/rt.sock|fcgi://localhost/
        ProxyFCGIBackendType GENERIC
        ProxyFCGISetEnvIf "true" SCRIPT_NAME ""
    </VirtualHost>

Note that the SCRIPT_NAME directive is needed to avoid issues with URIs not
being properly encoded, causing errors with URIs that have spaces.

In our testing we have found that this method shares more memory between
RT FCGI processes, so it can allow you to run more RT processes with less
memory. This comes at the cost of some extra management of the FCGI processes,
which mod_fcgid handles for you.

=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.

B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse
to start, to prevent difficulties sending mail from RT.  Change to
C<SetHandler modperl>, as the example below uses.

    <VirtualHost rt.example.com>
        ### Optional apache logs for RT
        # ErrorLog /opt/rt5/var/log/apache2.error
        # TransferLog /opt/rt5/var/log/apache2.access
        # LogLevel debug

        AddDefaultCharset UTF-8

        DocumentRoot "/opt/rt5/share/html"
        <Location />
            Require all granted
            SetHandler modperl
            PerlResponseHandler Plack::Handler::Apache2
            PerlSetVar psgi_app /opt/rt5/sbin/rt-server
        </Location>
        <Perl>
            use Plack::Handler::Apache2;
            Plack::Handler::Apache2->preload("/opt/rt5/sbin/rt-server");
        </Perl>
    </VirtualHost>

=head3 Token Authentication

If you plan to set up token-based access, possibly to use L<RT::REST2>,
add the following directive to your RT Apache configuration to allow
RT to access the Authorization header.

    SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

More information is available in L<RT::Authen::Token>.

=head3 Restricting the REST 1.0 mail-gateway

RT processes email via a REST 1.0 endpoint. If you accept email on the same
server as your running RT, you can restrict this endpoint to localhost only
with a configuration like the following:

    # Accept requests only from localhost
    <Location /REST/1.0/NoAuth/mail-gateway>
        Require local
    </Location>

If you run C<bin/rt-mailgate> on a separate server, you can update
the above to allow additional IP addresses.

    <Location /REST/1.0/NoAuth/mail-gateway>
        Require ip 127.0.0.1 ::1 192.0.2.0  # Add your actual IPs
    </Location>

See the L<Apache documentation|https://httpd.apache.org/docs/2.4/mod/mod_authz_host.html>
for additional configuration options.

After adding this configuration, test receiving email and confirm
your C<bin/rt-mailgate> utility and C</etc/aliases> configurations
can successfully submit email to RT.

=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/rt5/sbin/rt-server.fcgi

With the nginx configuration:

    server {
        listen 80;
        server_name rt.example.com;
        access_log  /var/log/nginx/access.log;

        location / {
            client_max_body_size 100M;

            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;
        }
    }

The default nginx value for C<client_max_body_size> is 1M, which is too
small for most RT systems that accept attachments. The 100M value above is
a suggestion. Adjust this to accept the largest attachments you expect to
allow via email and the web UI.

=head2 lighttpd

    server.modules += ( "mod_fastcgi" )
    $HTTP["host"] =~ "^rt.example.com" {
        fastcgi.server = (
            "/" => (
                "rt" => (
                    "socket"      => "/opt/rt5/var/socket",
                    "bin-path"    => "/opt/rt5/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<ScriptAlias> and C<Location> directives with C</rt>.  You
should also make sure C<DocumentRoot> is B<not> set to
C</opt/rt5/share/html/>, otherwise RT's source will be served from C</>.

For example: if you're using the sample mod_fcgid config above, you might change
the relevant directives to:

    ScriptAlias /rt /opt/rt5/sbin/rt-server.fcgi/

    # Set DocumentRoot as appropriate for the other content you want to serve
    DocumentRoot /var/www

    <Location /rt>
        ...
    </Location>

If you are using mod_proxy_fcgi, change these:

    ProxyPass /rt/ unix:/opt/rt5/var/rt.sock|fcgi://localhost/
    <Location /rt>
        ProxyFCGISetEnvIf "true" SCRIPT_NAME "/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.