1 ============================================

     2 How to use Django with FastCGI, SCGI, or AJP

     3 ============================================

     4 

     5 .. highlight:: bash

     6 

     7 Although the current preferred setup for running Django is :doc:`Apache with

     8 mod_wsgi </howto/deployment/modwsgi>`, many people use shared hosting, on

     9 which protocols such as FastCGI, SCGI or AJP are the only viable options. In

    10 some setups, these protocols may provide better performance than mod_wsgi_.

    11 

    12 .. admonition:: Note

    13 

    14     This document primarily focuses on FastCGI. Other protocols, such as SCGI

    15     and AJP, are also supported, through the ``flup`` Python package. See the

    16     Protocols_ section below for specifics about SCGI and AJP.

    17 

    18 Essentially, FastCGI is an efficient way of letting an external application

    19 serve pages to a Web server. The Web server delegates the incoming Web requests

    20 (via a socket) to FastCGI, which executes the code and passes the response back

    21 to the Web server, which, in turn, passes it back to the client's Web browser.

    22 

    23 Like mod_python, FastCGI allows code to stay in memory, allowing requests to be

    24 served with no startup time. Unlike mod_python_ (or `mod_perl`_), a FastCGI

    25 process doesn't run inside the Web server process, but in a separate,

    26 persistent process.

    27 

    28 .. _mod_wsgi: http://code.google.com/p/modwsgi/

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

    30 .. _mod_python: http://www.modpython.org/

    31 

    32 .. admonition:: Why run code in a separate process?

    33 

    34     The traditional ``mod_*`` arrangements in Apache embed various scripting

    35     languages (most notably PHP, Python and Perl) inside the process space of

    36     your Web server. Although this lowers startup time -- because code doesn't

    37     have to be read off disk for every request -- it comes at the cost of

    38     memory use. For mod_python, for example, every Apache process gets its own

    39     Python interpreter, which uses up a considerable amount of RAM.

    40 

    41     Due to the nature of FastCGI, it's even possible to have processes that run

    42     under a different user account than the Web server process. That's a nice

    43     security benefit on shared systems, because it means you can secure your

    44     code from other users.

    45 

    46 Prerequisite: flup

    47 ==================

    48 

    49 Before you can start using FastCGI with Django, you'll need to install flup_, a

    50 Python library for dealing with FastCGI. Version 0.5 or newer should work fine.

    51 

    52 .. _flup: http://www.saddi.com/software/flup/

    53 

    54 Starting your FastCGI server

    55 ============================

    56 

    57 FastCGI operates on a client-server model, and in most cases you'll be starting

    58 the FastCGI process on your own. Your Web server (be it Apache, lighttpd, or

    59 otherwise) only contacts your Django-FastCGI process when the server needs a

    60 dynamic page to be loaded. Because the daemon is already running with the code

    61 in memory, it's able to serve the response very quickly.

    62 

    63 .. admonition:: Note

    64 

    65     If you're on a shared hosting system, you'll probably be forced to use

    66     Web server-managed FastCGI processes. See the section below on running

    67     Django with Web server-managed processes for more information.

    68 

    69 A Web server can connect to a FastCGI server in one of two ways: It can use

    70 either a Unix domain socket (a "named pipe" on Win32 systems), or it can use a

    71 TCP socket. What you choose is a manner of preference; a TCP socket is usually

    72 easier due to permissions issues.

    73 

    74 To start your server, first change into the directory of your project (wherever

    75 your :doc:`manage.py </ref/django-admin>` is), and then run the

    76 :djadmin:`runfcgi` command::

    77 

    78     ./manage.py runfcgi [options]

    79 

    80 If you specify ``help`` as the only option after :djadmin:`runfcgi`, it'll

    81 display a list of all the available options.

    82 

    83 You'll need to specify either a :djadminopt:`socket`, a :djadminopt:`protocol`

    84 or both :djadminopt:`host` and :djadminopt:`port`. Then, when you set up your

    85 Web server, you'll just need to point it at the host/port or socket you

    86 specified when starting the FastCGI server. See the examples_, below.

    87 

    88 Protocols

    89 ---------

    90 

    91 Django supports all the protocols that flup_ does, namely fastcgi_, `SCGI`_ and

    92 `AJP1.3`_ (the Apache JServ Protocol, version 1.3). Select your preferred

    93 protocol by using the :djadminopt:`protocol=\<protocol_name\> <protocol>` option

    94 with ``./manage.py runfcgi`` -- where ``<protocol_name>`` may be one of:

    95 ``fcgi`` (the default), ``scgi`` or ``ajp``. For example::

    96 

    97     ./manage.py runfcgi protocol=scgi

    98 

    99 .. _flup: http://www.saddi.com/software/flup/

   100 .. _fastcgi: http://www.fastcgi.com/

   101 .. _SCGI: http://python.ca/scgi/protocol.txt

   102 .. _AJP1.3: http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html

   103 

   104 Examples

   105 --------

   106 

   107 Running a threaded server on a TCP port::

   108 

   109     ./manage.py runfcgi method=threaded host=127.0.0.1 port=3033

   110 

   111 Running a preforked server on a Unix domain socket::

   112 

   113     ./manage.py runfcgi method=prefork socket=/home/user/mysite.sock pidfile=django.pid

   114     

   115 .. admonition:: Socket security

   116 

   117     Django's default umask requires that the webserver and the Django fastcgi

   118     process be run with the same group **and** user. For increased security,

   119     you can run them under the same group but as different users. If you do

   120     this, you will need to set the umask to 0002 using the ``umask`` argument

   121     to ``runfcgi``.

   122 

   123 Run without daemonizing (backgrounding) the process (good for debugging)::

   124 

   125     ./manage.py runfcgi daemonize=false socket=/tmp/mysite.sock maxrequests=1

   126 

   127 Stopping the FastCGI daemon

   128 ---------------------------

   129 

   130 If you have the process running in the foreground, it's easy enough to stop it:

   131 Simply hitting ``Ctrl-C`` will stop and quit the FastCGI server. However, when

   132 you're dealing with background processes, you'll need to resort to the Unix

   133 ``kill`` command.

   134 

   135 If you specify the :djadminopt:`pidfile` option to :djadmin:`runfcgi`, you can

   136 kill the running FastCGI daemon like this::

   137 

   138     kill `cat $PIDFILE`

   139 

   140 ...where ``$PIDFILE`` is the ``pidfile`` you specified.

   141 

   142 To easily restart your FastCGI daemon on Unix, try this small shell script::

   143 

   144     #!/bin/bash

   145 

   146     # Replace these three settings.

   147     PROJDIR="/home/user/myproject"

   148     PIDFILE="$PROJDIR/mysite.pid"

   149     SOCKET="$PROJDIR/mysite.sock"

   150 

   151     cd $PROJDIR

   152     if [ -f $PIDFILE ]; then

   153         kill `cat -- $PIDFILE`

   154         rm -f -- $PIDFILE

   155     fi

   156 

   157     exec /usr/bin/env - \

   158       PYTHONPATH="../python:.." \

   159       ./manage.py runfcgi socket=$SOCKET pidfile=$PIDFILE

   160 

   161 Apache setup

   162 ============

   163 

   164 To use Django with Apache and FastCGI, you'll need Apache installed and

   165 configured, with `mod_fastcgi`_ installed and enabled. Consult the Apache

   166 documentation for instructions.

   167 

   168 Once you've got that set up, point Apache at your Django FastCGI instance by

   169 editing the ``httpd.conf`` (Apache configuration) file. You'll need to do two

   170 things:

   171 

   172     * Use the ``FastCGIExternalServer`` directive to specify the location of

   173       your FastCGI server.

   174     * Use ``mod_rewrite`` to point URLs at FastCGI as appropriate.

   175 

   176 .. _mod_fastcgi: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html

   177 

   178 Specifying the location of the FastCGI server

   179 ---------------------------------------------

   180 

   181 The ``FastCGIExternalServer`` directive tells Apache how to find your FastCGI

   182 server. As the `FastCGIExternalServer docs`_ explain, you can specify either a

   183 ``socket`` or a ``host``. Here are examples of both:

   184 

   185 .. code-block:: apache

   186 

   187     # Connect to FastCGI via a socket / named pipe.

   188     FastCGIExternalServer /home/user/public_html/mysite.fcgi -socket /home/user/mysite.sock

   189 

   190     # Connect to FastCGI via a TCP host/port.

   191     FastCGIExternalServer /home/user/public_html/mysite.fcgi -host 127.0.0.1:3033

   192 

   193 In either case, the file ``/home/user/public_html/mysite.fcgi`` doesn't

   194 actually have to exist. It's just a URL used by the Web server internally -- a

   195 hook for signifying which requests at a URL should be handled by FastCGI. (More

   196 on this in the next section.)

   197 

   198 .. _FastCGIExternalServer docs: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html#FastCgiExternalServer

   199 

   200 Using mod_rewrite to point URLs at FastCGI

   201 ------------------------------------------

   202 

   203 The second step is telling Apache to use FastCGI for URLs that match a certain

   204 pattern. To do this, use the `mod_rewrite`_ module and rewrite URLs to

   205 ``mysite.fcgi`` (or whatever you specified in the ``FastCGIExternalServer``

   206 directive, as explained in the previous section).

   207 

   208 In this example, we tell Apache to use FastCGI to handle any request that

   209 doesn't represent a file on the filesystem and doesn't start with ``/media/``.

   210 This is probably the most common case, if you're using Django's admin site:

   211 

   212 .. code-block:: apache

   213 

   214     <VirtualHost 12.34.56.78>

   215       ServerName example.com

   216       DocumentRoot /home/user/public_html

   217       Alias /media /home/user/python/django/contrib/admin/media

   218       RewriteEngine On

   219       RewriteRule ^/(media.*)$ /$1 [QSA,L,PT]

   220       RewriteCond %{REQUEST_FILENAME} !-f

   221       RewriteRule ^/(.*)$ /mysite.fcgi/$1 [QSA,L]

   222     </VirtualHost>

   223 

   224 .. _mod_rewrite: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html

   225 

   226 Django will automatically use the pre-rewrite version of the URL when

   227 constructing URLs with the ``{% url %}`` template tag (and similar methods).

   228 

   229 lighttpd setup

   230 ==============

   231 

   232 lighttpd_ is a lightweight Web server commonly used for serving static files. It

   233 supports FastCGI natively and, thus, is a good choice for serving both static

   234 and dynamic pages, if your site doesn't have any Apache-specific needs.

   235 

   236 .. _lighttpd: http://www.lighttpd.net/

   237 

   238 Make sure ``mod_fastcgi`` is in your modules list, somewhere after

   239 ``mod_rewrite`` and ``mod_access``, but not after ``mod_accesslog``. You'll

   240 probably want ``mod_alias`` as well, for serving admin media.

   241 

   242 Add the following to your lighttpd config file:

   243 

   244 .. code-block:: lua

   245 

   246     server.document-root = "/home/user/public_html"

   247     fastcgi.server = (

   248         "/mysite.fcgi" => (

   249             "main" => (

   250                 # Use host / port instead of socket for TCP fastcgi

   251                 # "host" => "127.0.0.1",

   252                 # "port" => 3033,

   253                 "socket" => "/home/user/mysite.sock",

   254                 "check-local" => "disable",

   255             )

   256         ),

   257     )

   258     alias.url = (

   259         "/media" => "/home/user/django/contrib/admin/media/",

   260     )

   261 

   262     url.rewrite-once = (

   263         "^(/media.*)$" => "$1",

   264         "^/favicon\.ico$" => "/media/favicon.ico",

   265         "^(/.*)$" => "/mysite.fcgi$1",

   266     )

   267 

   268 Running multiple Django sites on one lighttpd

   269 ---------------------------------------------

   270 

   271 lighttpd lets you use "conditional configuration" to allow configuration to be

   272 customized per host. To specify multiple FastCGI sites, just add a conditional

   273 block around your FastCGI config for each site::

   274 

   275     # If the hostname is 'www.example1.com'...

   276     $HTTP["host"] == "www.example1.com" {

   277         server.document-root = "/foo/site1"

   278         fastcgi.server = (

   279            ...

   280         )

   281         ...

   282     }

   283 

   284     # If the hostname is 'www.example2.com'...

   285     $HTTP["host"] == "www.example2.com" {

   286         server.document-root = "/foo/site2"

   287         fastcgi.server = (

   288            ...

   289         )

   290         ...

   291     }

   292 

   293 You can also run multiple Django installations on the same site simply by

   294 specifying multiple entries in the ``fastcgi.server`` directive. Add one

   295 FastCGI host for each.

   296 

   297 Cherokee setup

   298 ==============

   299 

   300 Cherokee is a very fast, flexible and easy to configure Web Server. It

   301 supports the widespread technologies nowadays: FastCGI, SCGI, PHP, CGI, SSI,

   302 TLS and SSL encrypted connections, Virtual hosts, Authentication, on the fly

   303 encoding, Load Balancing, Apache compatible log files, Data Base Balancer,

   304 Reverse HTTP Proxy and much more.

   305 

   306 The Cherokee project provides a documentation to `setting up Django`_ with Cherokee.

   307 

   308 .. _setting up Django: http://www.cherokee-project.com/doc/cookbook_django.html

   309 

   310 Running Django on a shared-hosting provider with Apache

   311 =======================================================

   312 

   313 Many shared-hosting providers don't allow you to run your own server daemons or

   314 edit the ``httpd.conf`` file. In these cases, it's still possible to run Django

   315 using Web server-spawned processes.

   316 

   317 .. admonition:: Note

   318 

   319     If you're using Web server-spawned processes, as explained in this section,

   320     there's no need for you to start the FastCGI server on your own. Apache

   321     will spawn a number of processes, scaling as it needs to.

   322 

   323 In your Web root directory, add this to a file named ``.htaccess``:

   324 

   325 .. code-block:: apache

   326 

   327     AddHandler fastcgi-script .fcgi

   328     RewriteEngine On

   329     RewriteCond %{REQUEST_FILENAME} !-f

   330     RewriteRule ^(.*)$ mysite.fcgi/$1 [QSA,L]

   331 

   332 Then, create a small script that tells Apache how to spawn your FastCGI

   333 program. Create a file ``mysite.fcgi`` and place it in your Web directory, and

   334 be sure to make it executable:

   335 

   336 .. code-block:: python

   337 

   338     #!/usr/bin/python

   339     import sys, os

   340 

   341     # Add a custom Python path.

   342     sys.path.insert(0, "/home/user/python")

   343 

   344     # Switch to the directory of your project. (Optional.)

   345     # os.chdir("/home/user/myproject")

   346 

   347     # Set the DJANGO_SETTINGS_MODULE environment variable.

   348     os.environ['DJANGO_SETTINGS_MODULE'] = "myproject.settings"

   349 

   350     from django.core.servers.fastcgi import runfastcgi

   351     runfastcgi(method="threaded", daemonize="false")

   352 

   353 Restarting the spawned server

   354 -----------------------------

   355 

   356 If you change any Python code on your site, you'll need to tell FastCGI the

   357 code has changed. But there's no need to restart Apache in this case. Rather,

   358 just reupload ``mysite.fcgi``, or edit the file, so that the timestamp on the

   359 file will change. When Apache sees the file has been updated, it will restart

   360 your Django application for you.

   361 

   362 If you have access to a command shell on a Unix system, you can accomplish this

   363 easily by using the ``touch`` command::

   364 

   365     touch mysite.fcgi

   366 

   367 Serving admin media files

   368 =========================

   369 

   370 Regardless of the server and configuration you eventually decide to use, you

   371 will also need to give some thought to how to serve the admin media files. The

   372 advice given in the :ref:`modpython <serving-the-admin-files>` documentation

   373 is also applicable in the setups detailed above.

   374 

   375 Forcing the URL prefix to a particular value

   376 ============================================

   377 

   378 Because many of these fastcgi-based solutions require rewriting the URL at

   379 some point inside the Web server, the path information that Django sees may not

   380 resemble the original URL that was passed in. This is a problem if the Django

   381 application is being served from under a particular prefix and you want your

   382 URLs from the ``{% url %}`` tag to look like the prefix, rather than the

   383 rewritten version, which might contain, for example, ``mysite.fcgi``.

   384 

   385 Django makes a good attempt to work out what the real script name prefix

   386 should be. In particular, if the Web server sets the ``SCRIPT_URL`` (specific

   387 to Apache's mod_rewrite), or ``REDIRECT_URL`` (set by a few servers, including

   388 Apache + mod_rewrite in some situations), Django will work out the original

   389 prefix automatically.

   390 

   391 In the cases where Django cannot work out the prefix correctly and where you

   392 want the original value to be used in URLs, you can set the

   393 :setting:`FORCE_SCRIPT_NAME` setting in your main ``settings`` file. This sets the

   394 script name uniformly for every URL served via that settings file. Thus you'll

   395 need to use different settings files if you want different sets of URLs to

   396 have different script names in this case, but that is a rare situation.

   397 

   398 As an example of how to use it, if your Django configuration is serving all of

   399 the URLs under ``'/'`` and you wanted to use this setting, you would set

   400 ``FORCE_SCRIPT_NAME = ''`` in your settings file.