Django includes built-in support for WSGI, but in order to deploy our Django projects under mod_wsgi, we need to write a simple WSGI script. This is just some Python code that sets up our environment and kicks off Django's WSGI handler. Here is an example script file, called django.wsgi:

import os
import sys

os.environ['DJANGO_SETTINGS_MODULE'] = 'coleman.settings' sys.path.append('/home/jesse/src/my-site-packages')
import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()

Specifying our settings module manually is required in all cases (it's a Django requirement). We can also modify the value of sys.path, if needed, to include our Django or other Python packages. The WSGI script will run under mod_wsgi and will therefore not receive any additions to the $PYTHONPATH environment variable we might use in our local, command-line development environment.

Once we've put together our WSGI script, we need to write an Apache configuration file. The primary Apache directive to know is WSGIScriptAlias. This is similar to the more common ScriptAlias directive. An example VirtualHost configuration appears below:

<VirtualHost *:80>
ServerName coleman.localhost
WSGIScriptAlias / /Users/jesse/src/coleman/apache/django.wsgi

<Directory /Users/jesse/src/coleman/apache>
Order deny,allow
Allow from all
</Directory>
Alias /media/ /Users/jesse/src/coleman/media/
<Directory /Users/jesse/src/coleman/media>
Order deny,allow
Allow from all
</Directory>
</VirtualHost>

By default, this configuration uses mod_wsgi in embedded mode. For development or testing purposes this may not make much of a difference, but as we mentioned earlier, it is generally recommended to use daemon mode for any WSGI application, unless you're willing and able to tune Apache yourself. To enable daemon mode, we use the WSGIDaemonProcess and WSGIProcessGroup directives:

<VirtualHost *:80>
WSGIDaemonProcess book-site user=jesse threads=25
WSGIProcessGroup book-site
ServerName coleman.localhost
WSGIScriptAlias / /Users/jesse/src/coleman/apache/django.wsgi

<Directory /Users/jesse/src/coleman/apache>
  Order deny,allow
  Allow from all
</Directory>

Alias /media/ /Users/jesse/src/coleman/media/

<Directory /Users/jesse/src/coleman/media>
  Order deny,allow
  Allow from all
</Directory>
</VirtualHost>

The addition of these two directives changes things quite significantly. Let's examine WSGIDaemonProcess first.

The WSGIDaemonProcess directive activates mod_wsgi's daemon mode. The first parameter, which is required, is a unique name that will be assigned to the WSGI daemon process. The remaining options are not required, but fine tune mod_wsgi's mechanisms. The above example uses two options. The first, user, specifies the user account that our WSGI process will run under. The second, threads, specifies how many threads to initiate in this process.

WSGIDaemonProcess supports establishing multiple processes as well, using the processes option. Use of this option in combination with threads will control how many total request handlers will be available for your WSGI application. The default number of threads is 15, so using processes=2 would spawn 30 total request handlers. These options are tunable and depend a lot on your specific application, server, hardware, and so on.

The WSGIDaemonProcess directive simply creates a WSGI process according to our desired options. To assign this process to a specific WSGI application, we need to use WSGIProcessGroup. This directive can occur in our top-level Apache configuration or within a VirtualHost context. It our example case, the WSGI application defined for the virtual host will be assigned to the WSGI process named book-site. A WSGI application can be bound to any WSGI process defined in the server or virtual host. In addition, multiple applications can be assigned to the same process in this same manner.

Whole books are dedicated to Apache configuration and the mod_wsgi site alone includes dozens of wiki pages with details and discussion about the module's use. In general, most applications will not need much more than a simple, straightforward configuration. It is important to understand the basics, however, because as your application grows, it could become important.

An issue that arises in our configuration above is thread-safety. Considerable debate has followed the development of Django in regards to this topic, but as of most recent releases, the framework is generally considered to be thread-safe. This means it is reasonable to run Django applications using multi-threaded WSGI processes or under a multi-threaded web server (for example, Apache's 'worker' MPM).

Undiscovered threading bugs are always possible, albeit unlikely. More important, however, is to consider the implications of your own application code and how it works in a multi-threaded environment. Typically this sort of problem can be introduced when trying to use shared, global variables between threads in your application code. Particularly important is the fact that Django QuerySet objects are not thread-safe. They attempt to share a global QuerySet instance in application code between threads, which will have unpredictable results.

We should also mention that versions of Django prior to 1.0 had known thread-safety problems. If you're running an earlier Django version, for code compatibility reasons perhaps, you could potentially encounter threading bugs when running under Apache's worker MPM, multi-threaded WSGI processes, any Apache server running on the Windows operating system, or any other multi-threaded environment.