Monday, June 25, 2012

Setting up CherryPy using mod_wsgi on Mac OS X Snow Leopard

Getting CherryPy 3.2 setup on Snow Leopard with mod_wsgi is relatively easy. Here is a step-by-step guide.

A word of caution:

This tutorial requires you to modify sensitive system files on your computer. If you are uncomfortable doing this or unaware of the repercussions, take some time and do your due-diligence to understand the repercussions before following these steps or do not follow the steps outlined in this tutorial.

Step 1 (optional) - Download and install Python 2.7.3  

Python is installed on SnowLeopard by default, but it's an older version 2.6. If you want to use that, you can skip this section.

  • Download Python 2.7.3 from the Python standard releases page
  • Browse to the downloaded python-2.7.3-macosx10.6.dmg file in Finder
  • Double-click on it and follow the installation instruction

The Python standard release of 2.7.3 installs the python executable to the following location on your Mac by default:

Add the above location to your $PATH environment variable.

Python 2.7.3 should now be up-and-running. To test this, open a terminal and type:
        python -V

The following text should show up (If not, you may have your $PATH environment variable set incorrectly).:
        Python 2.7.3

Step 2 - Download and install mod_wsgi

There are a few ways to do this. If you are sticking with Python 2.6 that comes pre-installed on Snow Leopard, you can download and install the Snow Leopard binary. If you have macports or homebrew you can use one of those if you prefer. Here, I will demonstrate how to compile it from source. It's quick, easy and puts the resulting file in the same place as all of the other Apache mods.

To download and compile from source, open up a terminal and type the following commands (Hit the [return] key after each command, you will see output from some of them. Also, the terminal may ask for your password at some point):
cd ~/Downloads/
tar -zxvf mod_wsgi-3.3.tar.gz
cd mod_wsgi-3.3
sudo ./configure
sudo make
sudo make install
Now, you should have installed with your other Apache modules in /usr/libexec/apache2. To confirm this, keep the terminal open and type the command: ls /usr/libexec/apache2/ The terminal should print back the file path (if not, something went awry, try again): /usr/libexec/apache2/

Step 3 - Test mod_wsgi on Apache

You have downloaded mod_wsgi, now let's get Apache to load it.

First, you need to edit some of the Apache configuration files. FYI, you will need to make hidden files and folders visible if they aren't already.
  •  Tell Apache to load the file that you installed. Open the following file in your favorite text editor:Macintosh HD/private/etc/apache2/httpd.conf
  • Find the big list of lines that begin with LoadModule. After the last LoadModule line, add the following line and save the file. You will be prompted for your password when saving. (Note, if you used macports or homebrew to install mod_wsgi, the location of will be different):LoadModule wsgi_module  libexec/apache2/
  • Now, create a VirtualHost in Apache. Open up the following file in your favorite text editor: Macintosh HD/private/etc/apache2/extra/httpd-vhosts.conf  
  • Add the following lines to the bottom of the file and save it: <VirtualHost *:80>
        ServerAdmin me@test-cherry-py
        ServerName test-cherrypy

        DocumentRoot "/Library/WebServer/test-cherrypy/documents"
        <Directory "/Library/WebServer/test-cherrypy/documents">
            Options Indexes FollowSymLinks Includes
            AllowOverride All
            Order allow,deny
            Allow from all

        WSGIScriptAlias / /Library/WebServer/test-cherrypy/wsgi-scripts/

        <Directory "/Library/WebServer/test-cherrypy/wsgi-scripts">
            Order allow,deny
            Allow from all
In the above VirtualHost code-block, you told Apache to answer to the domain name test-cherrypy, and to look for files and folders that probably don't exist on your machine yet. Let's get your machine set up so that Apache can find these files, directories and the domain name.

  • Fake the domain name. In Finder, open up the file Macintosh HD/etc/hosts in your favorite text editor and add the following line to the end of the file:     test-cherrypy
  • Create the directories and files that your VirtualHost directive above refers to. Go to the terminal and type the following commands (hit [return] after each command):
    cd /Library/Webserver
    sudo mkdir test-cherrypy
    sudo mkdir test-cherrypy/documents
    sudo mkdir test-cherrypy/wsgi-scripts
    sudo touch test-cherrypy/wsgi-scripts/
  • In Finder, open up the following file in your favorite text editor: Macintosh HD/Library/Webserver/test-cherrypy/wsgi-scripts/
  • It should be empty. Add the following lines of code to the file and save it: def application(environ, start_response):
        status = '200 OK'
        output = 'Hello, from mod_wsgi!'

        response_headers = [('Content-type', 'text/plain'),
                            ('Content-Length', str(len(output)))]
        start_response(status, response_headers)

        return [output]
Now, go to the Apple menu and open up System Preferences > Sharing  and uncheck and re-check the Web Sharing checkbox. This will restart Apache. Alternatively, you could type the following in the terminal:sudo apachectl restart
Open up your favorite browser and go to http://test-cherrypy. You should be greeted with the following text:
Hello, from mod_wsgi!

Step 4 - Download and install CherryPy 3.2.2

So, you have mod_wsgi working, now let's hook CherryPy up to it. Download and install CherryPy 3.2.2. Open up your terminal and type the following commands: cd ~/Downloads
tar -zxvf CherryPy-3.2.2.tar.gz
cd CherryPy-3.2.2
python install
You now have CherryPy installed! Let's hook it up to your Apache VirtualHost and try it out.
  • Open up the following file in your favorite text editor:
    Macintosh HD/Library/Webserver/test-cherrypy/wsgi-scripts/
  • Replace the contents of the file with the following code: import sys
    sys.stdout = sys.stderr

    import atexit
    import threading
    import cherrypy

    cherrypy.config.update({'environment': 'embedded'})

    if cherrypy.__version__.startswith('3.0') and cherrypy.engine.state == 0:

    class Root(object):
        def index(self):
            return 'Hello, from CherryPy!' = True

    application = cherrypy.Application(Root(), script_name=None, config=None)
Open up your favorite browser and go to http://test-cherrypy. You should be greeted with the following text:
Hello, from CherryPy!

Congratulations, you have successfully connected CherryPy to Apache on Snow Leopard using mod_wsgi!

1 comment:

  1. Daniel, you should update for Yosemite, Python 3, ...