Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added draft of docs/fastcgi.txt. Haven't finished editing this yet.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@3175 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 76448d0c4bc820400cce544cf78427f9c1349f19 1 parent 32228d2
Adrian Holovaty authored June 20, 2006

Showing 1 changed file with 262 additions and 0 deletions. Show diff stats Hide diff stats

  1. 262  docs/fastcgi.txt
262  docs/fastcgi.txt
... ...
@@ -0,0 +1,262 @@
  1
+==============================
  2
+How to use Django with FastCGI
  3
+==============================
  4
+
  5
+Although the current preferred setup for running Django is Apache_ with
  6
+`mod_python`_, many people use shared hosting, on which FastCGI_ is the only
  7
+viable option. In some setups, FastCGI also allows better security -- and,
  8
+possibly, better performance -- than mod_python.
  9
+
  10
+Essentially, FastCGI is an efficient way of letting an external application
  11
+serve pages to a Web server. The Web server delegates the incoming Web requests
  12
+(via a socket) to FastCGI, which executes the code and passes the response back
  13
+to the Web server, which, in turn, passes it back to the client's Web browser.
  14
+
  15
+Like mod_python, FastCGI allows code to stay in memory, allowing requests to be
  16
+served with no startup time. Unlike mod_python (or `mod_perl`_), a FastCGI
  17
+process doesn't run inside the Web server process, but in a separate,
  18
+persistent process.
  19
+
  20
+.. _Apache: http://httpd.apache.org/
  21
+.. _mod_python: http://www.modpython.org/
  22
+.. _mod_perl: http://perl.apache.org/
  23
+
  24
+.. admonition:: Why run code in a separate process?
  25
+
  26
+    The traditional ``mod_*`` arrangements in Apache embed various scripting
  27
+    languages (most notably PHP, Python and Perl) inside the process space of
  28
+    your Web server. Although this lowers startup time -- because code doesn't
  29
+    have to be read off disk for every request -- it comes at the cost of
  30
+    memory use. For mod_python, for example, every Apache process gets its own
  31
+    Python interpreter, which uses up a considerable amount of RAM.
  32
+
  33
+    Due to the nature of FastCGI, it's even possible to have processes that run
  34
+    under a different user account than the Web server process. That's a nice
  35
+    security benefit on shared systems, because it means you can secure your
  36
+    code from other users.
  37
+
  38
+Starting your FastCGI server
  39
+============================
  40
+
  41
+FastCGI operates on a client-server model, and in most cases you'll be starting
  42
+the FastCGI process on your own. Your Web server (be it Apache, lighttpd, or
  43
+otherwise) only contacts your Django-FastCGI process when the server needs a
  44
+dynamic page to be loaded. Because the daemon is already running with the code
  45
+in memory, it's able to serve the response very quickly.
  46
+
  47
+.. admonition:: Note
  48
+
  49
+    If you're on a shared hosting system, you'll probably be forced to use
  50
+    Web server-managed FastCGI processes. See the section below on running
  51
+    Django with Web server-managed processes for more information.
  52
+
  53
+A Web server can connect to a FastCGI server in one of two ways: It can use
  54
+either a Unix domain socket (a "named pipe" on Win32 systems), or it can use a
  55
+TCP socket. What you choose is a manner of preference; a TCP socket is usually
  56
+easier due to permissions issues.
  57
+
  58
+To start your server, first change into the directory of your project (wherever
  59
+your ``manage.py`` is), and then run ``manage.py`` with the ``runfcgi`` option::
  60
+
  61
+    ./manage.py runfcgi [options]
  62
+
  63
+If you specify ``help`` as the only option after ``runfcgi``, it'll display a
  64
+list of all the available options.
  65
+
  66
+You'll need to specify either a ``socket`` or both ``host`` and ``port``. Then,
  67
+when you set up your Web server, you'll just need to point it at the host/port
  68
+or socket you specified when starting the FastCGI server.
  69
+
  70
+Examples
  71
+--------
  72
+
  73
+Running a threaded server on a TCP port::
  74
+
  75
+    ./manage.py runfcgi method=threaded host=127.0.0.1 port=3033
  76
