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 3 and some of its derived applications, like Grok, 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 many web developers and site administrators already familiar with it. Grok, for example, has been installed behind Apache for production servers using mod_rewrite.

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 Grok and Zope.

I decided to cover the whole setup from new server to Grok 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 GNU/Linux Hardy Heron 8.04 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. In the commands block, the prompt with '$' is a user prompt, '#' is a root prompt you can have with sudo -s. In this part, you'll use a root terminal to not have to prefix each command by sudo. In the other parts, you'll use a user terminal where you add sudo before a command if you need to execute something as root. I usually have one terminal opened as root and another terminal as user.

$ sudo -s
# 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 python2.4-dev
# apt-get install apache2

The apache2 package usually install apache2-mpm-worker, but maybe you have the other version apache2-mpm-prefork installed. To be sure which one is installed you can execute:

# dpkg -l|grep apache2

Then install the corresponding development package, apache2-threaded-dev if apache2-mpm-worker is installed, apache2-prefork-dev if apache2-mpm-prefork is installed:

# apt-get install apache2-threaded-dev

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

# apt-get install python-setuptools

It's possible the version provided by the Ubuntu package is not the latest. If you want to have more control of the installed version of setuptools and want to update it yourself when a new version is available, you can use the following method instead. Download manually setuptools-0.6c8-py2.4.egg (or latest version, choose py2.4) and execute the command:

# sh setuptools-0.6c8-py2.4.egg

You can later update it with sudo easy_install-2.4 -U setuptools.

Now, the server is ready to install mod_wsgi. There is a package libapache2-mod-wsgi on Ubuntu 8.04, but it's the old 1.3 version. So we will build the latest mod_wsgi version. Please remove the libapache2-mod-wsgi package if you have previously installed it. We need to get the source directly from the download site and build it:

$ wget http://modwsgi.googlecode.com/files/mod_wsgi-2.1.tar.gz
$ tar xzf mod_wsgi-2.1.tar.gz
$ cd mod_wsgi-2.1
$ ./configure --with-python=/usr/bin/python2.4
$ make
$ sudo 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 to the /etc/apache2/mods-available/ directory.

The load declaration for the module needs to go on a file named wsgi.load (in /etc/apache2/mods-available/ directory), which contains only this:

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

The configuration directives reside in the file named wsgi.conf next to wsgi.load. We don't create it now, but it can be useful later to add directives in it if you have more than one WSGI application to serve.

Then you have to activate the wsgi module with:

# a2enmod wsgi

Note: a2enmod stands for "apache2 enable mod", this executable create the symlink for you. Actually a2enmod wsgi is equivalent to:

# cd /etc/apache2/mods-enabled
# ln -s ../mods-available/wsgi.load
# ln -s ../mods-available/wsgi.conf # if it exists

For apache 1.3 or apache 2 with an old directory layout, you may need to put the LoadModule line and the configuration directives you will see later inside the httpd.conf file in your apache's /etc directory. The soft links above will not be necessary in that case.

Repoze allows Grok to run behind any WSGI server. This tutorial will show how to install Grok behind the Apache web server and mod_wsgi using Repoze on a brand new Linux virtual server.

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:

$ sudo easy_install-2.4 virtualenv

$ virtualenv --no-site-packages ${sandbox}
$ cd ${sandbox}
$ . bin/activate

$ easy_install -i http://dist.repoze.org/grok/latest/simple repoze.grok

$ easy_install -b . -e -i http://dist.repoze.org/grok/latest/simple repoze.grok
$ cd repoze.grok
$ vi setup.py  # set GROK_VERSION = '0.13'
$ vi setup.cfg # comment easy_install section
$ python setup.py develop
$ cd ..

$ mkgrokinstance .

$ cp etc/sample-users.zcml etc/users.zcml

$ sudo cp etc/apache2.conf /etc/apache2/sites-available/grok

WSGIPythonHome ${sandbox}
WSGIDaemonProcess grok user=${youruser} group=${youruser} threads=1 processes=4 maximum-requests=10000 python-path=${sandbox}/lib/python2.4/site-packages
# python-eggs=/tmp/python-eggs
# please remove processes=4 if you don't use a ZEO server!

<VirtualHost *>
  ServerName my.machine.local
  WSGIScriptAlias /site ${sandbox}/bin/grok.wsgi
  WSGIProcessGroup grok
  WSGIPassAuthorization On
  WSGIReloadMechanism Process
  SetEnv HTTP_X_VHM_HOST http://my.machine.local/site
  SetEnv PASTE_CONFIG ${sandbox}/etc/grok.ini
</VirtualHost>

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

$ bin/zeoctl -C etc/zeo.conf start
. daemon process started, pid=7538

2008-07-28T15:32:06 INFO root daemon manager started
2008-07-28T15:32:06 INFO root spawned process pid=7538
2008-07-28T15:32:06 INFO root sleep 1 to avoid rapid restarts
2008-07-28T15:32:06 INFO root pid 7538: exit status 2; exiting now

$ bin/runzeo -C etc/zeo.conf

$ sudo a2ensite grok
$ sudo /etc/init.d/apache2 reload

$ sudo a2dissite grok
$ sudo /etc/init.d/apache2 reload

$ touch bin/grok.wsgi

# /etc/init.d/apache2 reload
# /etc/init.d/apache2 stop

$ bin/paster serve etc/grok.ini

$ bin/paster serve --reload etc/grok.ini

$ easy_install -U grokproject # to be sure we have the latest version (here 0.8)
$ grokproject --run-buildout=no helloworld
$ cd helloworld
$ python2.4 setup.py develop

<include package="helloworld" />