µWeb

h1. Requirements

For µWeb to work on Apache, you need the @mod_python@ package installed and enabled. On Debian (version 5 and up) this requires no effort beyond the straightforward installation of the package (here included with apache2 for ease of use):

<pre><code class="shell">

sudo apt-get install apache2 libapache2-mod-python

</code></pre>

The module automatically gets enabled and requires no further user-configuration.

h2. Apache config example

The second step is setting up an Apache config file. This is a basic configuration that sets up a VirtualHost for a specific hostname. This is the common scenario for Apache configurations, though many options are possible. We create the following file in Apache's @sites-available@ directory, and then enable it using @a2ensite@ (or an equivalent). This example is a copy of the router contained in the @uweb_info@ demo project:

<pre><code class="config">

# /var/www/uweb_info/ should contain the uWeb router

# This can be achieved by either copying the router (including optional

# configuration file) to this directory, or creating a symbolic link where

# /var/www/uweb_info points to the directory containing the router.

<VirtualHost *:80>

    ServerName      uweb.local

    DocumentRoot    /var/www/uweb_info/

</VirtualHost>

<Directory "/var/www/uweb_info">

    SetHandler        mod_python

    PythonHandler     router

    PythonPath        "['/home/elmer', '/home/elmer/devel'] + sys.path"

    PythonDebug       on

    PythonAutoReload  on

</Directory>

</code></pre>

The VirtualHost statement configures Apache to respond only to the given ServerName, so that it blends in nicely with a multi-website setup. The directory command contains the functional @mod_python@ statements:

|_.Directive |_.Meaning |

| SetHandler | Instructs Apache to handle all requests for (and under) this directory to be handled through the @mod_python@ handler. |

| PythonHandler | Name of the module that should route requests. Points to the location of the router (relative from the @DocumentRoot@). |

| PythonPath | This is a Python statement that is necessary to be able to include the uWeb framework. If µWeb is installed in @'/home/john/devel/uweb/'@ then the added path should be @'/home/john/devel/'@ |

| PythonDebug | Prints @mod_python@ debug reports in case there is an error causing µWeb itself to break. Like other debugging, it is suggested you turn this 'off' for production sites. |

| PythonAutoReload | Automatically reloads python source files if and when they have changed. Not very reliable on the µWeb Framework stack. Default to 'on', suggested you turn this 'off' for production sites. |

h2. µWeb router example

After setting up Apache configuration, it's time to move the *[[router]]* file to the appropriate location. For the example above, the router should be placed in @'/var/www/uweb_info/router.py'@ (of course, '.pyc' and '.pyo' would also work).

<pre><code class="python">

#!/usr/bin/python

"""A uWeb demonstration project."""

# uWeb Framework

import uweb

# Project's controller

from uweb.uweb_info import pages

# uWeb configuration variables

CONFIG = 'example.conf'

PACKAGE = 'uweb_info'

PAGE_CLASS = pages.PageMaker

ROUTES = (

    ('/static/(.*)', 'Static'),

    ('/(broken.*)', 'FourOhFour'),

    ('/haltandcatchfire', 'MakeFail'),

    ('/json', 'Json'),

    ('/text', 'Text'),

    ('/redirect/(.*)', 'Redirect'),

    ('/OpenIDLogin', '_OpenIdInitiate'),

    ('/OpenIDValidate', '_OpenIdValidate'),

    ('/ULF-Challenge', '_ULF_Challenge'),

    ('/ULF-Login', '_ULF_Verify'),

    ('/(.*)', 'Index'))

uweb.ServerSetup(apache_logging=True)

</code></pre>

Compared to the *[[request router]]*, there are a few things different here (broadly similar to Standalone):

# @CONFIG@ is used to indicate the path for the configuration file, if there is any. This is a path to the configuration file relative from the router location. In this router, the configuration file is a file named example.conf in the same directory as the router. If there is no configuration file, this variable should be omitted.

# @PACKAGE@ is used to indicate the package name of the project. The package name is used to group logfiles by. Logfiles will be automatically created and written to either. If no explicit @PACKAGE@ variable is set, it defaults to @'uweb_project'@.

# On the @uweb.ServerSetup@ call, there is an optional argument @'apache_logging'@ that controls application logging (enabled by default). This refers to the explicit logging done inside µWeb using @logging.log*@ methods. For this to work, there must be a writable path for µWeb either

#* on @'/var/log/underdark/'@ (the latter is recommended for Apache mode). This creates a subdirectory after the @PACKAGE@ name, and in there creates SQLite logfiles based on the router name.

#* on the home-directory of the apache user, in a subdirectory @.underdark@ (this directory will be created if it doesn't exist). From here, a directory will be created after the @PACKAGE@ name, and in a @'logs'@ directory, the various SQLite logfiles will be stored.

h2. Reload and run

After reloading the Apache configuration, the site will be available when we browse to http://uweb.local (assuming the path is resolved by DNS, or added to the machine's @hosts@ file).