|
1 .. _howto-deployment-modpython: |
|
2 |
|
3 ============================================ |
|
4 How to use Django with Apache and mod_python |
|
5 ============================================ |
|
6 |
|
7 .. warning:: |
|
8 |
|
9 Support for mod_python will be deprecated in a future release of Django. If |
|
10 you are configuring a new deployment, you are strongly encouraged to |
|
11 consider using :doc:`mod_wsgi </howto/deployment/modwsgi>` or any of the |
|
12 other :doc:`supported backends </howto/deployment/index>`. |
|
13 |
|
14 .. highlight:: apache |
|
15 |
|
16 The `mod_python`_ module for Apache_ can be used to deploy Django to a |
|
17 production server, although it has been mostly superseded by the simpler |
|
18 :doc:`mod_wsgi deployment option </howto/deployment/modwsgi>`. |
|
19 |
|
20 mod_python is similar to (and inspired by) `mod_perl`_ : It embeds Python within |
|
21 Apache and loads Python code into memory when the server starts. Code stays in |
|
22 memory throughout the life of an Apache process, which leads to significant |
|
23 performance gains over other server arrangements. |
|
24 |
|
25 Django requires Apache 2.x and mod_python 3.x, and you should use Apache's |
|
26 `prefork MPM`_, as opposed to the `worker MPM`_. |
|
27 |
|
28 .. seealso:: |
|
29 |
|
30 * Apache is a big, complex animal, and this document only scratches the |
|
31 surface of what Apache can do. If you need more advanced information about |
|
32 Apache, there's no better source than `Apache's own official |
|
33 documentation`_ |
|
34 |
|
35 * You may also be interested in :doc:`How to use Django with FastCGI, SCGI, |
|
36 or AJP </howto/deployment/fastcgi>`. |
|
37 |
|
38 .. _Apache: http://httpd.apache.org/ |
|
39 .. _mod_python: http://www.modpython.org/ |
|
40 .. _mod_perl: http://perl.apache.org/ |
|
41 .. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html |
|
42 .. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html |
|
43 .. _apache's own official documentation: http://httpd.apache.org/docs/ |
|
44 |
|
45 Basic configuration |
|
46 =================== |
|
47 |
|
48 To configure Django with mod_python, first make sure you have Apache installed, |
|
49 with the mod_python module activated. |
|
50 |
|
51 Then edit your ``httpd.conf`` file and add the following:: |
|
52 |
|
53 <Location "/mysite/"> |
|
54 SetHandler python-program |
|
55 PythonHandler django.core.handlers.modpython |
|
56 SetEnv DJANGO_SETTINGS_MODULE mysite.settings |
|
57 PythonOption django.root /mysite |
|
58 PythonDebug On |
|
59 </Location> |
|
60 |
|
61 ...and replace ``mysite.settings`` with the Python import path to your Django |
|
62 project's settings file. |
|
63 |
|
64 This tells Apache: "Use mod_python for any URL at or under '/mysite/', using the |
|
65 Django mod_python handler." It passes the value of :ref:`DJANGO_SETTINGS_MODULE |
|
66 <django-settings-module>` so mod_python knows which settings to use. |
|
67 |
|
68 .. versionadded:: 1.0 |
|
69 The ``PythonOption django.root ...`` is new in this version. |
|
70 |
|
71 Because mod_python does not know we are serving this site from underneath the |
|
72 ``/mysite/`` prefix, this value needs to be passed through to the mod_python |
|
73 handler in Django, via the ``PythonOption django.root ...`` line. The value set |
|
74 on that line (the last item) should match the string given in the ``<Location |
|
75 ...>`` directive. The effect of this is that Django will automatically strip the |
|
76 ``/mysite`` string from the front of any URLs before matching them against your |
|
77 URLconf patterns. If you later move your site to live under ``/mysite2``, you |
|
78 will not have to change anything except the ``django.root`` option in the config |
|
79 file. |
|
80 |
|
81 When using ``django.root`` you should make sure that what's left, after the |
|
82 prefix has been removed, begins with a slash. Your URLconf patterns that are |
|
83 expecting an initial slash will then work correctly. In the above example, |
|
84 since we want to send things like ``/mysite/admin/`` to ``/admin/``, we need |
|
85 to remove the string ``/mysite`` from the beginning, so that is the |
|
86 ``django.root`` value. It would be an error to use ``/mysite/`` (with a |
|
87 trailing slash) in this case. |
|
88 |
|
89 Note that we're using the ``<Location>`` directive, not the ``<Directory>`` |
|
90 directive. The latter is used for pointing at places on your filesystem, |
|
91 whereas ``<Location>`` points at places in the URL structure of a Web site. |
|
92 ``<Directory>`` would be meaningless here. |
|
93 |
|
94 Also, if your Django project is not on the default ``PYTHONPATH`` for your |
|
95 computer, you'll have to tell mod_python where your project can be found: |
|
96 |
|
97 .. parsed-literal:: |
|
98 |
|
99 <Location "/mysite/"> |
|
100 SetHandler python-program |
|
101 PythonHandler django.core.handlers.modpython |
|
102 SetEnv DJANGO_SETTINGS_MODULE mysite.settings |
|
103 PythonOption django.root /mysite |
|
104 PythonDebug On |
|
105 **PythonPath "['/path/to/project'] + sys.path"** |
|
106 </Location> |
|
107 |
|
108 The value you use for ``PythonPath`` should include the parent directories of |
|
109 all the modules you are going to import in your application. It should also |
|
110 include the parent directory of the :ref:`DJANGO_SETTINGS_MODULE |
|
111 <django-settings-module>` location. This is exactly the same situation as |
|
112 setting the Python path for interactive usage. Whenever you try to import |
|
113 something, Python will run through all the directories in ``sys.path`` in turn, |
|
114 from first to last, and try to import from each directory until one succeeds. |
|
115 |
|
116 Make sure that your Python source files' permissions are set such that the |
|
117 Apache user (usually named ``apache`` or ``httpd`` on most systems) will have |
|
118 read access to the files. |
|
119 |
|
120 An example might make this clearer. Suppose you have some applications under |
|
121 ``/usr/local/django-apps/`` (for example, ``/usr/local/django-apps/weblog/`` and |
|
122 so forth), your settings file is at ``/var/www/mysite/settings.py`` and you have |
|
123 specified :ref:`DJANGO_SETTINGS_MODULE <django-settings-module>` as in the above |
|
124 example. In this case, you would need to write your ``PythonPath`` directive |
|
125 as:: |
|
126 |
|
127 PythonPath "['/usr/local/django-apps/', '/var/www'] + sys.path" |
|
128 |
|
129 With this path, ``import weblog`` and ``import mysite.settings`` will both |
|
130 work. If you had ``import blogroll`` in your code somewhere and ``blogroll`` |
|
131 lived under the ``weblog/`` directory, you would *also* need to add |
|
132 ``/usr/local/django-apps/weblog/`` to your ``PythonPath``. Remember: the |
|
133 **parent directories** of anything you import directly must be on the Python |
|
134 path. |
|
135 |
|
136 .. note:: |
|
137 |
|
138 If you're using Windows, we still recommended that you use forward |
|
139 slashes in the pathnames, even though Windows normally uses the backslash |
|
140 character as its native separator. Apache knows how to convert from the |
|
141 forward slash format to the native format, so this approach is portable and |
|
142 easier to read. (It avoids tricky problems with having to double-escape |
|
143 backslashes.) |
|
144 |
|
145 This is valid even on a Windows system:: |
|
146 |
|
147 PythonPath "['c:/path/to/project'] + sys.path" |
|
148 |
|
149 You can also add directives such as ``PythonAutoReload Off`` for performance. |
|
150 See the `mod_python documentation`_ for a full list of options. |
|
151 |
|
152 Note that you should set ``PythonDebug Off`` on a production server. If you |
|
153 leave ``PythonDebug On``, your users would see ugly (and revealing) Python |
|
154 tracebacks if something goes wrong within mod_python. |
|
155 |
|
156 Restart Apache, and any request to ``/mysite/`` or below will be served by |
|
157 Django. Note that Django's URLconfs won't trim the "/mysite/" -- they get passed |
|
158 the full URL. |
|
159 |
|
160 When deploying Django sites on mod_python, you'll need to restart Apache each |
|
161 time you make changes to your Python code. |
|
162 |
|
163 .. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html |
|
164 |
|
165 Multiple Django installations on the same Apache |
|
166 ================================================ |
|
167 |
|
168 It's entirely possible to run multiple Django installations on the same Apache |
|
169 instance. Just use ``VirtualHost`` for that, like so:: |
|
170 |
|
171 NameVirtualHost * |
|
172 |
|
173 <VirtualHost *> |
|
174 ServerName www.example.com |
|
175 # ... |
|
176 SetEnv DJANGO_SETTINGS_MODULE mysite.settings |
|
177 </VirtualHost> |
|
178 |
|
179 <VirtualHost *> |
|
180 ServerName www2.example.com |
|
181 # ... |
|
182 SetEnv DJANGO_SETTINGS_MODULE mysite.other_settings |
|
183 </VirtualHost> |
|
184 |
|
185 If you need to put two Django installations within the same ``VirtualHost`` |
|
186 (or in different ``VirtualHost`` blocks that share the same server name), |
|
187 you'll need to take a special precaution to ensure mod_python's cache doesn't |
|
188 mess things up. Use the ``PythonInterpreter`` directive to give different |
|
189 ``<Location>`` directives separate interpreters:: |
|
190 |
|
191 <VirtualHost *> |
|
192 ServerName www.example.com |
|
193 # ... |
|
194 <Location "/something"> |
|
195 SetEnv DJANGO_SETTINGS_MODULE mysite.settings |
|
196 PythonInterpreter mysite |
|
197 </Location> |
|
198 |
|
199 <Location "/otherthing"> |
|
200 SetEnv DJANGO_SETTINGS_MODULE mysite.other_settings |
|
201 PythonInterpreter othersite |
|
202 </Location> |
|
203 </VirtualHost> |
|
204 |
|
205 The values of ``PythonInterpreter`` don't really matter, as long as they're |
|
206 different between the two ``Location`` blocks. |
|
207 |
|
208 Running a development server with mod_python |
|
209 ============================================ |
|
210 |
|
211 If you use mod_python for your development server, you can avoid the hassle of |
|
212 having to restart the server each time you make code changes. Just set |
|
213 ``MaxRequestsPerChild 1`` in your ``httpd.conf`` file to force Apache to reload |
|
214 everything for each request. But don't do that on a production server, or we'll |
|
215 revoke your Django privileges. |
|
216 |
|
217 If you're the type of programmer who debugs using scattered ``print`` |
|
218 statements, note that output to ``stdout`` will not appear in the Apache |
|
219 log and can even `cause response errors`_. |
|
220 |
|
221 .. _cause response errors: http://blog.dscpl.com.au/2009/04/wsgi-and-printing-to-standard-output.html |
|
222 |
|
223 If you have the need to print debugging information in a mod_python setup, you |
|
224 have a few options. You can print to ``stderr`` explicitly, like so:: |
|
225 |
|
226 print >> sys.stderr, 'debug text' |
|
227 sys.stderr.flush() |
|
228 |
|
229 (note that ``stderr`` is buffered, so calling ``flush`` is necessary if you wish |
|
230 debugging information to be displayed promptly.) |
|
231 |
|
232 A more compact approach is to use an assertion:: |
|
233 |
|
234 assert False, 'debug text' |
|
235 |
|
236 Another alternative is to add debugging information to the template of your page. |
|
237 |
|
238 .. _serving-media-files: |
|
239 |
|
240 Serving media files |
|
241 =================== |
|
242 |
|
243 Django doesn't serve media files itself; it leaves that job to whichever Web |
|
244 server you choose. |
|
245 |
|
246 We recommend using a separate Web server -- i.e., one that's not also running |
|
247 Django -- for serving media. Here are some good choices: |
|
248 |
|
249 * lighttpd_ |
|
250 * Nginx_ |
|
251 * TUX_ |
|
252 * A stripped-down version of Apache_ |
|
253 * Cherokee_ |
|
254 |
|
255 If, however, you have no option but to serve media files on the same Apache |
|
256 ``VirtualHost`` as Django, here's how you can turn off mod_python for a |
|
257 particular part of the site:: |
|
258 |
|
259 <Location "/media"> |
|
260 SetHandler None |
|
261 </Location> |
|
262 |
|
263 Just change ``Location`` to the root URL of your media files. You can also use |
|
264 ``<LocationMatch>`` to match a regular expression. |
|
265 |
|
266 This example sets up Django at the site root but explicitly disables Django for |
|
267 the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or |
|
268 ``.png``:: |
|
269 |
|
270 <Location "/"> |
|
271 SetHandler python-program |
|
272 PythonHandler django.core.handlers.modpython |
|
273 SetEnv DJANGO_SETTINGS_MODULE mysite.settings |
|
274 </Location> |
|
275 |
|
276 <Location "/media"> |
|
277 SetHandler None |
|
278 </Location> |
|
279 |
|
280 <LocationMatch "\.(jpg|gif|png)$"> |
|
281 SetHandler None |
|
282 </LocationMatch> |
|
283 |
|
284 |
|
285 .. _lighttpd: http://www.lighttpd.net/ |
|
286 .. _Nginx: http://wiki.nginx.org/Main |
|
287 .. _TUX: http://en.wikipedia.org/wiki/TUX_web_server |
|
288 .. _Apache: http://httpd.apache.org/ |
|
289 .. _Cherokee: http://www.cherokee-project.com/ |
|
290 |
|
291 .. _serving-the-admin-files: |
|
292 |
|
293 Serving the admin files |
|
294 ======================= |
|
295 |
|
296 Note that the Django development server automagically serves admin media files, |
|
297 but this is not the case when you use any other server arrangement. You're |
|
298 responsible for setting up Apache, or whichever media server you're using, to |
|
299 serve the admin files. |
|
300 |
|
301 The admin files live in (:file:`django/contrib/admin/media`) of the Django |
|
302 distribution. |
|
303 |
|
304 Here are two recommended approaches: |
|
305 |
|
306 1. Create a symbolic link to the admin media files from within your |
|
307 document root. This way, all of your Django-related files -- code **and** |
|
308 templates -- stay in one place, and you'll still be able to ``svn |
|
309 update`` your code to get the latest admin templates, if they change. |
|
310 |
|
311 2. Or, copy the admin media files so that they live within your Apache |
|
312 document root. |
|
313 |
|
314 Using "eggs" with mod_python |
|
315 ============================ |
|
316 |
|
317 If you installed Django from a Python egg_ or are using eggs in your Django |
|
318 project, some extra configuration is required. Create an extra file in your |
|
319 project (or somewhere else) that contains something like the following: |
|
320 |
|
321 .. code-block:: python |
|
322 |
|
323 import os |
|
324 os.environ['PYTHON_EGG_CACHE'] = '/some/directory' |
|
325 |
|
326 Here, ``/some/directory`` is a directory that the Apache Web server process can |
|
327 write to. It will be used as the location for any unpacking of code the eggs |
|
328 need to do. |
|
329 |
|
330 Then you have to tell mod_python to import this file before doing anything |
|
331 else. This is done using the PythonImport_ directive to mod_python. You need |
|
332 to ensure that you have specified the ``PythonInterpreter`` directive to |
|
333 mod_python as described above__ (you need to do this even if you aren't |
|
334 serving multiple installations in this case). Then add the ``PythonImport`` |
|
335 line in the main server configuration (i.e., outside the ``Location`` or |
|
336 ``VirtualHost`` sections). For example:: |
|
337 |
|
338 PythonInterpreter my_django |
|
339 PythonImport /path/to/my/project/file.py my_django |
|
340 |
|
341 Note that you can use an absolute path here (or a normal dotted import path), |
|
342 as described in the `mod_python manual`_. We use an absolute path in the |
|
343 above example because if any Python path modifications are required to access |
|
344 your project, they will not have been done at the time the ``PythonImport`` |
|
345 line is processed. |
|
346 |
|
347 .. _Egg: http://peak.telecommunity.com/DevCenter/PythonEggs |
|
348 .. _PythonImport: http://www.modpython.org/live/current/doc-html/dir-other-pimp.html |
|
349 .. _mod_python manual: PythonImport_ |
|
350 __ `Multiple Django installations on the same Apache`_ |
|
351 |
|
352 Error handling |
|
353 ============== |
|
354 |
|
355 When you use Apache/mod_python, errors will be caught by Django -- in other |
|
356 words, they won't propagate to the Apache level and won't appear in the Apache |
|
357 ``error_log``. |
|
358 |
|
359 The exception for this is if something is really wonky in your Django setup. In |
|
360 that case, you'll see an "Internal Server Error" page in your browser and the |
|
361 full Python traceback in your Apache ``error_log`` file. The ``error_log`` |
|
362 traceback is spread over multiple lines. (Yes, this is ugly and rather hard to |
|
363 read, but it's how mod_python does things.) |
|
364 |
|
365 If you get a segmentation fault |
|
366 =============================== |
|
367 |
|
368 If Apache causes a segmentation fault, there are two probable causes, neither |
|
369 of which has to do with Django itself. |
|
370 |
|
371 1. It may be because your Python code is importing the "pyexpat" module, |
|
372 which may conflict with the version embedded in Apache. For full |
|
373 information, see `Expat Causing Apache Crash`_. |
|
374 |
|
375 2. It may be because you're running mod_python and mod_php in the same |
|
376 Apache instance, with MySQL as your database backend. In some cases, |
|
377 this causes a known mod_python issue due to version conflicts in PHP and |
|
378 the Python MySQL backend. There's full information in the |
|
379 `mod_python FAQ entry`_. |
|
380 |
|
381 If you continue to have problems setting up mod_python, a good thing to do is |
|
382 get a barebones mod_python site working, without the Django framework. This is |
|
383 an easy way to isolate mod_python-specific problems. `Getting mod_python Working`_ |
|
384 details this procedure. |
|
385 |
|
386 The next step should be to edit your test code and add an import of any |
|
387 Django-specific code you're using -- your views, your models, your URLconf, |
|
388 your RSS configuration, etc. Put these imports in your test handler function |
|
389 and access your test URL in a browser. If this causes a crash, you've confirmed |
|
390 it's the importing of Django code that causes the problem. Gradually reduce the |
|
391 set of imports until it stops crashing, so as to find the specific module that |
|
392 causes the problem. Drop down further into modules and look into their imports, |
|
393 as necessary. |
|
394 |
|
395 .. _Expat Causing Apache Crash: http://www.dscpl.com.au/wiki/ModPython/Articles/ExpatCausingApacheCrash |
|
396 .. _mod_python FAQ entry: http://modpython.org/FAQ/faqw.py?req=show&file=faq02.013.htp |
|
397 .. _Getting mod_python Working: http://www.dscpl.com.au/wiki/ModPython/Articles/GettingModPythonWorking |
|
398 |
|
399 If you get a UnicodeEncodeError |
|
400 =============================== |
|
401 |
|
402 If you're taking advantage of the internationalization features of Django (see |
|
403 :doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must |
|
404 ensure that the environment used to start Apache is configured to accept |
|
405 non-ASCII file names. If your environment is not correctly configured, you |
|
406 will trigger ``UnicodeEncodeError`` exceptions when calling functions like |
|
407 ``os.path()`` on filenames that contain non-ASCII characters. |
|
408 |
|
409 To avoid these problems, the environment used to start Apache should contain |
|
410 settings analogous to the following:: |
|
411 |
|
412 export LANG='en_US.UTF-8' |
|
413 export LC_ALL='en_US.UTF-8' |
|
414 |
|
415 Consult the documentation for your operating system for the appropriate syntax |
|
416 and location to put these configuration items; ``/etc/apache2/envvars`` is a |
|
417 common location on Unix platforms. Once you have added these statements |
|
418 to your environment, restart Apache. |