+
  77
+Running a preforked server on a Unix domain socket::
  78
+
  79
+    ./manage.py runfcgi method=prefork socket=/home/user/mysite.sock pidfile=django.pid
  80
+
  81
+Run without daemonizing (backgrounding) the process (good for debugging)::
  82
+
  83
+    ./manage.py runfcgi daemonize=false socket=/tmp/mysite.sock
  84
+
  85
+Stopping the FastCGI daemon
  86
+---------------------------
  87
+
  88
+If you have the process running in the foreground, it's easy enough to stop it:
  89
+Simply hitting ``Ctrl-C`` will stop and quit the FastCGI server. However, when
  90
+you're dealing with background processes, you'll need to resort to the Unix
  91
+``kill`` command.
  92
+
  93
+If you specify the ``pidfile`` option to your ``manage.py runfcgi``, you can
  94
+kill the running FastCGI daemon like this::
  95
+
  96
+    kill `cat $PIDFILE`
  97
+
  98
+...where ``$PIDFILE`` is the ``pidfile`` you specified.
  99
+
  100
+To easily restart your FastCGI daemon on Unix, try this small shell script::
  101
+
  102
+    #!/bin/bash
  103
+
  104
+    # Replace these three settings.
  105
+    PROJDIR="/home/user/myproject"
  106
+    PIDFILE="$PROJDIR/mysite.pid"
  107
+    SOCKET="$PROJDIR/mysite.sock"
  108
+
  109
+    cd $PROJDIR
  110
+    if [ -f $PIDFILE ]; then
  111
+        kill `cat -- $PIDFILE`
  112
+        rm -f -- $PIDFILE
  113
+    fi
  114
+
  115
+    exec /usr/bin/env - \
  116
+      PYTHONPATH="../python:.." \
  117
+      ./manage.py runfcgi socket=$SOCKET pidfile=$PIDFILE
  118
+
  119
+Apache setup
  120
+============
  121
+
  122
+To use Django with Apache and FastCGI, you'll need Apache installed and
  123
+configured, with mod_fastcgi installed and enabled. Consult the Apache
  124
+documentation for instructions.
  125
+
  126
+Add the following to your ``httpd.conf``::
  127
+
  128
+    # Connect to FastCGI via a socket / named pipe
  129
+    FastCGIExternalServer /home/user/public_html/mysite.fcgi -socket /home/user/mysite.sock
  130
+    # Connect to FastCGI via a TCP host/port
  131
+    # FastCGIExternalServer /home/user/public_html/mysite.fcgi -host 127.0.0.1:3033
  132
+
  133
+    <VirtualHost 64.92.160.91>
  134
+      ServerName mysite.com
  135
+      DocumentRoot /home/user/public_html
  136
+      Alias /media /home/user/python/django/contrib/admin/media
  137
+      RewriteEngine On
  138
+      RewriteRule ^/(media.*)$ /$1 [QSA,L]
  139
+      RewriteCond %{REQUEST_FILENAME} !-f
  140
+      RewriteRule ^/(.*)$ /mysite.fcgi/$1 [QSA,L]
  141
+    </VirtualHost>
  142
+
  143
+Note that while you have to specify a mysite.fcgi, that this file doesn't
  144
+actually have to exist.  It is just an internal URL to the webserver which
  145
+signifies that any requests to that URL will go to the external FastCGI
  146
+server.
  147
+
  148
+LigHTTPd Setup
  149
+==============
  150
+
  151
+LigHTTPd is a light-weight asynchronous web-server, which is commonly used
  152
+for serving static files.  However, it supports FastCGI natively, and as such
  153
+is a very good choice for serving both static and dynamic media, if your site
  154
+does not have any apache-specific components.
  155
+
  156
+Make sure ``mod_fastcgi`` is in your modules list, somewhere after
  157
+mod_rewrite and mod_access, but not after mod_accesslog.  You'll probably
  158
+want mod_alias as well, for serving admin media.
  159
+
  160
+Add the following to your lighttpd config file::
  161
+
  162
+    server.document-root = "/home/user/public_html"
  163
