Running CherryPy behind Apache using mod_python

This is a HOWTO. See BehindApache for a higher-level discussion.

CherryPy 3 comes with a builtin mod_python adapter. An alternative that uses WSGI can be found at: http://projects.amor.org/misc/wiki/ModPythonGateway. This HOWTO discusses the builtin module.

Basic usage (but see DeployTemplate for better debugging support):

myapp.py

import cherrypy

class Root:
    @cherrypy.expose
    def index(self):
        return 'Hi there, Ho there, Hey there'

def setup_server():
    # Set up site-wide config. Do this first so that,
    # if something goes wrong, we get a log.
    cherrypy.config.update({'environment': 'production',
                            'log.screen': False,
                            'log.error_file': 'site.log',
                            'show_tracebacks': False})
    
    cherrypy.tree.mount(Root())
    # You must start the engine in a non-blocking fashion
    # so that mod_python can proceed
    cherrypy.engine.start(blocking=False)

httpd.conf:

DocumentRoot "/"
Listen 8080
LoadModule python_module /usr/lib/apache2/modules/mod_python.so

<Location "/">
    PythonPath "sys.path+['/path/to/my/application']"
    SetHandler python-program
    PythonHandler cherrypy._cpmodpy::handler
    PythonOption cherrypy.setup myapp::setup_server
    PythonDebug On
</Location> 

The actual path to your mod_python.so is dependent on your environment. In this case we suppose a global mod_python installation on a Linux distribution such as Ubuntu.

We do set the PythonPath configuration setting so that your application can be found by from the user running the apache2 instance. Of course if your application resides in the global site-packages folder this won't be needed.

Then restart apache2 and access http://localhost:8080.

Signal handling

If you encounter "Unrecoverable error in the server" or, with logging turned on, an error which seems related to threads and signals, then try adding the following lines to your cherrypy module before the engine is started:

cherrypy.engine.SIGHUP = None
cherrypy.engine.SIGTERM = None

This turns off the builtin signal handlers, which can interact in strange ways with the Apache process.