Setting up FastCGI apps on WebFaction

For the high-resolution orbital slice viewer on the Visible Orbit website, I had to setup wlziipsrv, a fork of the iipsrv large tiled image server. This is a FastCGI app, which means that, unlike a normal CGI which is started up for each request, one runs a number of these processes in daemon mode, and the front-end webserver communicates with them using the fastcgi protocol.

The end-result is this web-based high-resolution image viewer, which you can use to explore several thousands of microsocopic slices of human eyes. This is slice 41 of the S2897L registered set:


To make a long story short, there was no documentation on how to do this on a WebFaction shared host, a problem this post will try to remedy.

The main idea of the solution is to compile and run the lighttpd web server as a custom app, and then to map the fastcgi URL to that app. You can then configure lighttpd to run your fastcgi app. In the following sections, I show you how to do this.

Configure custom app

Using the webfaction panel, create a custom app as shown in the following screenshot.


Note down the port number that webfaction has allocated for this app. We will setup lighttpd to listen at this port for local access by the frontend webfaction webserver.

Using the website configuration screen of the webfaction panel, associate your new custom app to the fastcgi URL that will be requested. In my case, I have configured the front-end code to invoke the wlziipsrv fastcgi by going to /cgi-bin/wlziipsrv.fcgi. The configuration looks like this:


Here you are telling webfaction that if any client requests /cgi-bin/wlziipsrv.fcgi, it should connect them with whatever’s running behind the specially allocated custom app port. Next we will make sure that lighttpd will answer those requests.

Configure lighttpd

After building lighttpd with:

cd lighttpd_source_dir
./configure --prefix=$HOME/opt
make install

I created a config file such as the following one in the new custom app directory. Most important is that server.port matches the port number webfaction assigned. I also gave the file a name which will probably not be used by other lighttpd users on the system, namely visorb-lighttpd.conf.

server.document-root = "/home/myusername/webapps/wp_visorb_2017/"

server.port = 22430

server.modules += ( "mod_fastcgi" )

var.mypath = "/home/myusername/webapps/visorb_iipsrv/"

# uncomment this and start with -D to debug requests as they
# come in
#debug.log-request-handling = "enable"

mimetype.assign = (
  ".html" => "text/html", 
  ".txt" => "text/plain",
  ".jpg" => "image/jpeg",
  ".png" => "image/png" 

# webfaction frontend strips away the path; we end up here with only /
# however, we KNOW it must be /cgi-bin/wlziipsrv.fcgi
fastcgi.server = ( "/" =>
  (( "socket" => var.mypath + "wlziipsrv-fastcgi.socket",
     "check-local" => "disable",
     "min-procs" => 1,
     "max-procs" => 1,
     "bin-path" => "/home/myusername/build/WlzIIPSrv/src/wlziipsrv.fcgi",
     "bin-environment" => (
        "LOGFILE" => var.mypath + "iipsrv.log",
        "VERBOSITY" => "5",
        "MAX_IMAGE_CACHE_SIZE" => "10",
        "FILENAME_PATTERN" => "_pyr_",
        "JPEG_QUALITY" => "50",
        "MAX_CVT" => "3000"

Test lighttpd by doing:

~/opt/bin/lighttpd -t -f visorb-lighttpd.conf
~/opt/bin/lighttpd -D -f visorb-lighttpd.conf

This last command will keep lighttpd running in the foreground just so you can see any log messages. Press Ctrl-C to exit.

Setup cron to keep lighttpd running

Next we need to ensure that lighttpd is kept running. On webfaction, it seems that the only way to do this, is with a cronjob.

I made the following bash script that we will configure cron to invoke every 10 minutes. The script will start lighttpd if it is not already running.


VO_RUNNING=$(ps ax | grep visorb-lighttpd | grep -v grep)

if [ -z "$VO_RUNNING" ];
then $HOME/opt/sbin/lighttpd -f $HOME/webapps/visorb_iipsrv/visorb-lighttpd.conf;

I installed the script using crontab -e, adding the following line:

*/10 * * * * /home/myusername/webapps/visorb_iipsrv/


Using this method, you can reroute any fastcgi request to a custom app handled by lighttpd, and then have lighttpd manage the fastcgi processes.

For now this does exactly what I want. However, I can easily map multiple URLs to the same lighttpd using the webfaction panel. Ideally, I would then have the single lighttpd reroute to different fastcgi apps.

However, it seems that webfaction strips away the URL path information before passing the request on to lighttpd (this is what I saw in debug mode), which is why I currently have to map / to the wlziipsrv.fcgi in the lighttpd configuration. Fortunately, lighttpd is super light-weight (currently 1.4MB RSS), and having a separate lighttpd process per type of fastcgi application is more robust in any case.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.