201 lines
7.0 KiB
Plaintext
201 lines
7.0 KiB
Plaintext
=================================
|
|
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.
|
|
|
|
.. _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
|
|
PythonDebug On
|
|
</Location>
|
|
|
|
...and replace ``myproject.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.
|
|
|
|
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 myproject.settings
|
|
</VirtualHost>
|
|
|
|
<VirtualHost *>
|
|
ServerName www2.example.com
|
|
# ...
|
|
SetEnv DJANGO_SETTINGS_MODULE myproject.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 myproject.settings
|
|
PythonInterpreter myproject
|
|
</Location>
|
|
|
|
<Location "/otherthing">
|
|
SetEnv DJANGO_SETTINGS_MODULE myproject.other_settings
|
|
PythonInterpreter myproject_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 myproject.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 document
|
|
root.
|
|
|
|
Error handling
|
|
==============
|
|
|
|
When you use Apache/mod_python, errors will be caught by Django -- in other
|
|
words, they won't propogate 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.)
|