Modular Lighttpd Configurations

You might have asked yourself how to split lighttpd's configuration files apart or how to simply create configuration templates for several sites. This will show you how.

Thanks to lighttpd trac #1221

Here is what we are going to achieve with this little guide:

• /etc/lighttpd/
  • lighttpd.conf
  • incl-fcgi-django.conf (a template for serving django via fcgi)
  • incl-static.conf (another template for serving static sites)
  • sites/ (a directory containg per-site configs which will use the templates)
    • example.com.conf
    • originell.org.conf

Before we move on here is a small overview how I handle my sites. As an example serves a simple django project (my webframework of choice).

• /home/sites/
  • example.com/
    • various folders and virtualenvs
    • exampleproject/
      • django-specific files
      • media/
        • admin/ (images and stylesheets for the backend)
        • static/ (images and stylesheets for the frontend)
• /var/logs/lighttpd/sites/
  • example.com/
    • here I keep access and error logs

Creating our templates

Dive in head first!

fastcgi.server = (
    "/" + project +".fcgi" => (
        "main" => (
             "host" => "127.0.0.1",
             "port" => port,
             "check-local" => "disable"
        )
    ),
)

var.dir = "/home/sites/" + domain +"/"+ project +"/"
alias.url = (
    "/media/" => dir+"media/admin",
    "/static/" => dir +"media/static/",
)

url.rewrite-once = (
     "^(/media.*)$" => "$1",
     "^(/static.*)$" => "$1",
     "^/favicon\.ico$" => "/static/favicon.ico",
     "^(/.*)$" => "/"+ project +".fcgi$1",
 )

server.errorlog = "/var/log/lighttpd/"+ domain +"/error.log"
accesslog.filename = "/var/log/lighttpd/"+ domain +"/access.log"

I guess all of this is pretty selfexplanary. domain, project and port are variables which we will define in our site-specific settings. Remember that the above is just a template!

Here the promised incl-static.conf:

server.document-root = "/home/sites/" + domain +"/web/"
accesslog.filename = "/var/log/lighttpd/"+ domain +"/access.log"

A lot simpler, heh? ;-)

Setting up a site-specific config

First we create a sites dir inside /etc/lighttpd/

mkdir sites
cd sites

Now we create a site specific config for example.com.

[vim/emacs/nano] example.com.conf

and the config:

$HTTP["host"] =~ "(^|\.)example.com$" {
    var.domain = "example.com"
    var.project = "exampleproject"
    var.port = 1337

    include "incl-fcgi-django.conf"
}

First we have our mighty regex which matches example.com, with and without prepending www. Then we define the variables which we wrote into our template and last but not least we include our previously created template. Note that "include" always works it's way from lighttpd's base config directory (in our case, as with most distros, this is /etc/lighttpd/)

When serving a static page, things get amazingly short:

$HTTP["host"] =~ "(^|\.)originell.org$" {
    var.domain = "originell.org"
    include "incl-static.conf"
}

You might now ask yourself: How do I tell lighttpd where these files live?

Magic include_shell

Lighttpd has a powerful include variant: include_shell.

So putting this at the end of the lighttpd.conf

include_shell "find sites -name '*.conf' -exec cat {} \;"

All shellpros will already see what this is doing. For everyone else:

1. on startup time, lighttpd parses it's config
2. it sees include_shell and runs the command inside that
3. In our case this runs find which in turn searches our sites/ directory for files ending with .conf and then runs cat
4. lighttpd gets the output and parses it like it would be inline.

Easy and powerful as hell and pretty DRY.

Thanks for reading