Running a Pyramid Application under mod_wsgiΒΆ

mod_wsgi is an Apache module developed by Graham Dumpleton. It allows WSGI programs to be served using the Apache web server.

This guide will outline broad steps that can be used to get a Pyramid application running under Apache via mod_wsgi. This particular tutorial was developed under Apple's Mac OS X platform (Snow Leopard, on a 32-bit Mac), but the instructions should be largely the same for all systems, delta specific path information for commands and files.

Note

Unfortunately these instructions almost certainly won't work for deploying a Pyramid application on a Windows system using mod_wsgi. If you have experience with Pyramid and mod_wsgi on Windows systems, please help us document this experience by submitting documentation to the Pylons-devel maillist.

  1. The tutorial assumes you have Apache already installed on your system. If you do not, install Apache 2.X for your platform in whatever manner makes sense.

  2. It is also assumed that you have satisfied the Requirements for Installing Packages.

  3. Once you have Apache installed, install mod_wsgi. Use the (excellent) installation instructions for your platform into your system's Apache installation.

  4. Create a Pyramid application. For this tutorial we'll use the starter cookiecutter. See Creating a Pyramid Project for more in-depth information about creating a new project.

    $ cd ~
    $ cookiecutter https://github.com/Pylons/pyramid-cookiecutter-starter
    

    If prompted for the first item, accept the default yes by hitting return.

    You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before.
    Is it okay to delete and re-clone it? [yes]: yes
    project_name [Pyramid Scaffold]: myproject
    repo_name [scaffold]: myproject
    Select template_language:
    1 - jinja2
    2 - chameleon
    3 - mako
    Choose from 1, 2, 3 [1]: 1
    
  5. Create a virtual environment which we'll use to install our application. It is important to use the same base Python interpreter that was used to build mod_wsgi. For example, if mod_wsgi was built against the system Python 3.x, then your project should use a virtual environment created from that same system Python 3.x.

    $ cd myproject
    $ python3 -m venv env
    
  6. Install your Pyramid application and its dependencies.

    $ env/bin/pip install -e .
    
  7. Within the project directory (~/myproject), create a script named pyramid.wsgi. Give it these contents:

    from pyramid.paster import get_app, setup_logging
    ini_path = '/Users/chrism/myproject/production.ini'
    setup_logging(ini_path)
    application = get_app(ini_path, 'main')
    

    The first argument to pyramid.paster.get_app() is the project configuration file name. It's best to use the production.ini file provided by your cookiecutter, as it contains settings appropriate for production. The second is the name of the section within the .ini file that should be loaded by mod_wsgi. The assignment to the name application is important: mod_wsgi requires finding such an assignment when it opens the file.

    The call to pyramid.paster.setup_logging() initializes the standard library's logging module to allow logging within your application. See Logging Configuration.

    There is no need to make the pyramid.wsgi script executable. However, you'll need to make sure that two users have access to change into the ~/myproject directory: your current user (mine is chrism and the user that Apache will run as often named apache or httpd). Make sure both of these users can "cd" into that directory.

  8. Edit your Apache configuration and add some stuff. I happened to create a file named /etc/apache2/other/modwsgi.conf on my own system while installing Apache, so this stuff went in there.

    # Use only 1 Python sub-interpreter.  Multiple sub-interpreters
    # play badly with C extensions.  See
    # http://stackoverflow.com/a/10558360/209039
    WSGIApplicationGroup %{GLOBAL}
    WSGIPassAuthorization On
    WSGIDaemonProcess pyramid user=chrism group=staff threads=4 \
       python-path=/Users/chrism/myproject/env/lib/python3.5/site-packages
    WSGIScriptAlias /myapp /Users/chrism/myproject/pyramid.wsgi
    
    <Directory /Users/chrism/myproject>
      WSGIProcessGroup pyramid
      Require all granted
    </Directory>
    
  9. Restart Apache

    $ sudo /usr/sbin/apachectl restart
    
  10. Visit http://localhost/myapp in a browser. You should see the sample application rendered in your browser.

mod_wsgi has many knobs and a great variety of deployment modes. This is just one representation of how you might use it to serve up a Pyramid application. See the mod_wsgi configuration documentation for more in-depth configuration information.