==========================================

How to use Django with Apache and mod_wsgi

==========================================

Deploying Django with Apache_ and `mod_wsgi`_ is the recommended way to get

Django into production.

.. _Apache: http://httpd.apache.org/

.. _mod_wsgi: http://code.google.com/p/modwsgi/

mod_wsgi is an Apache module which can be used to host any Python application

which supports the `Python WSGI interface`_, including Django. Django will work

with any version of Apache which supports mod_wsgi.

.. _python wsgi interface: http://www.python.org/dev/peps/pep-0333/

The `official mod_wsgi documentation`_ is fantastic; it's your source for all

the details about how to use mod_wsgi. You'll probably want to start with the

`installation and configuration documentation`_.

.. _official mod_wsgi documentation: http://code.google.com/p/modwsgi/

.. _installation and configuration documentation: http://code.google.com/p/modwsgi/wiki/InstallationInstructions

Basic Configuration

===================

Once you've got mod_wsgi installed and activated, edit your ``httpd.conf`` file

and add::

    WSGIScriptAlias / /path/to/mysite/apache/django.wsgi

The first bit above is the url you want to be serving your application at (``/``

indicates the root url), and the second is the location of a "WSGI file" -- see

below -- on your system, usually inside of your project. This tells Apache

to serve any request below the given URL using the WSGI application defined by that file.

Next we'll need to actually create this WSGI application, so create the file

mentioned in the second part of ``WSGIScriptAlias`` and add::

    import os

    import sys

    os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'

    import django.core.handlers.wsgi

    application = django.core.handlers.wsgi.WSGIHandler()

If your project is not on your ``PYTHONPATH`` by default you can add::

    path = '/usr/local/django'

    if path not in sys.path:

        sys.path.append(path)

just above the final ``import`` line to place your project on the path. Remember to

replace 'mysite.settings' with your correct settings file, and '/usr/local/django'

with your own project's location.

Serving media files

===================

Django doesn't serve media files itself; it leaves that job to whichever Web

server you choose.

We recommend using a separate Web server -- i.e., one that's not also running

Django -- for serving media. Here are some good choices:

    * lighttpd_

    * Nginx_

    * TUX_

    * A stripped-down version of Apache_

    * Cherokee_

If, however, you have no option but to serve media files on the same Apache

``VirtualHost`` as Django, you can set up Apache to serve some URLs as

static media, and others using the mod_wsgi interface to Django.

This example sets up Django at the site root, but explicitly serves ``robots.txt``,

``favicon.ico``, any CSS file, and anything in the ``/media/`` URL space as a static

file. All other URLs will be served using mod_wsgi::

    Alias /robots.txt /usr/local/wsgi/static/robots.txt

    Alias /favicon.ico /usr/local/wsgi/static/favicon.ico

    AliasMatch /([^/]*\.css) /usr/local/wsgi/static/styles/$1

    Alias /media/ /usr/local/wsgi/static/media/

    <Directory /usr/local/wsgi/static>

    Order deny,allow

    Allow from all

    </Directory>

    WSGIScriptAlias / /usr/local/wsgi/scripts/django.wsgi

    <Directory /usr/local/wsgi/scripts>

    Order allow,deny

    Allow from all

    </Directory>

.. _lighttpd: http://www.lighttpd.net/

.. _Nginx: http://wiki.nginx.org/Main

.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server

.. _Apache: http://httpd.apache.org/

.. _Cherokee: http://www.cherokee-project.com/

More details on configuring a mod_wsgi site to serve static files can be found

in the mod_wsgi documentation on `hosting static files`_.

.. _hosting static files: http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#Hosting_Of_Static_Files

Details

=======

For more details, see the `mod_wsgi documentation on Django integration`_,

which explains the above in more detail, and walks through all the various

options you've got when deploying under mod_wsgi.

.. _mod_wsgi documentation on Django integration: http://code.google.com/p/modwsgi/wiki/IntegrationWithDjango