The web server of choice here at Streamy is Lighttpd. Written in C, it’s designed for performance, efficiency, security and concurrency. In addition to being one of the best performing http daemons for serving static content, it’s integration with FastCGI makes it simple to turn applications in almost any language into a CGI script with little or no code modification.  The communication between your script’s process and lighttpd is done with unix sockets or via tcp, making it easy to load-balance and have scripts that run on remote nodes.

Lighttpd makes it very easy to launch your cgi processes automatically without having to worry much about the interface.  However, debugging them like this can be arduous, if even possible.  When you want to get serious about developing fastcgi apps, you’ll need to run them yourself using spawn-fcgi and can then debug them using fcgi-debug.  spawn-fcgi is a way to separate the launching of the web server from the launching of the cgi proccess(es).  fcgi-debug is a nifty program that sits in between the web server and your script that allows you to see everything that’s going on.

A HUGE thanks to stbuehler who not only develops and maintains both of these applications but also spent time helping me debug a nasty issue we were having at Streamy.  IRC (and for developers, Freenode) is still one of the most powerful social networks out there!

Let’s imagine you have a compiled binary FastCGI program called myscript and you want to debug it.  At first, a simple lighttpd configuration for it might look like this:

fastcgi.server ( "/myscript" => ( "myscript" => (
  "socket" => "/home/user/myscript.sock",
  "bin-path" => "/home/user/myscript",
  "min-procs" => 1,
  "max-procs" => 1
)))

Full configuration information for mod_fastcgi is available here

The first step towards debugging is to change from Lighttpd spawning the process to using spawn-fcgi.  There are more detailed instructions available here and here, but in short what you will do is modify your lighty config to just point to the socket.  Remove bin-path and all process/load settings, otherwise you will run into conflicts.

fastcgi.server ( "/myscript" => ( "myscript" => (
  "socket" => "/home/user/myscript.sock"
)))

If we were not interested in debugging the interface/communications between lighttpd and fastcgi, we would spawn the script like this:

spawn-fcgi -s /home/user/myscript.sock -C 0 -F 1 -n -- /home/user/myscript

Adding fcgi-debug in the middle is as easy as calling it first rather than the script:

spawn-fcgi -s /home/user/myscript.sock -C 0 -F 1 -n -- fcgi-debug /home/user/myscript

You should now see lots of debug information directly to stdout.

You should also ensure that you have fastcgi debug turned on in your lighttpd logs. This is done with the setting:

server.errorlog = "/home/user/lighttpd_error.log"
fastcgi.debug = 1

If using fcgi-debug, you are required to use spawn-fcgi 1.6.2 rather than the one packaged with your lighttpd installation. spawn-fcgi 1.4.22 will run but will not show any debug output.