Set Up a Server and Deploy a Clojure App to it

This section is for all the apprentice server admins out there. If you feel hazy about what exactly a server is, then I’ll help you gain clarity by walking you through what happens when you visit a URL with your browser. You’ll separate servers-as-machines from servers-as-programs, and you’ll learn how computers decide which program to use to respond to a request. You’ll also learn a bit about the process model, a foundational programming concept that has made my life way easier and that will make your life easier, too.

The server you’re building will run a Clojure application that’s been packaged as an uberjar. When you run that uberjar, it will start its own HTTP server. (Read Building, Running, and the REPL from Clojure for the Brave and True if you’re unfamiliar with uberjars and running Java programs.)

In this case, the Clojure application will be an example that you’ll download. The example application will let you create and manage role-playing character sheets. It has a front-end browser client written in Clojurescript (of course), and a backend HTTP component that handles requests to create, read, update, and delete the character sheets.

As a dev from the shadows, you want to get the most out of your hardware by running multiple web apps on one machine. You want to be able to host, for example, application servers for dubstepkazoo.com and morekazoo.com on the same machine. Therefore, you can’t configure your application server to listen to port 80, because that would make it impossible for your machine to serve other applications.

To meet this requirement, you’ll install an nginx web server that listens to port 80 and routes incoming HTTP requests to your applications. When nginx gets a request, it forwards it to your applications' HTTP servers based on the domain name of the request. See Figure 1.1.

Finally, you’ll also install Datomic Free and set up the configuration necessary for your application to talk to Datomic.

Before you can build and deploy the example Clojure application, you’ll need to download it (of course) and install Homebrew (Macintosh only), Boot, Ansible, VirtualBox, and Vagrant. I’ve included installation instructions for Mac and Ubuntu machines below. If you’re using another Linux distro, I’m assuming u r l33t hax0r and you’ll be able to install these tools without guidance.

Some of these tools can take a while to download…​ Hey, maybe check out the DevOps Community Picks while you wait? (Using the tutorial I’ve spent hours and hours writing to market my side project…​ from the shadows.)

Now that we have everything installed, let’s create a virtual machine (VM) and set it up. Think of VMs as computers that are implemented as software. They have an operating system and manage processes just like the computer you’re using right now, but instead of physical hardware they rely on emulated hardware. The computer you use to start a VM is called the host.

We’re creating a VM because it lets us try out our server setup and deployment process more quickly and cheaply than using an actual server from a hosting company; we get a tighter feedback loop.

To create the VM, run this command:

vagrant up will take a few minutes to run because it’s doing a lot. It’s downloading an Ubuntu image and creating your virtual machine, and it’s also running scripts to set up the VM. The scripts are downloading packages like nginx and datomic, and uploading files to configure those services.

When Vagrant’s done, The last line of output it produces should look something like:

And that’s it! The server should now have nginx and datomic installed, and it should be ready for you to deploy the example app. If you want to shut down your vagrant server, just run vagrant halt. If you do something crazy and want to start from scratch, run vagrant destroy -f. This will delete the virtual machine you created; you can recreate it with vagrant up. (This ability to quickly recreate VMs is part of what makes them so useful.)

Run this command from within the character-sheet-example/infrastructure directory:

build and deploy are both tiny shell scripts (three lines each)../build will take a few minutes to run while it downloads dependencies, compiles clojurescript, and packs everything into an uberjar. Then ./deploy dev copies the uberjar to your VM, runs database migrations, runs a basic check that the app is functioning, and starts the app as an Ubuntu service. When it’s done, you should be able to view the example app by going to http://localhost:3100/ on your computer (not the VM). The screen should look something like this:

Bam! You have deployed a Clojure application to a server running on your computer. Whenever you change your Clojure app, you can build and deploy it again by running ./build && ./deploy dev from the infrastructure directory. The deployment will follow the same steps every time, without any manual intervention on your part. What’s even better is that you can be confident that this process will work on a real server, something we’ll try in the next section.

