To more and more Python web developers, WSGI holds the key to the Python web development future. Since there are a number of important web development frameworks and the power of Python makes it really easy to create new ones quickly, interacting with best of breed applications developed in multiple frameworks could soon be the best way to create a new Python web site.

Until relatively recently, Zope and some of its most successful applications, like Plone, ran the risk of missing the WSGI party, but not anymore, now that Repoze is here.

Repoze is a bridge between Zope and WSGI, which has the objectives of both helping Zope developers publish applications using WSGI and, equally important, letting non-Zope web developers use parts of Zope independently.

There are a number of WSGI servers available, but this tutorial will focus on using mod_wsgi, which is a WSGI adapter module for Apache. There are a number of reasons for this.

First, Apache is the most popular web hosting platform, so there are a number of web developers and site administrators already familiar with it. Plone, for example, usually is installed behind Apache for production servers.

Second, there are also lots of Python applications that already run under Apache using mod_python, and there are a few WSGI adapters for this module as well, but mod_wsgi is written in C code and has lower memory overhead and better performance than those adapters.

Also, one of the goals of mod_wsgi is to break into the low cost commodity web hosting market, which would be good for Python and ultimately for Plone and Zope.

I decided to cover the whole setup from new server to Plone startup in this tutorial, to offer a complete guide for the whole process in a single place. I chose to use Linux as the operating system, again because it's by far the most popular way to deploy web applications right now. Ubuntu is my distribution of choice, but this steps apply equally well to any Debian based distribution. Other distributions use different package managers and probably other system paths, but you should be able to figure out easily what you need in any case.

I started with a clean install of Ubuntu Linux 7.10 on a new virtual server. The first step is to install the necessary packages for the correct Python version (Zope currently requires Python 2.4) and also for the Apache server.

