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

To configure applications without authenticators, use the config.py script
in tools/Apache to set up mod_python applications. For example:

python tools/Apache/config.py \
    mod_python \
    /home/paulb/Software/Python/WebStack/examples/ModPython/CookiesApp/CookiesHandler.py \
    /etc/apache2/sites-available \
    cookies-mod \
    /cookies \
    .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.cookies
http://localhost/cookies/my.cookies

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

For each application, add an Alias line to httpd.conf to point to the directory
containing the handler package, then specify the appropriate module name as the
PythonHandler.

Alias /simple "/home/paulb/Software/Python/WebStack/examples/ModPython/SimpleApp"

<Directory "/home/paulb/Software/Python/WebStack/examples/ModPython/SimpleApp">
    AddHandler python-program .simple
    PythonHandler SimpleHandler
    PythonDebug On
</Directory>

It would appear that the directory really should be distinct from others
defined for mod_python, and that the handler should have a distinct name from
other handlers employed.

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.

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

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

Examples of URL paths not addressing the application are as follows:

  /agenda/my-agenda.simple
  /simple/tasks/my-tasks.simple

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:

Alias /auth "/home/paulb/Software/Python/WebStack/examples/ModPython/AuthApp"

<Directory "/home/paulb/Software/Python/WebStack/examples/ModPython/AuthApp">
    AddHandler python-program .py
    PythonHandler AuthHandler
    PythonAuthenHandler AuthHandler
    PythonDebug On
    AuthType Basic
    AuthName "AuthResource"
    AuthUserFile /usr/local/apache2/conf/users
    require valid-user
</Directory>

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.