A virtual private server (VPS) is essentially a virtual machine provided by a hosting company. Unlike Geocities of yesteryear or Squarespace/Tumblr/Wordpress of todayyear, you’re given root access to a machine and it’s up to you to set it up to serve your app.

My favorite VPS host is Digital Ocean. I’ve used them for more than three years and love them! Their customer support is responsive and helpful, they have a huge library of well-written documents on working with servers, and their tools make it simple and easy to create new servers. If you sign up using the above link, you’ll get a $10 credit (and I’ll get a $25 credit, yay), enough to run a server with 1gb of RAM and 30gb of SSD disk space for a month, or 2gb of RAM and 40gb for 15 days. Just a heads up: the signup process will ask you for a credit card.

One great thing about Digital Ocean is that it only bills you for the amount of time your servers run: you could sign up, create a 2gb server to use as you go through this tutorial (what I recommend), and then immediately delete the server, and you’ll never get charged. It’s a cost-free way to try this stuff out, as long as you’re diligent about deleting your server afterward. In this section, I’ll walk you through the entire process, showing you both how to create a server and delete it.

After you sign up, you’ll see a screen asking you create a droplet:

Droplet is digital ocean’s trademark branded term for VPS. Click “create droplet”, and you’ll be greeted with a screen that looks like this:

Choose an Ubuntu 14.04.5 x64 server.

Close to the bottom of the page you’ll be asked to add an SSH key. You’ll need to add an SSH key for the deploy scripts to work. If you’re unfamiliar with the process, Digital Ocean has a quick, helpful guide.

The next section prompts you to give your droplet a name. This is for your human use only; it doesn’t impact the server’s functioning. Try naming it "deploy-quest".

When you’re done, click "create", and in less than a minute your server will be ready to use! Digital Ocean shows a nice little progress bar while it sets up your server, and when it’s done it should show you the IP address of your server. Try visiting it in a browser:

It doesn’t work because we haven’t set up the server to actually serve anything. All it takes is to update the file character-sheet-example/infrastructure/ansible/inventories/prod/hosts by replacing the text character-sheet-example-prod on the first line with your server’s IP address. The demo server I’m using as I write this has the IP address 138.197.66.144, so my file looks like this:

(If you have a domain name configured to point to your droplet, you can just use the domain name instead of the IP address.)

Now, update the file character-sheet-example/infrastructure/ansible/inventories/prod/group_vars/webservers by using your IP address for clojure_uberjar_webapp_domain (for a real site, you would use the real domain name). It should look something like this:

Now all you have to do is run these commands on the command line from the character-sheet-example/infrastructure directory:

If all goes well, you should be able to visit the IP address in your browser and see the example app:

Not bad! Just a couple configuration tweaks and the app is online, ready for the world to see. It takes very little work to set up a server and deploy a Clojure app, and I think that’s pretty exciting!

Now you know how to deploy a Clojure application that follows the conventions I follow in my personal projects. To get this working with your own application, you’ll probably have to do a bit of customization.

In this section, you set up your computer to perform quick and painless Clojure deployments. You installed Boot, Ansible, Virtualbox, and Vagrant, and you used them to deploy an example Clojure application to a local VM. You may have even deployed the app to a VPS hosted by Digital Ocean. You discovered that deploying a Clojure application can be easy, and you felt a pleasant warmth as you brain released a tiny bit of dopamine into your system.

Seriously though - I spent a lot of time working out how to deploy sites with minimum hassle, and I hope the result is as exciting to you as it is to me. In the next section, I’ll walk you through the code I wrote and share what I’ve learned in my years as a DevOps amateur working on small-scale deployments. If you’d like to learn exactly how the tools you used work together to set up your server, or if you’d like to learn a bit about server management, read on!

Here’s all the command you ran for easy reference: