431 lines
16 KiB
Plaintext
431 lines
16 KiB
Plaintext
============================================
|
|
How to use Django with FastCGI, SCGI, or AJP
|
|
============================================
|
|
|
|
.. highlight:: bash
|
|
|
|
Although the current preferred setup for running Django is :doc:`Apache with
|
|
mod_wsgi </howto/deployment/modwsgi>`, many people use shared hosting, on
|
|
which protocols such as FastCGI, SCGI or AJP are the only viable options. In
|
|
some setups, these protocols may provide better performance than mod_wsgi_.
|
|
|
|
.. 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_wsgi, FastCGI allows code to stay in memory, allowing requests to be
|
|
served with no startup time. While mod_wsgi can either be configured embedded
|
|
in the Apache Web server process or as a separate daemon process, a FastCGI
|
|
process never runs inside the Web server process, always in a separate,
|
|
persistent process.
|
|
|
|
.. _mod_wsgi: http://code.google.com/p/modwsgi/
|
|
.. _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.
|
|
|
|
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 :doc:`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 :djadminopt:`socket`, a :djadminopt:`protocol`
|
|
or both :djadminopt:`host` and :djadminopt:`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 :djadminopt:`protocol=\<protocol_name\> <protocol>` 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
|
|
|
|
.. admonition:: Socket security
|
|
|
|
Django's default umask requires that the webserver and the Django fastcgi
|
|
process be run with the same group **and** user. For increased security,
|
|
you can run them under the same group but as different users. If you do
|
|
this, you will need to set the umask to 0002 using the ``umask`` argument
|
|
to ``runfcgi``.
|
|
|
|
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 :djadminopt:`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).
|
|
|
|
Using mod_fcgid as alternative to mod_fastcgi
|
|
----------------------------------------------
|
|
|
|
Another way to serve applications through FastCGI is by using Apache's
|
|
`mod_fcgid`_ module. Compared to mod_fastcgi mod_fcgid handles FastCGI
|
|
applications differently in that it manages the spawning of worker processes
|
|
by itself and doesn't offer something like ``FastCGIExternalServer``. This
|
|
means that the configuration looks slightly different.
|
|
|
|
In effect, you have to go the way of adding a script handler similar to what
|
|
is described later on regarding running Django in a :ref:`shared-hosting
|
|
environment <apache_shared_hosting>`. For further details please refer to the
|
|
`mod_fcgid reference`_
|
|
|
|
.. _mod_fcgid: http://httpd.apache.org/mod_fcgid/
|
|
.. _mod_Fcgid reference: http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html
|
|
|
|
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.
|
|
|
|
Cherokee setup
|
|
==============
|
|
|
|
Cherokee is a very fast, flexible and easy to configure Web Server. It
|
|
supports the widespread technologies nowadays: FastCGI, SCGI, PHP, CGI, SSI,
|
|
TLS and SSL encrypted connections, Virtual hosts, Authentication, on the fly
|
|
encoding, Load Balancing, Apache compatible log files, Data Base Balancer,
|
|
Reverse HTTP Proxy and much more.
|
|
|
|
The Cherokee project provides a documentation to `setting up Django`_ with Cherokee.
|
|
|
|
.. _setting up Django: http://www.cherokee-project.com/doc/cookbook_django.html
|
|
|
|
.. _apache_shared_hosting:
|
|
|
|
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")
|
|
|
|
This works if your server uses mod_fastcgi. If, on the other hand, you are
|
|
using mod_fcgid the setup is mostly the same except for a slight change in the
|
|
``.htaccess`` file. Instead of adding a fastcgi-script handler, you have to
|
|
add a fcgid-handler:
|
|
|
|
.. code-block:: apache
|
|
|
|
AddHandler fcgid-script .fcgi
|
|
RewriteEngine On
|
|
RewriteCond %{REQUEST_FILENAME} !-f
|
|
RewriteRule ^(.*)$ mysite.fcgi/$1 [QSA,L]
|
|
|
|
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:`mod_wsgi <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 Web server, 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 Web server 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
|
|
:setting:`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.
|