==========================================
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 described in :pep:`3333`, including
Django. Django will work with any version of Apache which supports mod_wsgi.

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-files:

Serving files
=============

Django doesn't serve 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
``/static/`` and ``/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/media/
    Alias /static/ /usr/local/wsgi/static/

    <Directory /usr/local/wsgi/static>
    Order deny,allow
    Allow from all
    </Directory>

    <Directory /usr/local/wsgi/media>
    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 the static files
of the admin app, 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/static/admin`) of the
Django distribution.

We **strongly** recommend using :mod:`django.contrib.staticfiles` to handle
the admin files, but here are two other approaches:

1. Create a symbolic link to the admin static files from within your
   document root.

2. Or, copy the admin static 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