
=head1 NAME

PSA::Installation - how to install PSA applications into various web servers

=head1 DESCRIPTION

This document provides instructions on how to configure PSA to work
with various web servers and URL styles/methods.

The PSA framework itself could easily accept requests directly,
without using a web server.  Most of the request parsing is already
seperated from the request source mechanism (these are horribly tied
to system/CGI locations in most CGI::* modules).  This is because
L<PSA::Request::CGI> is a complete encapsulation of the request, not a
partial encapsulation.

=head1 APACHE

First, you need to get the FastCGI source, and compile it as an Apache
module.  You might be able to use apxs(sic?) to do this.  Or, maybe
you can just use C<apt-get install libapache-mod-fastcgi>.

There are various ways that you can connect a FastCGI application, but
the best is probably to use the C<FastCGIExternalServer> option.

Set the external FastCGI socket path to somewhere readable to the web
server, preferably outside the webroot.  Then, set in the
F<etc/psa.yml>:

 acceptor:
   socket: "/var/lib/myapp/appSocket"
   nproc: 5

The above will create 5 handler processes when you run C<psa>.  If you
are to be using a system-wide init script, you should also set up an
C<auth:> section of the config as described in L<PSA::Config>.

If you're using FastCGI, then first add a user & group to the system
for the application.  Apache/mod_perl seemed to forget at some point
that it's good to have different applications run as different UNIX
users, so mod_perl is incompatible with the User/Group options.

LoadModule fastcgi_module /usr/lib/apache/1.3/mod_fastcgi.so
LoadModule rewrite_module /usr/lib/apache/1.3/mod_rewrite.so

RewriteLock "/var/run/rewrite.LCK"

<VirtualHost your_ip>
    DocumentRoot /home/user/application

    User user
    Group group

    ServerName www.your_dns_name.www.gwbush.com
    ServerAlias your_dns_name.www.gwbush.com

    <Directory /home/user/application>
        <FilesMatch ^.*\.fcgi$>
            Options +ExecCGI
            allow from all

            <IfModule mod_perl.c>
                SetHandler perl-script
                PerlHandler Apache::Registry
            </IfModule>

            <IfModule mod_fastcgi.c>
	        SetHandler fastcgi-script
            </IfModule>
        </FilesMatch>
        Order allow,deny
        Allow from all
    </Directory>

</VirtualHost>

Alternatively, if your system is set to already execute files with a
.cgi extension as CGI, or you have "AllowOverride all" set, then you
should just be able to copy the entire PSA application somewhere under
your webroot.

=head1 Lighttpd

Phew, what a breeze.  Whilst this web server is very basic and lacking
some basic functionality, I think it's on the right track!  It's more
lightweight than your poppa, too!

Add C<mod_fastcgi> support to the C<server.modules> option in your
F<lighttpd.conf>, first.

=head2 location-style URLs

Example entry in F<lighttpd.conf>:

 fastcgi.server =
    ( "/apps/vt2" =>
      ( "vt2" =>
        ( "socket" => "/var/www/vt2.utsl.gen.nz/var/appSocket",
          "check-local" => "disable"
        )
      ),
    )

With this URL style, the application server serves static files as
well.  This is configured in F<psa.yml> (when using the default
L<psa-bin/issue.pl> template generator) as below:

 env:
  

 acceptor:
   base: "/apps/vt2"
 
 uri:
   flat:
     "/apps/vt2/"


=head2 handler-style URLs

This mode is slightly more optimal, as the web server can serve static
files directly, but can be considerably more fiddly and temperamental.

 server.indexfiles =
    ( "index.pl", "index.html", "index.htm", "default.htm" )
 
 fastcgi.server =
    ( ".pl" =>
      ( "vt2" =>
        ( "socket" => "/var/www/vt2.utsl.gen.nz/var/appSocket",
          "check-local" => "enable"
        )
      ),
    )
 
 server.error-handler-404   = "/err.pl/404"

With this URL style, you need to tell the template generator if you
have any paths which you want to be handled by a script, and also
place dummy F<.pl> files in your F<docs/> (static webroot)

 acceptor:
   base: "/"

 uri:
   flat: "/"

   dynamic:
     - '/proj'
     - '/lists'

In the above example, the C</proj> URL will be re-written to
C</proj.pl> so that the web server knows it is a dynamic request.
This I<does> mean, however, that URLs that change can be problematic.

For that reason, the stock 404 handler can redirect to new handlers as
well as static files again configured via F<psa.yml>:

 404:
   moved:
     '/proj/': '/proj.pl/'

=head1 LiteSpeed

=head1 Zeus

=head1 thttpd Pro

=cut

