“This separation allows server and application processes to be restarted independently — an important consideration for busy web sites. It also facilitates per-application security policies — important for ISPs and web hosting companies.”

The lighttpd web server includes the binary spawn-fcgi, which as the name suggests, allows you to spawn FastCGI processes. This can be done independently of the web server processes.

Lighttpd’s FastCGI module, mod_fastcgi is well documented here, but there are a lot of arguments to sift through and it can be a process of trial and error to get a working configuration.

In this example, we will review how to configure lighttpd and spawn-fcgi on separate servers. The web server which will run lighttpd and host all html, images, css, etc. files. The FastCGI server will host all PHP files.

Here is the relevant excerpt from lighttpd.conf on Server A: (the server hosting the html, images, css, etc)

server.modules = (
                          [ ... ]
                          "mod_fastcgi",
                          [ ... ]
                        )
[ ... ]
$HTTP["host"] =~ "(^|\.)iamtgc\.com$" {
   server.name = "iamtgc.com"
   server.document-root = "/lighttpd/" + server.name
   fastcgi.server         =  ( ".php" =>
                               ((
                                   "host" => "192.168.25.120",
                                   "port" => 9999,
                                   "docroot" => "/php/iamtgc.com",
                                   "check-local" => "disable"
                               ))
                             )
   accesslog.filename = "/var/log/lighttpd/" + server.name + "-access.log"
}
[ ... ]

On Server B (where the FastCGI processes are running) you start the FastCGI server like this:

# spawn-fcgi -f /usr/local/bin/php-cgi -a 192.168.25.120 -p 9999

Note, the php needs to exist in the docroot reference above, in this case /php/iamtgc.com. The bind address (-a) and port (-p) also correspond to the host and port variables referenced in lighttpd.conf on Server A.

Also note, php-cgi can be replaced with something like dispatch.fcgi in the case of Ruby on Rails or a similar fcgi file for Django as seen here. In both of these cases, other changes would be also required to Server A’s lighttpd.conf.

In this article I outline the steps which I took that lead to a successful configuration. This article is not explanation on how to install Django, lighttpd or any of the associated components. It is, however, my hope that this article will help you get Django running with lighttpd and fastcgi without the frustration.


This example assumes you, jdoe, will set up a django-projects directory to contain multiple django projects, and your first project is a blog.

$ mkdir /home/jdoe/django-projects

$ cd /home/jdoe/django-projects

$ django-admin.py startproject blog

Now we need to setup your fastcgi file, we’ll place this in /home/jdoe/www/blog/mysite.fcgi, this is assuming your document-root is /home/jdoe/www/blog.

#!/usr/pkg/bin/python2.4
import sys, os

# Add a custom Python path.
sys.path.insert(0, "/home/jdoe/django-projects")

# Switch to the directory of your project. (Optional.)
# os.chdir("/home/jdoe/django-projects/blog")

# Set the DJANGO_SETTINGS_MODULE environment variable.
os.environ['DJANGO_SETTINGS_MODULE'] = "blog.settings"

from django.core.servers.fastcgi import runfastcgi
runfastcgi(method="threaded", daemonize="false")

Okay, now that you’ve set up your fcgi file, let’s test it out

$ python2.4 ./mysite.fcgi
WSGIServer: missing FastCGI param REQUEST_METHOD required by WSGI!
WSGIServer: missing FastCGI param SERVER_NAME required by WSGI!
WSGIServer: missing FastCGI param SERVER_PORT required by WSGI!
WSGIServer: missing FastCGI param SERVER_PROTOCOL required by WSGI!
Traceback (most recent call last):
  File "/usr/pkg/lib/python2.4/site-packages/flup-0.5-py2.4.egg/flup/server/fcgi_base.py", line 558, in run
    protocolStatus, appStatus = self.server.handler(self)
  File "/usr/pkg/lib/python2.4/site-packages/flup-0.5-py2.4.egg/flup/server/fcgi_base.py", line 1112, in handler
    result = self.application(environ, start_response)
  File "/usr/pkg/lib/python2.4/site-packages/Django-0.95.1-py2.4.egg/django/core/handlers/wsgi.py", line 148, in __call__
    response = self.get_response(request.path, request)
  File "/usr/pkg/lib/python2.4/site-packages/Django-0.95.1-py2.4.egg/django/core/handlers/base.py", line 59, in get_response
    response = middleware_method(request)
  File "/usr/pkg/lib/python2.4/site-packages/Django-0.95.1-py2.4.egg/django/middleware/common.py", line 40, in process_request
    if settings.APPEND_SLASH and (old_url[1][-1] != '/') and ('.' not in old_url[1].split('/')[-1]):
IndexError: string index out of range
Content-Type: text/html

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>Unhandled Exception</title>
</head><body>
<h1>Unhandled Exception</h1>
<p>An unhandled exception was thrown by the application.</p>
</body></html>

This is the output you can expect to see, if you happen to get the following output instead

$ python2.4 ./mysite.fcgi
Traceback (most recent call last):
  File "./mysite.fcgi", line 15, in ?
    runfastcgi(method="threaded", daemonize="false")
TypeError: runfastcgi() got an unexpected keyword argument 'method'

You should replace

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

in mysite.fcgi with

runfastcgi(["method=threaded", "daemonize=false"])

Now the last step is setting up lighttpd, the following sets up django in your domain blog.domain.tld, but the important part is the fastcgi.server block. The primary change that I had to make from the Django documentation is the addition of the bin-path variable.

$HTTP["host"] =~ "(^|\.)blog\.domain\.tld$" {
        server.document-root = "/home/jdoe/www/blog"
        accesslog.filename = "/var/log/lighttpd/blog.domain.tld-access.log"

        fastcgi.server = (
                ".fcgi" => (
                        "localhost" => (
                                "bin-path" => "/home/jdoe/www/blog/mysite.fcgi",
                                "socket" => "/home/jdoe/tmp/mysite.sock",
                                "check-local" => "disable",
                                "min-procs" => 2,
                                "max-procs" => 4,
                        )
                ),
        )

        alias.url = (
                "/media/" => "/home/jdoe/www/blog/media/",
        )
        url.rewrite-once = (
                "^(/media.*)$" => "$1",
                "^/favicon\.ico$" => "/media/favicon.ico",
                "^(/.*)$" => "/mysite.fcgi$1",
        )
}