Deploying Clojure Apps on Heroku

Last updated 21 March 2016

This article describes how to take an existing Clojure app and deploy it to Heroku.

Overview

To generate a project skeleton that has some extra convenience features that are useful for Heroku development, type lein new heroku helloworld. The skeleton project’s README.md file describes what it contains and how to use it.

The most important parts of an app are: your application’s source code in the src directory, a project.clj file in the root directory, and a Procfile that defines the app’s process types. A database isn’t automatically provisioned for Clojure apps, but it is easy to add one if you need it.

Your Clojure application’s source code

Put your application source code into a folder within the src directory.

The project.clj file

The project.clj file is used by Clojure’s dependency manager. Heroku’s Clojure support is applied only if a project.clj file exists in the root directory.

Note that it’s highly recommended to use AOT (ahead-of-time compilation) during deployment because it speeds up app boot time and catches certain types of errors before the app is live. The following project.clj settings will apply AOT during deployment but not during local development:

  :profiles {:uberjar {:aot :all}}

The Procfile

A Procfile is a text file, in the root directory of your application, that defines process types and that explicitly declares what command should be executed to start your app. It will look something like this:

web: java $JVM_OPTS -cp target/helloworld-standalone.jar clojure.main -m helloworld.web

This declares a single process type, web, and the command needed to run it. The name web is important here. It declares that this process type will be attached to the HTTP routing stack of Heroku, and receive web traffic when deployed.

The command in a web process type must bind to the port number specified in the PORT environment variable. If it does not, the dyno will not start.

Procfiles can contain additional process types. For example, you might declare one for a background worker process that processes items off of a queue.

How to keep build artifacts out of git

Prevent build artifacts from going into revision control by creating a .gitignore file. Here’s a typical .gitignore:

/target
/pom.xml
/.lein-*
/.env

Console

Heroku allows you to run one-off dynos - scripts and applications that only need to be executed when needed - using the heroku run command. Use this to launch a REPL process attached to your local terminal for experimenting in your app’s environment:

$ heroku run lein repl
Running lein repl attached to terminal... up, run.1
Downloading Leiningen to .lein/leiningen-2.2.0-standalone.jar now...
[...]
Clojure 1.5.1
user=>

Since Leiningen is not included in your slug for size reasons, it’s downloaded on-demand here. The repl has your app’s namespaces available. For example:

user=> (require 'hello.world)
nil
user=> (hello.world/app {})
{:status 200, :headers {"Content-Type" "text/plain"}, :body "Hello, world"}

For more details about using a REPL on Heroku, see the live debugging Clojure apps article.

One-off scripts

You can run a one-off Clojure script attached to the terminal in the same way, as long as the script exists in your deployed app. Try making a small script that prints to the console and exits:

src/hello/hi.clj

(ns hello.hi)

(defn -main [& args]
  (println "Hello there"))

Run the script in a one-off dyno with heroku run:

$ heroku run lein run -m hello.hi
Running lein run -m hello.hi attached to terminal... up, run.2
Hello there