Configuring Apache
==================

To configure applications without authenticators, use the
webstack_apache_config.py script (installed with setup.py but also found in
tools/Apache) to set up mod_python applications. For example:

python webstack_apache_config.py \
    mod_python \
    /home/paulb/Software/Python/WebStack/examples/ModPython/CookiesApp/CookiesHandler.py \
    /etc/apache2/sites-available \
    cookies-mod \
    /cookies \

This script can also be used to configure CGI applications. Run the script
without any arguments to see the documentation.

With the above command, the "cookies" application should be visitable with
URLs resembling these:

http://localhost/cookies/test
http://localhost/cookies/my-cookies

The Manual Approach
-------------------

For each application, add a Location section to httpd.conf (or an appropriate
equivalent configuration file) as follows:

<Location "/simple">
    SetHandler python-program
    PythonHandler SimpleHandler
    PythonDebug On
    PythonPath "['/home/paulb/Software/Python/WebStack/examples/ModPython/SimpleApp'] + sys.path"
</Location>

The WebStack package must reside on the PYTHONPATH, along with the package
containing the application itself. Therefore, ensure that the handler uses the
appropriate entries in sys.path or use the PythonPath directive as shown
above.

Using the above definition in httpd.conf, only server resources residing
directly below "/simple" in the URL "hierarchy" would be associated with the
Simple WebStack application's resources. Therefore, the following URL paths
would access the application:

  /simple/home
  /simple/tasks/my-tasks
  /simple/agenda/tomorrow/first-thing

Authentication/Authorisation in mod_python
==========================================

Apache imposes fairly strict controls over authentication, requiring the
addition of various declarations in the configuration in order to impose
access controls on applications, and for WebStack authenticators to be used, a
"PythonAuthenHandler" must be declared in the application's configuration
section.

Consequently, it is necessary to define authentication methods in the
httpd.conf file as in the following example:

<Location "/auth">
    SetHandler python-program
    PythonHandler AuthHandler
    PythonAuthenHandler AuthHandler
    PythonDebug On
    AuthType Basic
    AuthName "AuthResource"
    AuthUserFile /etc/apache2/users
    require valid-user
    PythonPath "['/home/paulb/Software/Python/WebStack/examples/ModPython/AuthApp'] + sys.path"
</Location>

The details of the application's deployment, including the exact pathname of
the users file and the appropriate access policy, must obviously be defined
according to the actual application concerned.

Session Storage with mod_python
===============================

The very simple SessionStore class provided in WebStack.Helpers.Session, and
used by the WebStack.ModPython.Transaction class, requires that a directory be
created under the Apache server root with the name "WebStack-sessions". Here are
some example commands for doing this:

  cd /usr/local/apache2
  mkdir WebStack-sessions
  chown username.groupname WebStack-sessions

The given "username" and "groupname" correspond to the user and group the Apache
server assumes when running.
