Massive reorganization of the docs. See the new docs online at http://docs.djangoproject.com/.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8506 bcc190cf-cafb-0310-a4f2-bffc1f526a37

3 files changed, 777 insertions, 0 deletions

diff --git a/docs/howto/deployment/fastcgi.txt b/docs/howto/deployment/fastcgi.txt
new file mode 100644
index 0000000000..f9f9a8184a
--- /dev/null
+++ b/docs/howto/deployment/fastcgi.txt
@@ -0,0 +1,383 @@
+.. _howto-deployment-fastcgi:
+
+===========================================
+How to use Django with FastCGI, SCGI or AJP
+===========================================
+
+.. highlight:: bash
+
+Although the current preferred setup for running Django is :ref:`Apache with
+mod_python <howto-deployment-modpython>`, many people use shared hosting, on
+which protocols such as FastCGI, SCGI or AJP are the only viable options. In
+some setups, these protocols also allow better security -- and, possibly, better
+performance -- than mod_python_.
+
+.. admonition:: Note
+
+    This document primarily focuses on FastCGI. Other protocols, such as SCGI
+    and AJP, are also supported, through the ``flup`` Python package. See the
+    Protocols_ section below for specifics about SCGI and AJP.
+
+Essentially, FastCGI is an efficient way of letting an external application
+serve pages to a Web server. The Web server delegates the incoming Web requests
+(via a socket) to FastCGI, which executes the code and passes the response back
+to the Web server, which, in turn, passes it back to the client's Web browser.
+
+Like mod_python, FastCGI allows code to stay in memory, allowing requests to be
+served with no startup time. Unlike mod_python_ (or `mod_perl`_), a FastCGI
+process doesn't run inside the Web server process, but in a separate,
+persistent process.
+
+.. _mod_python: http://www.modpython.org/
+.. _mod_perl: http://perl.apache.org/
+
+.. admonition:: Why run code in a separate process?
+
+    The traditional ``mod_*`` arrangements in Apache embed various scripting
+    languages (most notably PHP, Python and Perl) inside the process space of
+    your Web server. Although this lowers startup time -- because code doesn't
+    have to be read off disk for every request -- it comes at the cost of
+    memory use. For mod_python, for example, every Apache process gets its own
+    Python interpreter, which uses up a considerable amount of RAM.
+
+    Due to the nature of FastCGI, it's even possible to have processes that run
+    under a different user account than the Web server process. That's a nice
+    security benefit on shared systems, because it means you can secure your
+    code from other users.
+
+Prerequisite: flup
+==================
+
+Before you can start using FastCGI with Django, you'll need to install flup_, a
+Python library for dealing with FastCGI. Version 0.5 or newer should work fine.
+
+.. _flup: http://www.saddi.com/software/flup/
+
+Starting your FastCGI server
+============================
+
+FastCGI operates on a client-server model, and in most cases you'll be starting
+the FastCGI process on your own. Your Web server (be it Apache, lighttpd, or
+otherwise) only contacts your Django-FastCGI process when the server needs a
+dynamic page to be loaded. Because the daemon is already running with the code
+in memory, it's able to serve the response very quickly.
+
+.. admonition:: Note
+
+    If you're on a shared hosting system, you'll probably be forced to use
+    Web server-managed FastCGI processes. See the section below on running
+    Django with Web server-managed processes for more information.
+
+A Web server can connect to a FastCGI server in one of two ways: It can use
+either a Unix domain socket (a "named pipe" on Win32 systems), or it can use a
+TCP socket. What you choose is a manner of preference; a TCP socket is usually
+easier due to permissions issues.
+
+To start your server, first change into the directory of your project (wherever
+your :ref:`manage.py <ref-django-admin>` is), and then run the
+:djadmin:`runfcgi` command::
+
+    ./manage.py runfcgi [options]
+
+If you specify ``help`` as the only option after :djadmin:`runfcgi`, it'll
+display a list of all the available options.
+
+You'll need to specify either a ``socket``, a ``protocol`` or both ``host`` and
+``port``. Then, when you set up your Web server, you'll just need to point it at
+the host/port or socket you specified when starting the FastCGI server. See the
+examples_, below.
+
+Protocols
+---------
+
+Django supports all the protocols that flup_ does, namely fastcgi_, `SCGI`_ and
+`AJP1.3`_ (the Apache JServ Protocol, version 1.3). Select your preferred
+protocol by using the ``protocol=<protocol_name>`` option with ``./manage.py
+runfcgi`` -- where ``<protocol_name>`` may be one of: ``fcgi`` (the default),
+``scgi`` or ``ajp``. For example::
+
+    ./manage.py runfcgi protocol=scgi
+
+.. _flup: http://www.saddi.com/software/flup/
+.. _fastcgi: http://www.fastcgi.com/
+.. _SCGI: http://python.ca/scgi/protocol.txt
+.. _AJP1.3: http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html
+
+Examples
+--------
+
+Running a threaded server on a TCP port::
+
+    ./manage.py runfcgi method=threaded host=127.0.0.1 port=3033
+
+Running a preforked server on a Unix domain socket::
+
+    ./manage.py runfcgi method=prefork socket=/home/user/mysite.sock pidfile=django.pid
+
+Run without daemonizing (backgrounding) the process (good for debugging)::
+
+    ./manage.py runfcgi daemonize=false socket=/tmp/mysite.sock maxrequests=1
+
+Stopping the FastCGI daemon
+---------------------------
+
+If you have the process running in the foreground, it's easy enough to stop it:
+Simply hitting ``Ctrl-C`` will stop and quit the FastCGI server. However, when
+you're dealing with background processes, you'll need to resort to the Unix
+``kill`` command.
+
+If you specify the ``pidfile`` option to :djadmin:`runfcgi`, you can kill the
+running FastCGI daemon like this::
+
+    kill `cat $PIDFILE`
+
+...where ``$PIDFILE`` is the ``pidfile`` you specified.
+
+To easily restart your FastCGI daemon on Unix, try this small shell script::
+
+    #!/bin/bash
+
+    # Replace these three settings.
+    PROJDIR="/home/user/myproject"
+    PIDFILE="$PROJDIR/mysite.pid"
+    SOCKET="$PROJDIR/mysite.sock"
+
+    cd $PROJDIR
+    if [ -f $PIDFILE ]; then
+        kill `cat -- $PIDFILE`
+        rm -f -- $PIDFILE
+    fi
+
+    exec /usr/bin/env - \
+      PYTHONPATH="../python:.." \
+      ./manage.py runfcgi socket=$SOCKET pidfile=$PIDFILE
+
+Apache setup
+============
+
+To use Django with Apache and FastCGI, you'll need Apache installed and
+configured, with `mod_fastcgi`_ installed and enabled. Consult the Apache
+documentation for instructions.
+
+Once you've got that set up, point Apache at your Django FastCGI instance by
+editing the ``httpd.conf`` (Apache configuration) file. You'll need to do two
+things:
+
+    * Use the ``FastCGIExternalServer`` directive to specify the location of
+      your FastCGI server.
+    * Use ``mod_rewrite`` to point URLs at FastCGI as appropriate.
+
+.. _mod_fastcgi: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html
+
+Specifying the location of the FastCGI server
+---------------------------------------------
+
+The ``FastCGIExternalServer`` directive tells Apache how to find your FastCGI
+server. As the `FastCGIExternalServer docs`_ explain, you can specify either a
+``socket`` or a ``host``. Here are examples of both:
+
+.. code-block:: apache
+
+    # Connect to FastCGI via a socket / named pipe.
+    FastCGIExternalServer /home/user/public_html/mysite.fcgi -socket /home/user/mysite.sock
+
+    # Connect to FastCGI via a TCP host/port.
+    FastCGIExternalServer /home/user/public_html/mysite.fcgi -host 127.0.0.1:3033
+
+In either case, the file ``/home/user/public_html/mysite.fcgi`` doesn't
+actually have to exist. It's just a URL used by the Web server internally -- a
+hook for signifying which requests at a URL should be handled by FastCGI. (More
+on this in the next section.)
+
+.. _FastCGIExternalServer docs: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html#FastCgiExternalServer
+
+Using mod_rewrite to point URLs at FastCGI
+------------------------------------------
+
+The second step is telling Apache to use FastCGI for URLs that match a certain
+pattern. To do this, use the `mod_rewrite`_ module and rewrite URLs to
+``mysite.fcgi`` (or whatever you specified in the ``FastCGIExternalServer``
+directive, as explained in the previous section).
+
+In this example, we tell Apache to use FastCGI to handle any request that
+doesn't represent a file on the filesystem and doesn't start with ``/media/``.
+This is probably the most common case, if you're using Django's admin site:
+
+.. code-block:: apache
+
+    <VirtualHost 12.34.56.78>
+      ServerName example.com
+      DocumentRoot /home/user/public_html
+      Alias /media /home/user/python/django/contrib/admin/media
+      RewriteEngine On
+      RewriteRule ^/(media.*)$ /$1 [QSA,L,PT]
+      RewriteCond %{REQUEST_FILENAME} !-f
+      RewriteRule ^/(.*)$ /mysite.fcgi/$1 [QSA,L]
+    </VirtualHost>
+
+.. _mod_rewrite: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
+
+Django will automatically use the pre-rewrite version of the URL when
+constructing URLs with the ``{% url %}`` template tag (and similar methods).
+
+lighttpd setup
+==============
+
+lighttpd_ is a lightweight Web server commonly used for serving static files. It
+supports FastCGI natively and, thus, is a good choice for serving both static
+and dynamic pages, if your site doesn't have any Apache-specific needs.
+
+.. _lighttpd: http://www.lighttpd.net/
+
+Make sure ``mod_fastcgi`` is in your modules list, somewhere after
+``mod_rewrite`` and ``mod_access``, but not after ``mod_accesslog``. You'll
+probably want ``mod_alias`` as well, for serving admin media.
+
+Add the following to your lighttpd config file:
+
+.. code-block:: lua
+
+    server.document-root = "/home/user/public_html"
+    fastcgi.server = (
+        "/mysite.fcgi" => (
+            "main" => (
+                # Use host / port instead of socket for TCP fastcgi
+                # "host" => "127.0.0.1",
+                # "port" => 3033,
+                "socket" => "/home/user/mysite.sock",
+                "check-local" => "disable",
+            )
+        ),
+    )
+    alias.url = (
+        "/media/" => "/home/user/django/contrib/admin/media/",
+    )
+
+    url.rewrite-once = (
+        "^(/media.*)$" => "$1",
+        "^/favicon\.ico$" => "/media/favicon.ico",
+        "^(/.*)$" => "/mysite.fcgi$1",
+    )
+
+Running multiple Django sites on one lighttpd
+---------------------------------------------
+
+lighttpd lets you use "conditional configuration" to allow configuration to be
+customized per host. To specify multiple FastCGI sites, just add a conditional
+block around your FastCGI config for each site::
+
+    # If the hostname is 'www.example1.com'...
+    $HTTP["host"] == "www.example1.com" {
+        server.document-root = "/foo/site1"
+        fastcgi.server = (
+           ...
+        )
+        ...
+    }
+
+    # If the hostname is 'www.example2.com'...
+    $HTTP["host"] == "www.example2.com" {
+        server.document-root = "/foo/site2"
+        fastcgi.server = (
+           ...
+        )
+        ...
+    }
+
+You can also run multiple Django installations on the same site simply by
+specifying multiple entries in the ``fastcgi.server`` directive. Add one
+FastCGI host for each.
+
+Running Django on a shared-hosting provider with Apache
+=======================================================
+
+Many shared-hosting providers don't allow you to run your own server daemons or
+edit the ``httpd.conf`` file. In these cases, it's still possible to run Django
+using Web server-spawned processes.
+
+.. admonition:: Note
+
+    If you're using Web server-spawned processes, as explained in this section,
+    there's no need for you to start the FastCGI server on your own. Apache
+    will spawn a number of processes, scaling as it needs to.
+
+In your Web root directory, add this to a file named ``.htaccess``:
+
+.. code-block:: apache
+
+    AddHandler fastcgi-script .fcgi
+    RewriteEngine On
+    RewriteCond %{REQUEST_FILENAME} !-f
+    RewriteRule ^(.*)$ mysite.fcgi/$1 [QSA,L]
+
+Then, create a small script that tells Apache how to spawn your FastCGI
+program. Create a file ``mysite.fcgi`` and place it in your Web directory, and
+be sure to make it executable:
+
+.. code-block:: python
+
+    #!/usr/bin/python
+    import sys, os
+
+    # Add a custom Python path.
+    sys.path.insert(0, "/home/user/python")
+
+    # Switch to the directory of your project. (Optional.)
+    # os.chdir("/home/user/myproject")
+
+    # Set the DJANGO_SETTINGS_MODULE environment variable.
+    os.environ['DJANGO_SETTINGS_MODULE'] = "myproject.settings"
+
+    from django.core.servers.fastcgi import runfastcgi
+    runfastcgi(method="threaded", daemonize="false")
+
+Restarting the spawned server
+-----------------------------
+
+If you change any Python code on your site, you'll need to tell FastCGI the
+code has changed. But there's no need to restart Apache in this case. Rather,
+just reupload ``mysite.fcgi``, or edit the file, so that the timestamp on the
+file will change. When Apache sees the file has been updated, it will restart
+your Django application for you.
+
+If you have access to a command shell on a Unix system, you can accomplish this
+easily by using the ``touch`` command::
+
+    touch mysite.fcgi
+
+Serving admin media files
+=========================
+
+Regardless of the server and configuration you eventually decide to use, you
+will also need to give some thought to how to serve the admin media files. The
+advice given in the :ref:`modpython <serving-the-admin-files>` documentation
+is also applicable in the setups detailed above.
+
+Forcing the URL prefix to a particular value
+============================================
+
+Because many of these fastcgi-based solutions require rewriting the URL at
+some point inside the webserver, the path information that Django sees may not
+resemble the original URL that was passed in. This is a problem if the Django
+application is being served from under a particular prefix and you want your
+URLs from the ``{% url %}`` tag to look like the prefix, rather than the
+rewritten version, which might contain, for example, ``mysite.fcgi``.
+
+Django makes a good attempt to work out what the real script name prefix
+should be. In particular, if the webserver sets the ``SCRIPT_URL`` (specific
+to Apache's mod_rewrite), or ``REDIRECT_URL`` (set by a few servers, including
+Apache + mod_rewrite in some situations), Django will work out the original
+prefix automatically.
+
+In the cases where Django cannot work out the prefix correctly and where you
+want the original value to be used in URLs, you can set the
+``FORCE_SCRIPT_NAME`` setting in your main ``settings`` file. This sets the
+script name uniformly for every URL served via that settings file. Thus you'll
+need to use different settings files if you want different sets of URLs to
+have different script names in this case, but that is a rare situation.
+
+As an example of how to use it, if your Django configuration is serving all of
+the URLs under ``'/'`` and you wanted to use this setting, you would set
+``FORCE_SCRIPT_NAME = ''`` in your settings file.
+
+
diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt
new file mode 100644
index 0000000000..80c16fcd82
--- /dev/null
+++ b/docs/howto/deployment/index.txt
@@ -0,0 +1,33 @@
+.. _howto-deployment-index:
+
+Deploying Django
+================
+
+Django's chock-full of shortcuts to make web developer's lives easier, but all
+those tools are of no use if you can't easily deploy your sites. Since Django's
+inception, ease of deployment has been a major goal. There's a number of good
+ways to easily deploy Django:
+
+.. toctree::
+   :maxdepth: 1
+   
+   modpython
+   fastcgi
+   
+:ref:`Deploying under mod_python <howto-deployment-modpython>` is the
+recommended deployment method; start there if you're not sure which path you'd
+like to go down.
+
+.. seealso::
+
+    * `Chapter 20 of The Django Book`_ discusses deployment and especially
+      scaling in more detail.
+      
+    * `mod_wsgi`_ is a newcomer to the Python deployment world, but it's rapidly
+      gaining traction. Currently there's a few hoops you have to jump through to
+      `use mod_wsgi with Django`_, but mod_wsgi tends to get rave reviews from
+      those who use it.
+
+.. _chapter 20 of the django book: http://djangobook.com/en/1.0/chapter20/
+.. _mod_wsgi: http://code.google.com/p/modwsgi/
+.. _use mod_wsgi with Django: http://code.google.com/p/modwsgi/wiki/IntegrationWithDjango
\ No newline at end of file
diff --git a/docs/howto/deployment/modpython.txt b/docs/howto/deployment/modpython.txt
new file mode 100644
index 0000000000..0303e13153
--- /dev/null
+++ b/docs/howto/deployment/modpython.txt
@@ -0,0 +1,361 @@
+.. _howto-deployment-modpython:
+
+============================================
+How to use Django with Apache and mod_python
+============================================
+
+.. highlight:: apache
+
+Apache_ with `mod_python`_ currently is the preferred setup for using Django
+on a production server.
+
+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`_.
+
+You may also be interested in :ref:`How to use Django with FastCGI, SCGI or AJP
+<howto-deployment-fastcgi>` (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
+
+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.
+
+**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 :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.
+
+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.
+
+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:
+
+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/
+
+.. _howto-deployment-modpython-serving-the-admin-files:
+
+.. _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 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
+
+