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

h1. Configuring 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. |

h1. Setting up the µ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.

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