Before that, It was necessary to install the required packages for being able to compile and build software using Ubuntu (other distributions usually don't need this). Be aware that both package installation and Apache module additions usually require root access.

$ apt-get install build-essential

Next, the packages for Python and Apache. Like most packaged Linux distributions, Ubuntu requires a separate install for the development libraries of each piece of software:

$ apt-get install python2.4
$ apt-get install python2.4-dev
$ apt-get install apache2
$ apt-get install apache2-dev

Repoze uses Python's setup tools, so that package is needed as well:

$ apt-get install python-setuptools

Now, the server is ready for mod_wsgi. Since there is no package for this in Ubuntu 7.10, we need to get it directly from the download site:

$ wget http://modwsgi.googlecode.com/files/mod_wsgi-2.0c4.tar.gz

$ tar xzf mod_wsgi-2.0c4.tar.gz
$ cd mod_wsgi-2.0c4
$ ./configure --with-python=/usr/bin/python2.4
$ make
$ make install

Note that it is necessary to compile mod_wsgi using the same Python you will use to run your web site. Since Zope requires 2.4, the --with-python option was used to point to the newly installed Python.

Once mod_wsgi is intalled, the apache server needs to be told about it. On Apache 2, this is done by adding the load declaration and any configuration directives inside the mods-available directory.

The load declaration was put on a file named wsgi.load, which contains only this:

LoadModule wsgi_module /usr/lib/apache2/modules/mod_wsgi.so

The configuration directives reside in the file named wsgi.conf, they contain an almost identical configuration to the one shown on the repoze.org site, on the deployment page. Replace ${sandbox} below with the path to your Repoze installation's top-level environment.

WSGIPythonHome ${sandbox}
WSGIDaemonProcess tmp threads=1 processes=4 maximum-requests=10000 python-path=${sandbox}/lib/python2.4/site-packages
<VirtualHost *:80>
  ServerName my.machine.local
  WSGIScriptAlias /site ${sandbox}/bin/zope2.wsgi
  WSGIProcessGroup tmp
  WSGIPassAuthorization On
  SetEnv HTTP_X_VHM_HOST http://my.machine.local/site
  SetEnv PASTE_CONFIG ${sandbox}/etc/zope2.ini
</VirtualHost>

This will run mod_wsgi in 'daemon' mode, which means it will launch a number of processes to run the configured WSGI application instead of using the Apache process. Since Repoze uses virtualenv, the site-packages directory of the virtual Python used to run it needs to be passed in the python-path variable. To tell mod_wsgi which WSGI application to run, we use the WSGIScriptAlias directive and pass it the path to the desired application.

To really activate this configuration files, another step is required, which is to create soft links for them under the mods-enabled directory of the Apache configuration:

$ cd mods-enabled
$ ln -s ../mods-available/wsgi.load
$ ln -s ../mods-available/wsgi.conf

For apache 1.3 or Apache 2 with an old directory layout, you may need to put both of these snippets inside the httpd.conf file in your Apache's /etc directory. The soft links above will not be necessary in that case.

Once we have mod_wsgi configured, the server is finally ready for Repoze. The first step is to create a new Repoze sandbox. Since Repoze, Zope and friends require lots of packages, the idea is to get a clean environment for your project, where packages do not conflict with existing or future packages from your normal Python installation. We use setuptools to install the virtualenv package:

$ easy_install-2.4 virtualenv

 When virtualenv is ready, we create the actual sandbox. Choose a directory where you would like to install the Plone sandbox and pass it to virtualenv like this:

$ virtualenv --no-site-packages /path/to/sandbox

The --no-site-packages option ensures that the new Python installation does not inherit any packages from the normal installation. After this is done, we finally install Plone using a specially packaged egg from the repoze.org repository. Right now, since Plone is not packaged as a collection of eggs, this is the only place where we can get that. Sadly, this means that until the Repoze crew gets around to creating a new egg, we are limited to Plone version 3.0.1. In the future, Plone may be packaged in a usable manner and we could then use plone.org as a repository, thus getting the latest official release. For now, we have to do this:

$ /path/to/sandbox/bin/easy_install -i http://dist.repoze.org/simple repoze.plone

This command was run using my regular user account and created a plone directory which is actually the Repoze sandbox. The repoze.plone egg that installs this also installs a few sample configuration files, which may be used almost "as is" to run the new site. Be warned that distutils tries to byte-compile all python files it finds at install time, which means the Python scripts under Plone's skin directories will throw some syntax errors, since they are not always valid Python code. You can safely ignore these errors.

The last thing that we need to do is to create the Zope instance for our Plone site:

$ /path/to/sandbox/bin/mkzope2instance .

This will create all of the required configuration files and directories for a Zope instance. The most important files are located on the etc directory of the sandbox:

• 'zope.ini', a Paste configuration file used to establish the Paste (WSGI) pipeline which repoze.zope2 will use to serve up repoze.zope2.
• 'zope.conf', a classic Zope 2 configuration file which can be used to adjust Zope settings.
• 'site.zcml', a boilerplate site.zcml that should be used to control ZCML processing.

To test the installation, first it is needed to add a new user to the Zope site. The command is run from inside the sandbox directory:

$ bin/addzope2user cguardia password

Now the site could be tested using paster:

$ bin/paster serve etc/zope2.ini

Once this is run you will have access to the newly installed Zope site at port 8080. It's a good idea to take advantage of this test to add a Plone Site inside, so everything is ready for the WSGI configuration.

The only other requirement for running under mod_wsgi is to install a ZEO server and modify the sandbox's etc/zope.conf file to use a client storage pointing to it. This is very easy, just run (inside the sandbox):

$ bin/mkzeoinst .

This creates runzeo and zeoctl scripts under the bin directory. Since mkzeoinst doesn't delete existing files, it's important to make sure that they don't exist before running it.

Now you need to set up a ZEO client or more. Here is a sample configuration stanza for one client, which should be added to the zope.conf file:

<zodb_db main>
    cache-size 5000
    <zeoclient>
        server localhost:8100
        storage 1
        cache-size 20MB
        name zeostorage
        var $INSTANCE/var
    </zeoclient>
    mount-point /
</zodb_db>

That's it. The site is now ready to work behind Apache and mod_wsgi.

$ bin/zeoctl start
$ sudo apache2ctl start

There it is. Zope can now run directly behind the Apache server, without need for its own ZServer. As you can see, using Repoze, Zope and Plone can now coexist peacefully with other Python frameworks using WSGI.