Lisp, Programming

Tutorial: Running Hunchentoot on Webfaction

Lately I’ve been playing around with the Lisp web framework Weblocks that runs on Hunchentoot, and it seemed like time to test it in a deployment environment. There are not many web hosts that officially support Lisp, however, so short of setting up my own local server machine and getting a dedicated connection to the internet, it was not immediately obvious whether I could accomplish this.

Luckily, my hosting account from Webfaction—that I use for testing web apps under development before deploying them on my clients’ servers—allows me to install basically whatever linux software I want from source under my home directory. So I installed CLISP and SBCL on my server, followed by Quicklisp, set up a custom app (listening on port), forwarded a domain I wasn’t using for anything else, and installed Weblocks and CL-Prevalence through Quicklisp. Et voila! I didn’t even have to run Hunchentoot through Apache. If you’re looking for a powerful and flexible web host, WebFaction is definitely the way to go.

That being said, there were a few catches along the way, which some of you might like and/or need to know about up front.

First up, Hunchentoot and Weblocks run best on SBCL—which is lucky because that’s my preferred Lisp interpreter and compiler—but to compile SBCL from source, you already need a running Lisp image. For convenience, I compiled and installed CLISP first, and then followed the instructions from the SBCL INSTALL file in the top-level source directory to build SBCL from source with CLISP.

Installing CLISP went mostly as described on the Webfaction Community Q&A site, except for when it came to libsigsegv and the default ulimit value. I modified the compilation and installation of CLISP as follows below.

Open up your preferred terminal and log in to your WebFaction server over SSH. You should appear at the bash prompt in your $HOME directory—unless you have a special place you like to download and compile your source code, the $HOME directory is a good place to be. Now get, unpack, configure, make and install CLISP:

$ wget
$ tar jxvf clisp-2.49.tar.bz2

$ cd clisp-2.49

$ ./configure --ignore-absence-of-libsigsegv --prefix=$HOME

$ ulimit -s 16384
$ cd src/
$ vim config.lisp
$ ./configure --prefix=$HOME

$ ./makemake > Makefile
$ make
$ make install

With that out of the way, SBCL was a breeze. WebFaction uses CentOS 64-bit for their linux hosting, and have GNU Make preinstalled. I note this because it matters which version of Make you have installed for SBCL, even though it seems not to matter for CLISP.

To install SBCL using CLISP:

$ screen

$ wget
$ tar jxvf sbcl-1.1.1-source.tar.bz2
$ cd sbcl-1.1.1
$ sh --xc-host='clisp' --prefix=$HOME

Compiling SBCL takes a while, so you want to run it under screen so you can detach it (Ctrl-a d); this apparently speeds up compilation time somewhat, particularly if you’re using Terminal on OS X or working over SSH (like you would have to be on WebFaction).

You can periodically check on the progress of the compilation by running the ps command:

$ ps -u <YOUR_USERNAME> -o rss,etime,pid,command

(Obviously, don’t forget to replace in the command above with your actual webfaction ssh login).

Once the shell script process finishes, or whenever you want to see the compilation in progress, you can get back to your detached screen session with:

$ screen -r

Once it finishes compiling, you’re almost ready to install. If you have TeX installed (which, I admit, is a little unlikely on a WebFaction server), you can compile the SBCL documentation after SBCL itself is done. Otherwise skip the cd doc/manual && make and ../.. lines and just type INSTALL_ROOT=$HOME sh

$ cd doc/manual && make
$ ../..


You’ll get a lovely message saying SBCL is installed under your home directory. Make sure to test it out by typing sbcl at the command prompt, then in the REPL type some random built-in function to make sure everything is happy. I chose arithmetic because if that doesn’t work, your Lisp image is totally frakked, and that’s a good thing to know up front.

* (+ 10 20 30)


Exit the REPL to go back to bash with (exit). Now it’s time to get Quicklisp, which is a fantastic package manager for Lisp. You can read more about it on the Quicklisp site, or just go ahead and install it:

$ curl -O
$ sbcl --load quicklisp.lisp

You’ll be back in SBCL, with a friendly message telling you how to install Quicklisp; once it’s installed you can add it to the SBCL init file so it’s ready to go every time you open lisp.

* (quicklisp-quickstart:install)

* (ql:add-to-init-file)

Now with your complete Lisp implementation running on your Webfaction server, if you haven’t already, you should go to your user control panel and create a new custom application (the ‘listening on port’ variety — don’t use the ‘custom install script’ unless you’ve carefully followed the instructions on the appropriate documentation page). Make a note of the Port number assigned to your new app, and then add your domain(s) that you want to point to your Weblocks site. Finally, you can set up the websites by pointing the desired domains to the appropriate application, as usual. If you need more help with this, step-by-step instructions are available in WebFaction’s documentation.

Back to your SSH session, you can install Weblocks and all its dependencies right in SBCL with Quicklisp. All of Weblocks’ dependencies are downloaded automatically with Weblocks except for CL-Prevalence. So, here we go:

* (ql:quickload "weblocks")

* (ql:quickload "cl-prevalence")

Now the fun can begin (unless of course you’re like me, and you’ve been having fun the whole time…).

You can (and should) load up the weblocks-demo app to see the server in action before you start working on your own lisp web app.

* (asdf:oos 'asdf:load-op 'weblocks-demo)

* (weblocks-demo:start-weblocks-demo :port ####)

(Again, replace the #### above with the port number assigned to your custom app above).

That should be that. Assuming you’ve given your new app on Webfaction time to propagate over the various DNS levels (which almost snagged me because I was getting very impatient to play with Weblocks by this point), you can point your browser to the domain you assigned to your custom app, and you should see a plain-vanilla confirmation screen for Hunchentoot, proudly branded with the “Made With Lisp” Lizard logo. The Weblocks-Demo app will be at

You’ll notice that the demo app starts off with some interesting statistics—despite all the active, ajax-powered content on this little demo web app, the application itself is written entirely in Lisp. The HTML and Javascript seen in the browser is generated by the framework from Lisp code.

Now you’ll probably want to take a look at the source code for the example apps, and start building your own. Weblocks is hosted on Bitbucket, so you can browse the source at your convenience.

Naturally, I’ll be sharing more Weblocks and Hunchentoot adventures along the way. Happy hacking.