mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 02:48:35 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

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

Browse source 
git-svn-id: http://code.djangoproject.com/svn/django/trunk@8506 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jacob Kaplan-Moss 2008-08-23 22:25:40 +00:00
parent b3688e8194
commit 97cb07c3a1
188 changed files with 19913 additions and 17059 deletions
Download patch file Download diff file Expand all files Collapse all files

383
docs/howto/deployment/fastcgi.txt Normal file
View file

@ -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.

33
docs/howto/deployment/index.txt Normal file
View file

@ -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

361
docs/howto/deployment/modpython.txt Normal file
View file

@ -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