Running Kitsune with mod_wsgi


This section of documentation may be outdated.



Setting up Kitsune to run as a WSGI application is fairly straightforward. You will need to install the requirements as described in the installation chapter.

There are 3 steps once Kitsune is installed:

  • Set the document root.

  • Set up aliases.

  • Some file permissions.

  • Set up WSGI itself.

Apache Modules

Most of the Apache modules are part of a default Apache install, but may need to be activated. If they aren’t installed, all of them, including mod_wsgi should be installable via your favorite package manager.

WSGI Configuration

In the Apache config (or <VirtualHost>) you will need the following:

Note that values may be slightly different.

DocumentRoot /path/to/kitsune/webroot/

<Directory "/path/to/kitsune/webroot/">
    Options +FollowSymLinks

Alias /media/ "/path/to/kitsune/media/"
Alias /admin-media/ \

WSGISocketPrefix /var/run/wsgi

WSGIDaemonProcess kitsune processes=8 threads=1 \
WSGIProcessGroup kitsune

WSGIScriptAlias /k "/path/to/kitsune/wsgi/kitsune.wsgi"

May or may not be necessary. It was for me.


processes should be set to the number of cores. threads should probably be left at 1. maximum-requests is good at between 4000 and 10000.


Will make Kitsune accessible from http://domain/k, and we use rewrites in webroot/.htaccess to hide the /k. This will change soon, and the .htaccess file won’t be necessary.

The Alias directives let Kitsune access its CSS, JS, and images through Apache, reducing the load on Django.


Most of our kitsune/ is under version control, but can be overridden in a file called kitsune/ You can see example settings in the Development Setup.

File Permissions

To upload files, the webserver needs write access to media/uploads and all its subdirectories. The directories we currently use are:


media/uploads and its subdirectories should never be added to version control, as they are installation-/content-specific.

Product Details JSON

Some people have issues with django-mozilla-product-details and file permissions. The management command update_product_details writes a number of JSON files to disk, and the webserver then needs to read them.

If you get file system errors from product_details, make sure the files are readable by the webserver (should be by default) and the directory is readable and executable.

By default, product_details stores the JSON files in:


This is configurable. If you have multiple web servers, they should share this data. You can set the PROD_DETAILS_DIR variable in kitsune/ to a different path, for example on NFS.


Debugging via WSGI is a little more interesting than via the dev server. One key difference is that you cannot use pdb. Writing to stdout is not allowed within the WSGI process, and will result in a Internal Server Error.

There are three relevant cases for debugging via WSGI (by which I mean, where to find stack traces):

Apache Error Page

So you’ve got a really bad error and you aren’t even seeing the Kitsune error page! This is usually caused by an uncaught exception during the WSGI application start-up. Our WSGI script, located in wsgi/kitsune.wsgi, tries to run all the initial validation that the dev server runs, to catch these errors early.

So where is the stack trace? You’ll need to look in your Apache error logs. Where these are is OS-dependent, but a good place to look is /var/log/httpd. If you are using SSL, also check the SSL VirtualHost’s logs, for example /var/log/httpd/ssl_error_log.

With DEBUG=True

With DEBUG = True in your kitsune/, you will see a stack trace in the browser on error. Problem solved!

With DEBUG=False

With DEBUG = False in your kitsune/, you’ll see our Server Error message. You can still get stack traces, though, by setting the ADMINS variable in kitsune/

    ('me', 'my@email.address'),

Django will email you the stack trace. Provided you’ve set up email.

Reloading WSGI

WSGI keeps Python and Kitsune running in an isolated process. That means code changes aren’t automatically reflected on the server. In most default configurations of mod_wsgi, you can simply do this:

touch wsgi/kitsune.wsgi

That will cause the WSGI process to reload.