Skip to main content

how to deploy clojure applications using bakesale

In this guide, I show how to deploy Clojure applications using bakesale. I wrote bakesale because I wanted to return to the main ingredients of deployment, doing only so much as is finger-saving, and leaving the rest to the user to sort. I find this gives a lot of flexibility, whilst not cluttering my deployment config with lots of custom settings. bakesale is written as a collection of simple Shell scripts, and is pretty transparent. It’s built around the premise that deployment is much like baking a cake for a bakesale. Although I usually use it to deploy Ruby applications, deploying Clojure applications is just as straightforward. For this guide, I deploy MTRX9 (GitHub; Twitter), a simple websockets matrix monitoring tool which uses the notions of streams, chars, and time.

server prerequisites

The server, running Ubuntu 12.04 LTS, has a sudoer user called mtrx9, with a corresponding home directory. RubyGems is installed as a package, because I’ll use Foreman to write upstart scripts on the server. This isn’t necessary, of course, but it’s pretty convenient. Note that this server isn’t running Ruby applications, so I’m not using RVM or another version manager; instead, I just let the package dependencies get satisfied. I have Java OpenJDK installed, again as a package.

I manage these prerequisites using Puppet (a masterless setup, also deployed using bakesale); however, this is about deploying Clojure, so I’ll assume you’ve set up the server in whichever way makes you happy. To manually install the necessary packages:

apt-get install rubygems openjdk-7-jdk

install bakesale

bakesale just needs to be somewhere on your local system so that you can source it in scripts. I assume a local user called mlnw, with a corresponding home directory at /Users/mlnw/. I also assume your code repository is at /Users/mlnw/mtrx9/. Clone bakesale somewhere:

git clone git://github.com/tiredpixel/bakesale.git /Users/mlnw/bakesale

That’s all that’s needed to use bakesale; by default, the master branch will be used, which is (hopefully) stable.

define settings and services

bakesale discourages having the deployment config in the code repository itself (let’s stop embedding config in repositories). Create a directory to hold your deployment config:

mkdir -p /Users/mlnw/Deployments/mtrx9/

Create a file containing environment variables for the application; this will be exported to upstart using Foreman. MTRX9 only uses environment variables settings, but if you have other settings, you can write these in a similar manner. Copy the example and edit as appropriate:

cp /Users/mlnw/mtrx9/.env.example /Users/mlnw/Deployments/mtrx9/mtrx9.env

The Procfile defines services for the application. We will compile into a standalone uberjar, so write a custom Procfile:

# /Users/mlnw/Deployments/mtrx9/mtrx9.Procfile

web: java -jar target/*-*-standalone.jar $PORT

write deployment recipe

The deployment recipe defines the details of the deployment. However, it’s just a Shell script, so you can put whatever custom logic in there you need. If you find yourself using the same small fragment of code a lot across scripts, then it might be a good candidate for a new bakesale ‘stage’. It would be excellent if you would be so kind as to fork bakesale and submit a pull request with your improvement. Include bakesale at the top of your script:

source /Users/mlnw/bakesale/bakesale.sh

Then, just write a Shell script to deploy the application, using the bakesale ‘stage’ helpers. Without further ado, here is the complete script for deploying MTRX9. It clones the MTRX9 repository (fresh each time, by design), writes the settings and services configs, compiles the application into an uberjar, rsyncs everything to the server, uses Foreman to export it to upstart (Foreman gets automatically installed, if it’s not already, as part of that command), and restarts the exported services. This only takes a few lines:

# /Users/mlnw/Deployments/mtrx9/mtrx9.sh

#!/bin/bash

source /Users/mlnw/bakesale/bakesale.sh

ssh1=mtrx9@example.com

sshs="($ssh1)"

# = Bake

bakesale bake git git://github.com/tiredpixel/mtrx9.git

bakesale bake copy /Users/mlnw/Deployments/mtrx9/mtrx9.env .env
bakesale bake copy /Users/mlnw/Deployments/mtrx9/mtrx9.Procfile Procfile

bash -c "cd '$bakesale_cakebox/'; lein uberjar" # or any other custom step

# = Carry

bakesale carry rsync_ssh "$sshs" mtrx9/

# = Wave

bakesale wave ssh_foreman "$sshs" "export --root mtrx9/ --app mtrx9 --user mtrx9 --concurrency web=1 upstart /etc/init; restart mtrx9"

bakesale supports multi-server deployments; just pass an array of locations to the SSH commands.

deploy application

The deployment config is just a script, so to deploy, just execute it:

bash /Users/mlnw/Deployments/mtrx9/mtrx9.sh

At some point, you’ll be asked for the sudo password; this is necessary so Foreman can export it to upstart.

comments

bakesale isn’t particularly fast at deployment; there are a few reasons for this. One is that a fresh clone of the code repository is made each time; this is to provide absolute assurance that nothing’s been included by accident. Another reason for slowness is that the ‘cakebox’ is rsynced up to the server, rather than letting the server perform the clone; this is so the server doesn’t need to have Git installed, and doesn’t require the server to have access to the code repository. bakesale is just as opinionated as any other deployer; it doesn’t claim to be the best solution, only a solution built on a certain set of ideas (such as not having to pull hair out about server access to repositories, and forwarded SSH settings). It’s still a young project, so if you’d like to help improve it, please do get in contact—or just fork it and see.

Peace,
tiredpixel ☮