.. _howto-deployment-modpython:

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

How to use Django with Apache and mod_python

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

.. warning::

    Support for mod_python will be deprecated in a future release of Django. If

    you are configuring a new deployment, you are strongly encouraged to

    consider using :doc:`mod_wsgi </howto/deployment/modwsgi>` or any of the

    other :doc:`supported backends </howto/deployment/index>`.

.. highlight:: apache

The `mod_python`_ module for Apache_ can be used to deploy Django to a

production server, although it has been mostly superseded by the simpler

:doc:`mod_wsgi deployment option </howto/deployment/modwsgi>`.

mod_python is similar to (and inspired by) `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.

Django requires Apache 2.x and mod_python 3.x, and you should use Apache's

`prefork MPM`_, as opposed to the `worker MPM`_.

.. seealso::

    * Apache is a big, complex animal, and this document only scratches the

      surface of what Apache can do. If you need more advanced information about

      Apache, there's no better source than `Apache's own official

      documentation`_

    * You may also be interested in :doc:`How to use Django with FastCGI, SCGI,

      or AJP </howto/deployment/fastcgi>`.

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

.. _mod_python: http://www.modpython.org/

.. _mod_perl: http://perl.apache.org/

.. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html

.. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html

.. _apache's own official documentation: http://httpd.apache.org/docs/

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 mysite.settings

        PythonOption django.root /mysite

        PythonDebug On

    </Location>

...and replace ``mysite.settings`` with the Python import path to your Django

project's 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 :ref:`DJANGO_SETTINGS_MODULE

<django-settings-module>` so mod_python knows which settings to use.

.. versionadded:: 1.0

    The ``PythonOption django.root ...`` is new in this version.

Because mod_python does not know we are serving this site from underneath the

``/mysite/`` prefix, this value needs to be passed through to the mod_python

handler in Django, via the ``PythonOption django.root ...`` line. The value set

on that line (the last item) should match the string given in the ``<Location

...>`` directive. The effect of this is that Django will automatically strip the

``/mysite`` string from the front of any URLs before matching them against your

URLconf patterns. If you later move your site to live under ``/mysite2``, you

will not have to change anything except the ``django.root`` option in the config

file.

When using ``django.root`` you should make sure that what's left, after the

prefix has been removed, begins with a slash. Your URLconf patterns that are

expecting an initial slash will then work correctly. In the above example,

since we want to send things like ``/mysite/admin/`` to ``/admin/``, we need

to remove the string ``/mysite`` from the beginning, so that is the

``django.root`` value. It would be an error to use ``/mysite/`` (with a

trailing slash) in this case.

Note that we're using the ``<Location>`` directive, not the ``<Directory>``

directive. The latter is used for pointing at places on your filesystem,

whereas ``<Location>`` points at places in the URL structure of a Web site.

``<Directory>`` would be meaningless here.

Also, if your Django project is not on the default ``PYTHONPATH`` for your

computer, you'll have to tell mod_python where your project can be found:

.. parsed-literal::

    <Location "/mysite/">

        SetHandler python-program

        PythonHandler django.core.handlers.modpython

        SetEnv DJANGO_SETTINGS_MODULE mysite.settings

        PythonOption django.root /mysite

        PythonDebug On

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

    </Location>

The value you use for ``PythonPath`` should include the parent directories of

all the modules you are going to import in your application. It should also

include the parent directory of the :ref:`DJANGO_SETTINGS_MODULE

