django/docs/modpython.txt

=================================
How to use Django with mod_python
=================================

`Apache`_ with `mod_python`_ currently is the preferred setup for using Django
on a production server.

mod_python is similar to `mod_perl`_ : It embeds Python within Apache and loads
Python code into memory when the server starts. Code stays in memory throughout
the life of an Apache process, which leads to significant performance gains over
other server arrangements.

.. _Apache: http://httpd.apache.org/
.. _mod_python: http://www.modpython.org/
.. _mod_perl: http://perl.apache.org/

Basic configuration
===================

To configure Django with mod_python, first make sure you have Apache installed,
with the mod_python module activated.

Then edit your ``httpd.conf`` file and add the following::

    <Location "/mysite/">
        SetHandler python-program
        PythonHandler django.core.handlers.modpython
        SetEnv DJANGO_SETTINGS_MODULE myproject.settings.main
        PythonDebug On
    </Location>

...and replace ``myproject.settings.main`` with the Python path to your
settings file.

This tells Apache: "Use mod_python for any URL at or under '/mysite/', using the
Django mod_python handler." It passes the value of ``DJANGO_SETTINGS_MODULE``
so mod_python knows which settings to use.

Also, if you've manually altered your ``PYTHONPATH`` to put your Django project
on it, you'll need to tell mod_python::

    PythonPath "['/path/to/project'] + sys.path"

You can also add directives such as ``PythonAutoReload Off`` for performance.
See the `mod_python documentation`_ for a full list of options.

Note that you should set ``PythonDebug Off`` on a production server. If you
leave ``PythonDebug On``, your users would see ugly (and revealing) Python
tracebacks if something goes wrong within mod_python.

Restart Apache, and any request to /mysite/ or below will be served by Django.
Note that Django's URLconfs won't trim the "/mysite/" -- they get passed the
full URL.

When deploying Django sites on mod_python, you'll need to restart Apache each
time you make changes to your Python code.

Here's a template for an admin configuration::

    <Location "/admin/">
        SetHandler python-program
        PythonHandler django.core.handlers.modpython
        SetEnv DJANGO_SETTINGS_MODULE myproject.settings.admin
        PythonDebug On
    </Location>

The only thing different here is the ``DJANGO_SETTINGS_MODULE``.

Multiple Django installations on the same Apache
================================================

It's entirely possible to run multiple Django installations on the same Apache
instance. Just use ``VirtualHost`` for that, like so::

    NameVirtualHost *

    <VirtualHost *>
        ServerName www.example.com
        # ...
        SetEnv DJANGO_SETTINGS_MODULE myproject.settings.main
    </VirtualHost>

    <VirtualHost *>
        ServerName admin.example.com
        # ...
        SetEnv DJANGO_SETTINGS_MODULE myproject.settings.admin
    </VirtualHost>

If you need to put two Django installations within the same ``VirtualHost``,
you'll need to take a special precaution to ensure mod_python's cache doesn't
mess things up. Use the ``PythonInterpreter`` directive to give different
``<Location>`` directives separate interpreters::

    <VirtualHost *>
        ServerName www.example.com
        # ...
        <Location "/something">
            SetEnv DJANGO_SETTINGS_MODULE myproject.settings.main
            PythonInterpreter myproject_main
        </Location>

        <Location "/admin">
            SetEnv DJANGO_SETTINGS_MODULE myproject.settings.admin
            PythonInterpreter myproject_admin
        </Location>
    </VirtualHost>

The values of ``PythonInterpreter`` don't really matter, as long as they're
different between the two ``Location`` blocks.

Running a development server with mod_python
============================================

If you use mod_python for your development server, you can avoid the hassle of
having to restart the server each time you make code changes. Just set
``MaxRequestsPerChild 1`` in your ``httpd.conf`` file to force Apache to reload
everything for each request. But don't do that on a production server, or we'll
revoke your Django privileges.

.. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html

Serving media files
===================

Django doesn't serve media files itself. It'd be inefficient to flow media
files through a (relatively) complex framework when much, much more well-tuned
solutions are better.

We recommend using a separate Web server for serving media. Here are some good
choices:

* lighttpd_
* TUX_
* A stripped-down version of Apache_

If, however, you have no option but to serve media files on the same Apache
``VirtualHost`` as Django, here's how you can turn off mod_python for a
particular part of the site::

    <Location "/media/">
        SetHandler None
    </Location>

Just change ``Location`` to the root URL of your media 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.

.. _lighttpd: http://www.lighttpd.net/
.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
.. _Apache: http://httpd.apache.org/