1 =================================
2 How to use Django with mod_python
3 =================================
5 Apache_ with `mod_python`_ currently is the preferred setup for using Django
6 on a production server.
8 mod_python is similar to `mod_perl`_ : It embeds Python within Apache and loads
9 Python code into memory when the server starts. Code stays in memory throughout
10 the life of an Apache process, which leads to significant performance gains over
11 other server arrangements.
13 Django requires Apache 2.x and mod_python 3.x, and you should use Apache's
14 `prefork MPM`_, as opposed to the `worker MPM`_.
16 You may also be interested in `How to use Django with FastCGI, SCGI or AJP`_
17 (which also covers SCGI and AJP).
19 .. _Apache: http://httpd.apache.org/
20 .. _mod_python: http://www.modpython.org/
21 .. _mod_perl: http://perl.apache.org/
22 .. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html
23 .. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html
24 .. _How to use Django with FastCGI, SCGI or AJP: ../fastcgi/
29 To configure Django with mod_python, first make sure you have Apache installed,
30 with the mod_python module activated.
32 Then edit your ``httpd.conf`` file and add the following::
35 SetHandler python-program
36 PythonHandler django.core.handlers.modpython
37 SetEnv DJANGO_SETTINGS_MODULE mysite.settings
41 ...and replace ``mysite.settings`` with the Python import path to your Django
42 project's settings file.
44 This tells Apache: "Use mod_python for any URL at or under '/mysite/', using the
45 Django mod_python handler." It passes the value of ``DJANGO_SETTINGS_MODULE``
46 so mod_python knows which settings to use.
48 Note that we're using the ``<Location>`` directive, not the ``<Directory>``
49 directive. The latter is used for pointing at places on your filesystem,
50 whereas ``<Location>`` points at places in the URL structure of a Web site.
51 ``<Directory>`` would be meaningless here.
53 Also, if your Django project is not on the default ``PYTHONPATH`` for your
54 computer, you'll have to tell mod_python where your project can be found:
59 SetHandler python-program
60 PythonHandler django.core.handlers.modpython
61 SetEnv DJANGO_SETTINGS_MODULE mysite.settings
63 **PythonPath "['/path/to/project'] + sys.path"**
68 If you're using Windows, remember that the path will contain backslashes.
69 This string is passed through Python's string parser twice, so you need to
70 escape each backslash **twice**::
72 PythonPath "['c:\\\\path\\\\to\\\\project'] + sys.path"
76 PythonPath "[r'c:\\path\\to\\project'] + sys.path"
78 You can also add directives such as ``PythonAutoReload Off`` for performance.
79 See the `mod_python documentation`_ for a full list of options.
81 Note that you should set ``PythonDebug Off`` on a production server. If you
82 leave ``PythonDebug On``, your users would see ugly (and revealing) Python
83 tracebacks if something goes wrong within mod_python.
85 Restart Apache, and any request to /mysite/ or below will be served by Django.
86 Note that Django's URLconfs won't trim the "/mysite/" -- they get passed the
89 When deploying Django sites on mod_python, you'll need to restart Apache each
90 time you make changes to your Python code.
92 Multiple Django installations on the same Apache
93 ================================================
95 It's entirely possible to run multiple Django installations on the same Apache
96 instance. Just use ``VirtualHost`` for that, like so::
101 ServerName www.example.com
103 SetEnv DJANGO_SETTINGS_MODULE mysite.settings
107 ServerName www2.example.com
109 SetEnv DJANGO_SETTINGS_MODULE mysite.other_settings
112 If you need to put two Django installations within the same ``VirtualHost``,
113 you'll need to take a special precaution to ensure mod_python's cache doesn't
114 mess things up. Use the ``PythonInterpreter`` directive to give different
115 ``<Location>`` directives separate interpreters::
118 ServerName www.example.com
120 <Location "/something">
121 SetEnv DJANGO_SETTINGS_MODULE mysite.settings
122 PythonInterpreter mysite
125 <Location "/otherthing">
126 SetEnv DJANGO_SETTINGS_MODULE mysite.other_settings
127 PythonInterpreter mysite_other
131 The values of ``PythonInterpreter`` don't really matter, as long as they're
132 different between the two ``Location`` blocks.
134 Running a development server with mod_python
135 ============================================
137 If you use mod_python for your development server, you can avoid the hassle of
138 having to restart the server each time you make code changes. Just set
139 ``MaxRequestsPerChild 1`` in your ``httpd.conf`` file to force Apache to reload
140 everything for each request. But don't do that on a production server, or we'll
141 revoke your Django privileges.
143 If you're the type of programmer who debugs using scattered ``print``
144 statements, note that ``print`` statements have no effect in mod_python; they
145 don't appear in the Apache log, as one might expect. If you have the need to
146 print debugging information in a mod_python setup, either do this::
148 assert False, the_value_i_want_to_see
150 Or add the debugging information to the template of your page.
152 .. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html
157 Django doesn't serve media files itself; it leaves that job to whichever Web
160 We recommend using a separate Web server -- i.e., one that's not also running
161 Django -- for serving media. Here are some good choices:
165 * A stripped-down version of Apache_
167 If, however, you have no option but to serve media files on the same Apache
168 ``VirtualHost`` as Django, here's how you can turn off mod_python for a
169 particular part of the site::
175 Just change ``Location`` to the root URL of your media files. You can also use
176 ``<LocationMatch>`` to match a regular expression.
178 This example sets up Django at the site root but explicitly disables Django for
179 the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or
183 SetHandler python-program
184 PythonHandler django.core.handlers.modpython
185 SetEnv DJANGO_SETTINGS_MODULE mysite.settings
192 <LocationMatch "\.(jpg|gif|png)$">
197 .. _lighttpd: http://www.lighttpd.net/
198 .. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
199 .. _Apache: http://httpd.apache.org/
201 Serving the admin files
202 =======================
204 Note that the Django development server automagically serves admin media files,
205 but this is not the case when you use any other server arrangement. You're
206 responsible for setting up Apache, or whichever media server you're using, to
207 serve the admin files.
209 The admin files live in (``django/contrib/admin/media``) of the Django
212 Here are two recommended approaches:
214 1. Create a symbolic link to the admin media files from within your
215 document root. This way, all of your Django-related files -- code
216 **and** templates -- stay in one place, and you'll still be able to
217 ``svn update`` your code to get the latest admin templates, if they
219 2. Or, copy the admin media files so that they live within your Apache
222 Using eggs with mod_python
223 ==========================
225 If you installed Django from a Python egg_ or are using eggs in your Django
226 project, some extra configuration is required. Create an extra file in your
227 project (or somewhere else) that contains something like the following::
230 os.environ['PYTHON_EGG_CACHE'] = '/some/directory'
232 Here, ``/some/directory`` is a directory that the Apache webserver process can
233 write to. It will be used as the location for any unpacking of code the eggs
236 Then you have to tell mod_python to import this file before doing anything
237 else. This is done using the PythonImport_ directive to mod_python. You need
238 to ensure that you have specified the ``PythonInterpreter`` directive to
239 mod_python as described above__ (you need to do this even if you aren't
240 serving multiple installations in this case). Then add the ``PythonImport``
241 line inside the ``Location`` or ``VirtualHost`` section. For example::
243 PythonInterpreter my_django
244 PythonImport /path/to/my/project/file.py my_django
246 Note that you can use an absolute path here (or a normal dotted import path),
247 as described in the `mod_python manual`_. We use an absolute path in the
248 above example because if any Python path modifications are required to access
249 your project, they will not have been done at the time the ``PythonImport``
252 .. _Egg: http://peak.telecommunity.com/DevCenter/PythonEggs
253 .. _PythonImport: http://www.modpython.org/live/current/doc-html/dir-other-pimp.html
254 .. _mod_python manual: PythonImport_
255 __ `Multiple Django installations on the same Apache`_
260 When you use Apache/mod_python, errors will be caught by Django -- in other
261 words, they won't propagate to the Apache level and won't appear in the Apache
264 The exception for this is if something is really wonky in your Django setup. In
265 that case, you'll see an "Internal Server Error" page in your browser and the
266 full Python traceback in your Apache ``error_log`` file. The ``error_log``
267 traceback is spread over multiple lines. (Yes, this is ugly and rather hard to
268 read, but it's how mod_python does things.)
270 If you get a segmentation fault
271 ===============================
273 If Apache causes a segmentation fault, there are two probable causes, neither
274 of which has to do with Django itself.
276 1. It may be because your Python code is importing the "pyexpat" module,
277 which may conflict with the version embedded in Apache. For full
278 information, see `Expat Causing Apache Crash`_.
279 2. It may be because you're running mod_python and mod_php in the same
280 Apache instance, with MySQL as your database backend. In some cases,
281 this causes a known mod_python issue due to version conflicts in PHP and
282 the Python MySQL backend. There's full information in the
283 `mod_python FAQ entry`_.
285 If you continue to have problems setting up mod_python, a good thing to do is
286 get a barebones mod_python site working, without the Django framework. This is
287 an easy way to isolate mod_python-specific problems. `Getting mod_python Working`_
288 details this procedure.
290 The next step should be to edit your test code and add an import of any
291 Django-specific code you're using -- your views, your models, your URLconf,
292 your RSS configuration, etc. Put these imports in your test handler function
293 and access your test URL in a browser. If this causes a crash, you've confirmed
294 it's the importing of Django code that causes the problem. Gradually reduce the
295 set of imports until it stops crashing, so as to find the specific module that
296 causes the problem. Drop down further into modules and look into their imports,
299 .. _Expat Causing Apache Crash: http://www.dscpl.com.au/articles/modpython-006.html
300 .. _mod_python FAQ entry: http://modpython.org/FAQ/faqw.py?req=show&file=faq02.013.htp
301 .. _Getting mod_python Working: http://www.dscpl.com.au/articles/modpython-001.html