+    fastcgi.server = (
  164
+        "/mysite.fcgi" => (
  165
+            "main" => (
  166
+                # Use host / port instead of socket for TCP fastcgi
  167
+                # "host" => "127.0.0.1",
  168
+                # "port"  => 3033,
  169
+                "socket" => "/home/user/mysite.sock",
  170
+                "check-local" => "disable",
  171
+            )
  172
+        ),
  173
+    )
  174
+    alias.url = (
  175
+        "/media/" => "/home/user/django/contrib/admin/media/",
  176
+    )
  177
+
  178
+    url.rewrite-once = (
  179
+        "^(/media.*)$" => "$1",
  180
+        "^/favicon\.ico$" => "/media/favicon.ico",
  181
+        "^(/.*)$" => "/mysite.fcgi$1",
  182
+    )
  183
+
  184
+Running multiple django sites on one LigHTTPd
  185
+---------------------------------------------
  186
+
  187
+LigHTTPd allows you to use what is called conditional configuration to allow
  188
+configuration to be customized per-host.  In order to specify multiple fastcgi
  189
+sites, simply add a conditional block around your fastcgi config for each site::
  190
+
  191
+    $HTTP["host"] == "www.website1.com" {
  192
+        server.document-root = "/foo/site1"
  193
+        fastcgi.server = (
  194
+           ...
  195
+        )
  196
+        ...
  197
+    }
  198
+
  199
+    $HTTP["host"] == "www.website2.com" {
  200
+        server.document-root = "/foo/site2"
  201
+        fastcgi.server = (
  202
+           ...
  203
+        )
  204
+        ...
  205
+    }
  206
+
  207
+You can also run multiple django installations on the same site simply by
  208
+specifying multiple entries in the ``fastcgi.server`` directive, add one
  209
+fastcgi host for each.
  210
+
  211
+Running Django on a shared-hosting provider
  212
+===========================================
  213
+
  214
+For many users on shared-hosting providers, you aren't able to run your own
  215
+server daemons nor do they have access to the httpd.conf of their webserver.
  216
+However, it is still possible to run Django using webserver-spawned processes.
  217
+
  218
+.. admonition:: Note
  219
+
  220
+    If you are using webserver-managed processes, there's no need for you
  221
+    to start the FastCGI server on your own.  Apache will spawn a number
  222
+    of processes, scaling as it needs to.
  223
+
  224
+In your web root directory, add this to a file named .htaccess ::
  225
+
  226
+    AddHandler fastcgi-script .fcgi
  227
+    RewriteEngine On
  228
+    RewriteCond %{REQUEST_FILENAME} !-f
  229
+    RewriteRule ^/(.*)$ /mysite.fcgi/$1 [QSA,L]
  230
+
  231
+Now you must add a small shim script in order for apache to properly
  232
+spawn your FastCGI program.  Create a mysite.fcgi and place it in your
  233
+web directory, making it executable ::
  234
+
  235
+    #!/usr/bin/python
  236
+    import sys, os
  237
+
  238
+    # add a custom pythonpath
  239
+    sys.path.insert(0, "/home/user/python")
  240
+
  241
+    # switch to the directory of your project. (optional)
  242
+    # os.chdir("/home/user/myproject")
  243
+
  244
+    # change to the name of your app's settings module
  245
+    os.environ['DJANGO_SETTINGS_MODULE'] = "myproject.settings"
  246
+
  247
+    from django.core.servers.fastcgi import runfastcgi
  248
+    runfastcgi(["method=threaded", "daemonize=false"])
  249
+
  250
+Restarting the spawned server
  251
+-----------------------------
  252
+
  253
+If you change the code of your site, to make apache re-load your django
  254
+application, you do not need to restart the server.  Simply re-upload or
  255
+edit your ``mysite.fcgi`` in such a way that the timestamp on the file
  256
+will change.  When apache sees that the file has been updated, it will
  257
+restart your django application for you.
  258
+
  259
+If you have access to a command shell on a unix system, restarting the
  260
+server can be done with the ``touch`` command::
  261
+
  262
+    touch mysite.fcgi

0 notes on commit 76448d0

Please sign in to comment.
Something went wrong with that request. Please try again.