--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/howto/deployment/modpython.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,418 @@
+.. _howto-deployment-modpython:
+
+============================================
+How to use Django with Apache and mod_python
+============================================
+
+.. warning::
+
+ Support for mod_python will be deprecated in a future release of Django. If
+ you are configuring a new deployment, you are strongly encouraged to
+ consider using :doc:`mod_wsgi </howto/deployment/modwsgi>` or any of the
+ other :doc:`supported backends </howto/deployment/index>`.
+
+.. highlight:: apache
+
+The `mod_python`_ module for Apache_ can be used to deploy Django to a
+production server, although it has been mostly superseded by the simpler
+:doc:`mod_wsgi deployment option </howto/deployment/modwsgi>`.
+
+mod_python is similar to (and inspired by) `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`_.
+
+.. seealso::
+
+ * Apache is a big, complex animal, and this document only scratches the
+ surface of what Apache can do. If you need more advanced information about
+ Apache, there's no better source than `Apache's own official
+ documentation`_
+
+ * You may also be interested in :doc:`How to use Django with FastCGI, SCGI,
+ or AJP </howto/deployment/fastcgi>`.
+
+.. _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
+.. _apache's own official documentation: http://httpd.apache.org/docs/
+
+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 :ref:`DJANGO_SETTINGS_MODULE
+<django-settings-module>` so mod_python knows which settings to use.
+
+.. versionadded:: 1.0
+ The ``PythonOption django.root ...`` is new in this 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 :ref:`DJANGO_SETTINGS_MODULE
+<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.
+
+Make sure that your Python source files' permissions are set such that the
+Apache user (usually named ``apache`` or ``httpd`` on most systems) will have
+read access to the files.
+
+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 :ref:`DJANGO_SETTINGS_MODULE <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.
+
+.. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html
+
+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``
+(or in different ``VirtualHost`` blocks that share the same server name),
+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 output to ``stdout`` will not appear in the Apache
+log and can even `cause response errors`_.
+
+.. _cause response errors: http://blog.dscpl.com.au/2009/04/wsgi-and-printing-to-standard-output.html
+
+If you have the need to print debugging information in a mod_python setup, you
+have a few options. You can print to ``stderr`` explicitly, like so::
+
+ print >> sys.stderr, 'debug text'
+ sys.stderr.flush()
+
+(note that ``stderr`` is buffered, so calling ``flush`` is necessary if you wish
+debugging information to be displayed promptly.)
+
+A more compact approach is to use an assertion::
+
+ assert False, 'debug text'
+
+Another alternative is to add debugging information to the template of your page.
+
+.. _serving-media-files:
+
+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_
+ * Nginx_
+ * TUX_
+ * A stripped-down version of Apache_
+ * Cherokee_
+
+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/
+.. _Nginx: http://wiki.nginx.org/Main
+.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
+.. _Apache: http://httpd.apache.org/
+.. _Cherokee: http://www.cherokee-project.com/
+
+.. _serving-the-admin-files:
+
+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 (:file:`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:
+
+.. code-block:: python
+
+ import os
+ os.environ['PYTHON_EGG_CACHE'] = '/some/directory'
+
+Here, ``/some/directory`` is a directory that the Apache Web server 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/wiki/ModPython/Articles/ExpatCausingApacheCrash
+.. _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/wiki/ModPython/Articles/GettingModPythonWorking
+
+If you get a UnicodeEncodeError
+===============================
+
+If you're taking advantage of the internationalization features of Django (see
+:doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must
+ensure that the environment used to start Apache is configured to accept
+non-ASCII file names. If your environment is not correctly configured, you
+will trigger ``UnicodeEncodeError`` exceptions when calling functions like
+``os.path()`` on filenames that contain non-ASCII characters.
+
+To avoid these problems, the environment used to start Apache should contain
+settings analogous to the following::
+
+ export LANG='en_US.UTF-8'
+ export LC_ALL='en_US.UTF-8'
+
+Consult the documentation for your operating system for the appropriate syntax
+and location to put these configuration items; ``/etc/apache2/envvars`` is a
+common location on Unix platforms. Once you have added these statements
+to your environment, restart Apache.