============================================

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_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_wsgi: http://code.google.com/p/modwsgi/

.. _mod_perl: http://perl.apache.org/

.. _mod_python: http://www.modpython.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 :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).

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

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