==========================================
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 = '/path/to/mysite'
    if path not in sys.path:
        sys.path.append(path)

just below the ``import sys`` line to place your project on the path. Remember to
replace 'mysite.settings' with your correct settings file, and '/path/to/mysite'
with your own project's location.

.. _serving-media-files:

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

.. _serving-the-admin-files:

Serving the admin files
=======================

Note that the Django development server automagically serves admin media files,
but this is not the case when you use any other server arrangement. You're
responsible for setting up Apache, or whichever media server you're using, to
serve the admin files.

The admin files live in (:file:`django/contrib/admin/media`) of the Django
distribution.

Here are two recommended approaches:

    1. Create a symbolic link to the admin media files from within your
       document root. This way, all of your Django-related files -- code **and**
       templates -- stay in one place, and you'll still be able to ``svn
       update`` your code to get the latest admin templates, if they change.

    2. Or, copy the admin media files so that they live within your Apache
       document root.

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