Building a Common Lisp webapp using Python’s envbuilder

One of my goals in starting envbuilder was to make it not totally wedded to Python. My main use-case for envbuilder is to build Python apps, but I think it’s important to make sure envbuilder can be flexible and simple enough to get the job done. I think that the best way to do that is to try using it to build something other than Python.

Shaneal Manek’s excellent guide to setting up a simple Lisp webapp seemed like the perfect project to try this out with. I’ll start off by telling you how to try it out. The first step is to actually get envbuilder. I recommend using the version that’s in master as of this writing. Although this example can probably be made to work with envbuilder 0.2.1 (the current stable release), it is just much easier to understand if you use some of 0.3.0’s features.

So, to get envbuilder, you just need to use the following command:

   git clone git@github.com:jasonbaker/envbuilder.git

This example is already set up in examples/lisp-webapp. To get up and running, you just need to do the following commands:

  1. envb checkout # get the files you need to start
  2. export INSTALL_ROOT=`pwd` # tell sbcl to install to the current directory
  3. envb setup # create a local build of SBCL
  4. export SBCL_HOME=`pwd`/lib/sbcl # tell sbcl where it is installed
  5. envb start # start the webserver

Alright, so here is the .env file in all its glory:

  1. # It seems that there’s a bug in configobj where a section name can 
  2. # conflict in interpolation, so name this differently 
  3. sbcl_ = ‘$CWD/bin/sbcl’
  4. [project]
  5.  parcels = ‘sbcl’‘webapp’
  6.  [[sbcl]]
  7.  checkout = ‘git clone git://git.boinkor.net/sbcl’
  8.  setup = ‘cp $CWD/customize-target-features.lisp $dir’‘sh make.sh’‘sh install.sh’
  9.  [[webapp]]
  10.  dir = ‘trivial-lisp-webapp’
  11.  checkout = ‘git clone git://github.com/smanek/trivial-lisp-webapp.git’
  12.  start = ‘$sbcl_ –no-sysinit –no-userinit –load $CWD/$dir/src/init.lisp’,
  13. [commands]
  14.  [[start]]
  15.  working_dir = ‘%dir/scripts’
  16.  required = False
  17.  help = ‘Start the server’

The first thing to understand about envbuilder is the concept of a “parcel”. A parcel is simply a piece of software that’s usually checked out from version control (although it doesn’t have to be). The commands that are run when you do “envb checkout” are defined using the checkout option. Similarly, the command that is run when you do “envb setup” is defined by the setup option. You’ll notice that the webapp parcel doesn’t have a setup command. This is because we don’t really need to do anything to set it up other than checking it out from git. There is one important thing to note here though. The sbcl section uses a $CWD variable to run itself. There is a difference between $CWD and simply using a dot (“.”). The difference being that the setup command is run from inside the parcel’s directory. Using dot is relative to that directory while $CWD is the directory that envb was run from.

The last feature to note is the custom command (start). Just as with checkout and setup, the start command is to be placed in a start option in a parcel. In this case, the start command only runs on the webapp parcel. I won’t go into detail about each option on the start command as that’s covered in the envbuilder documentation.

So, the purpose of this blog post isn’t really to teach you how to set up a lisp web application with envbuilder. It’s to show you that envbuilder is much more than a tool to create a Python virtualenv. If you’d like to contribute to envbuilder, the best way to do so at present is to submit other examples of how you’ve gotten envbuilder to work in a neat or creative way. After all, the real fun in creating an extensible application is finding out that it can do things you didn’t realize it could do.