diff options
Diffstat (limited to 'docs/modpython.txt')
| -rw-r--r-- | docs/modpython.txt | 349 |
1 files changed, 0 insertions, 349 deletions
diff --git a/docs/modpython.txt b/docs/modpython.txt deleted file mode 100644 index 44de0e1bd2..0000000000 --- a/docs/modpython.txt +++ /dev/null @@ -1,349 +0,0 @@ -================================= -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:: - - <Location "/mysite/"> - SetHandler python-program - PythonHandler django.core.handlers.modpython - SetEnv DJANGO_SETTINGS_MODULE mysite.settings - PythonOption django.root /mysite - PythonDebug On - </Location> - -...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. - -**New in Django development version:** Because mod_python does not know we are -serving this site from underneath the ``/mysite/`` prefix, this value needs to -be passed through to the mod_python handler in Django, via the ``PythonOption -django.root ...`` line. The value set on that line (the last item) should -match the string given in the ``<Location ...>`` directive. The effect of this -is that Django will automatically strip the ``/mysite`` string from the front -of any URLs before matching them against your ``URLConf`` patterns. If you -later move your site to live under ``/mysite2``, you will not have to change -anything except the ``django.root`` option in the config file. - -When using ``django.root`` you should make sure that what's left, after the -prefix has been removed, begins with a slash. Your URLConf patterns that are -expecting an initial slash will then work correctly. In the above example, -since we want to send things like ``/mysite/admin/`` to ``/admin/``, we need -to remove the string ``/mysite`` from the beginning, so that is the -``django.root`` value. It would be an error to use ``/mysite/`` (with a -trailing slash) in this case. - -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 your Django project is not on the default ``PYTHONPATH`` for your -computer, you'll have to tell mod_python where your project can be found: - -.. parsed-literal:: - - <Location "/mysite/"> - SetHandler python-program - PythonHandler django.core.handlers.modpython - SetEnv DJANGO_SETTINGS_MODULE mysite.settings - PythonOption django.root /mysite - PythonDebug On - **PythonPath "['/path/to/project'] + sys.path"** - </Location> - -The value you use for ``PythonPath`` should include the parent directories of -all the modules you are going to import in your application. It should also -include the parent directory of the ``DJANGO_SETTINGS_MODULE`` location. This -is exactly the same situation as setting the Python path for interactive -usage. Whenever you try to import something, Python will run through all the -directories in ``sys.path`` in turn, from first to last, and try to import -from each directory until one succeeds. - -An example might make this clearer. Suppose -you have some applications under ``/usr/local/django-apps/`` (for example, -``/usr/local/django-apps/weblog/`` and so forth), your settings file is at -``/var/www/mysite/settings.py`` and you have specified -``DJANGO_SETTINGS_MODULE`` as in the above example. In this case, you would -need to write your ``PythonPath`` directive as:: - - PythonPath "['/usr/local/django-apps/', '/var/www'] + sys.path" - -With this path, ``import weblog`` and ``import mysite.settings`` will both -work. If you had ``import blogroll`` in your code somewhere and ``blogroll`` -lived under the ``weblog/`` directory, you would *also* need to add -``/usr/local/django-apps/weblog/`` to your ``PythonPath``. Remember: the -**parent directories** of anything you import directly must be on the Python -path. - -.. note:: - - If you're using Windows, we still recommended that you use forward - slashes in the pathnames, even though Windows normally uses the backslash - character as its native separator. Apache knows how to convert from the - forward slash format to the native format, so this approach is portable and - easier to read. (It avoids tricky problems with having to double-escape - backslashes.) - - This is valid even on a Windows system:: - - PythonPath "['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 * - - <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 othersite - </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. - -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 in the main server configuration (i.e., outside the ``Location`` or -``VirtualHost`` sections). 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 - - |