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):

sudo apt-get install apache2 libapache2-mod-python

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

Configuring Apache¶

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:

# /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>

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.

Setting up the router¶

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

#!/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)

Compared to the Request Router, there are a few things different here (broadly similar to Standalone):

1. 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.
2. 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'.
3. 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.

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