+
−=================================
+
−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.
+
−
+
−Django requires Apache 2.x and mod_python 3.x, and you should use Apache's
+
−`prefork MPM`_, as opposed to the `worker MPM`_.
+
−
+
−You may also be interested in `How to use Django with 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
+
−.. _How to use Django with FastCGI: ../fastcgi/
+
−
+
−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
+
−        PythonDebug On
+
−    </Location>
+
−
+
−...and replace ``mysite.settings`` 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.
+
−
+
−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 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.
+
−
+
−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``,
+
−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 mysite_other
+
−        </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 ``print`` statements have no effect in mod_python; they
+
−don't appear in the Apache log, as one might expect. If you have the need to
+
−print debugging information in a mod_python setup, either do this::
+
−
+
−    assert False, the_value_i_want_to_see
+
−
+
−Or add the debugging information to the template of your page.
+
−
+
−.. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html
+
−
+
−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_
+
−* 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. 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/
+
−.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
+
−.. _Apache: http://httpd.apache.org/
+
−
+
−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 (``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.
+
−
+
−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/articles/modpython-006.html
+
−.. _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/articles/modpython-001.html