# django / docs / modpython.txt

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 ================================= 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, SCGI or AJP_ (which also covers SCGI and AJP). .. _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, SCGI or AJP: ../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:: SetHandler python-program PythonHandler django.core.handlers.modpython SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonDebug On ...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 DJANGO_SETTINGS_MODULE so mod_python knows which settings to use. Note that we're using the  directive, not the  directive. The latter is used for pointing at places on your filesystem, whereas  points at places in the URL structure of a Web site.  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: .. parsed-literal:: SetHandler python-program PythonHandler django.core.handlers.modpython SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonDebug On **PythonPath "['/path/to/project'] + sys.path"** .. caution:: If you're using Windows, remember that the path will contain backslashes. This string is passed through Python's string parser twice, so you need to escape each backslash **twice**:: PythonPath "['c:\\\\path\\\\to\\\\project'] + sys.path" Or, use raw strings:: PythonPath "[r'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. 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 * ServerName www.example.com # ... SetEnv DJANGO_SETTINGS_MODULE mysite.settings ServerName www2.example.com # ... SetEnv DJANGO_SETTINGS_MODULE mysite.other_settings 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  directives separate interpreters:: ServerName www.example.com # ... SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonInterpreter mysite SetEnv DJANGO_SETTINGS_MODULE mysite.other_settings PythonInterpreter mysite_other 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:: SetHandler None Just change Location to the root URL of your media files. You can also use  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:: SetHandler python-program PythonHandler django.core.handlers.modpython SetEnv DJANGO_SETTINGS_MODULE mysite.settings SetHandler None SetHandler None .. _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. 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:: import os os.environ['PYTHON_EGG_CACHE'] = '/some/directory' Here, /some/directory is a directory that the Apache webserver 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 inside the Location or VirtualHost section. 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/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