<django-settings-module>` location. This is exactly the same situation as

setting the Python path for interactive usage. Whenever you try to import

something, Python will run through all the directories in ``sys.path`` in turn,

from first to last, and try to import from each directory until one succeeds.

Make sure that your Python source files' permissions are set such that the

Apache user (usually named ``apache`` or ``httpd`` on most systems) will have

read access to the files.

An example might make this clearer. Suppose you have some applications under

``/usr/local/django-apps/`` (for example, ``/usr/local/django-apps/weblog/`` and

so forth), your settings file is at ``/var/www/mysite/settings.py`` and you have

specified :ref:`DJANGO_SETTINGS_MODULE <django-settings-module>` as in the above

example. In this case, you would need to write your ``PythonPath`` directive

as::

    PythonPath "['/usr/local/django-apps/', '/var/www'] + sys.path"

With this path, ``import weblog`` and ``import mysite.settings`` will both

work. If you had ``import blogroll`` in your code somewhere and ``blogroll``

lived under the ``weblog/`` directory, you would *also* need to add

``/usr/local/django-apps/weblog/`` to your ``PythonPath``. Remember: the

**parent directories** of anything you import directly must be on the Python

path.

.. note::

    If you're using Windows, we still recommended that you use forward

    slashes in the pathnames, even though Windows normally uses the backslash

    character as its native separator. Apache knows how to convert from the

    forward slash format to the native format, so this approach is portable and

    easier to read. (It avoids tricky problems with having to double-escape

    backslashes.)

    This is valid even on a Windows system::

        PythonPath "['c:/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.

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

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 mysite.settings

    </VirtualHost>

    <VirtualHost *>

        ServerName www2.example.com

        # ...

        SetEnv DJANGO_SETTINGS_MODULE mysite.other_settings

    </VirtualHost>

If you need to put two Django installations within the same ``VirtualHost``

(or in different ``VirtualHost`` blocks that share the same server name),

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 mysite.settings

            PythonInterpreter mysite

        </Location>

        <Location "/otherthing">

            SetEnv DJANGO_SETTINGS_MODULE mysite.other_settings

            PythonInterpreter othersite

        </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.

If you're the type of programmer who debugs using scattered ``print``

statements, note that output to ``stdout`` will not appear in the Apache

log and can even `cause response errors`_.

.. _cause response errors: http://blog.dscpl.com.au/2009/04/wsgi-and-printing-to-standard-output.html

If you have the need to print debugging information in a mod_python setup, you

have a few options. You can print to ``stderr`` explicitly, like so::

    print >> sys.stderr, 'debug text'

    sys.stderr.flush()

(note that ``stderr`` is buffered, so calling ``flush`` is necessary if you wish

debugging information to be displayed promptly.)

A more compact approach is to use an assertion::

    assert False, 'debug text'

Another alternative is to add debugging information to the template of your page.

.. _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, 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. You can also use

``<LocationMatch>`` to match a regular expression.

This example sets up Django at the site root but explicitly disables Django for

the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or

``.png``::

    <Location "/">

        SetHandler python-program

        PythonHandler django.core.handlers.modpython

        SetEnv DJANGO_SETTINGS_MODULE mysite.settings

    </Location>

    <Location "/media">

        SetHandler None

    </Location>

    <LocationMatch "\.(jpg|gif|png)$">

        SetHandler None

    </LocationMatch>

.. _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/

.. _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.

Using "eggs" with mod_python

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

If you installed Django from a Python egg_ or are using eggs in your Django

project, some extra configuration is required. Create an extra file in your

project (or somewhere else) that contains something like the following:

.. code-block:: python

    import os

    os.environ['PYTHON_EGG_CACHE'] = '/some/directory'

Here, ``/some/directory`` is a directory that the Apache Web server process can

write to. It will be used as the location for any unpacking of code the eggs

need to do.

Then you have to tell mod_python to import this file before doing anything

else. This is done using the PythonImport_ directive to mod_python. You need

to ensure that you have specified the ``PythonInterpreter`` directive to

mod_python as described above__ (you need to do this even if you aren't

serving multiple installations in this case). Then add the ``PythonImport``

line in the main server configuration (i.e., outside the ``Location`` or

``VirtualHost`` sections). For example::

    PythonInterpreter my_django

    PythonImport /path/to/my/project/file.py my_django

Note that you can use an absolute path here (or a normal dotted import path),

as described in the `mod_python manual`_. We use an absolute path in the

above example because if any Python path modifications are required to access

your project, they will not have been done at the time the ``PythonImport``

line is processed.

.. _Egg: http://peak.telecommunity.com/DevCenter/PythonEggs

.. _PythonImport: http://www.modpython.org/live/current/doc-html/dir-other-pimp.html

.. _mod_python manual: PythonImport_

__ `Multiple Django installations on the same Apache`_

Error handling

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

When you use Apache/mod_python, errors will be caught by Django -- in other

words, they won't propagate to the Apache level and won't appear in the Apache

``error_log``.

The exception for this is if something is really wonky in your Django setup. In

that case, you'll see an "Internal Server Error" page in your browser and the

full Python traceback in your Apache ``error_log`` file. The ``error_log``

traceback is spread over multiple lines. (Yes, this is ugly and rather hard to

read, but it's how mod_python does things.)

If you get a segmentation fault

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

If Apache causes a segmentation fault, there are two probable causes, neither

of which has to do with Django itself.

    1. It may be because your Python code is importing the "pyexpat" module,

       which may conflict with the version embedded in Apache. For full

       information, see `Expat Causing Apache Crash`_.

    2. It may be because you're running mod_python and mod_php in the same

       Apache instance, with MySQL as your database backend. In some cases,

       this causes a known mod_python issue due to version conflicts in PHP and

       the Python MySQL backend. There's full information in the

       `mod_python FAQ entry`_.

If you continue to have problems setting up mod_python, a good thing to do is

get a barebones mod_python site working, without the Django framework. This is

an easy way to isolate mod_python-specific problems. `Getting mod_python Working`_

details this procedure.

The next step should be to edit your test code and add an import of any

Django-specific code you're using -- your views, your models, your URLconf,

your RSS configuration, etc. Put these imports in your test handler function

and access your test URL in a browser. If this causes a crash, you've confirmed

it's the importing of Django code that causes the problem. Gradually reduce the

set of imports until it stops crashing, so as to find the specific module that

causes the problem. Drop down further into modules and look into their imports,

as necessary.

.. _Expat Causing Apache Crash: http://www.dscpl.com.au/wiki/ModPython/Articles/ExpatCausingApacheCrash

.. _mod_python FAQ entry: http://modpython.org/FAQ/faqw.py?req=show&file=faq02.013.htp

.. _Getting mod_python Working: http://www.dscpl.com.au/wiki/ModPython/Articles/GettingModPythonWorking

If you get a UnicodeEncodeError

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

If you're taking advantage of the internationalization features of Django (see

:doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must

ensure that the environment used to start Apache is configured to accept

non-ASCII file names. If your environment is not correctly configured, you

will trigger ``UnicodeEncodeError`` exceptions when calling functions like

``os.path()`` on filenames that contain non-ASCII characters.

To avoid these problems, the environment used to start Apache should contain

settings analogous to the following::

    export LANG='en_US.UTF-8'

    export LC_ALL='en_US.UTF-8'

Consult the documentation for your operating system for the appropriate syntax

and location to put these configuration items; ``/etc/apache2/envvars`` is a

common location on Unix platforms. Once you have added these statements

to your environment, restart Apache.