Getting Started on Heroku with Clojure
Introduction
Deploy a Clojure app in minutes with this tutorial.
The tutorial assumes that you have:
- A verified Heroku Account
- OpenJDK 17 (or newer) installed
- Leiningen 2 installed
- Postgres installed
- An Eco dynos plan subscription (recommended)
We recommend using our low-cost plans to complete this tutorial. Eligible students can apply for platform credits through our new Heroku for GitHub Students program.
Set Up
Install the Heroku Command Line Interface (CLI). Use the CLI to manage and scale your app, provision add-ons, view your logs, and run your app locally.
The Heroku CLI requires Git, the popular version control system. If you don’t already have Git installed, complete the following before proceeding:
Download and run the installer for your platform:
macOS
WindowsDownload the appropriate installer for your Windows installation:
You can find more installation options for the Heroku CLI here.
After installation, you can use the heroku command from your command shell.
On Windows, start the Command Prompt (cmd.exe) or Powershell to access the command shell.
To log in to the Heroku CLI, use the heroku login command:
$ heroku login
heroku: Press any key to open up the browser to login or q to exit:
Opening browser to https://cli-auth.heroku.com/auth/cli/browser/***
heroku: Waiting for login...
Logging in... done
Logged in as me@example.com
This command opens your web browser to the Heroku login page. If your browser is already logged in to Heroku, click the Log In button on the page.
This authentication is required for the heroku and git commands to work correctly.
If you have any problems installing or using the Heroku CLI, see the main Heroku CLI article for advice and troubleshooting steps.
If you’re behind a firewall that uses a proxy to connect with external HTTP/HTTPS services, set the HTTP_PROXY or HTTPS_PROXY environment variables in your local development environment before running the heroku command.
Prepare the App
In this step, you clone a sample application and prepare to deploy it to Heroku.
If you’re new to Heroku, it’s recommended to complete this tutorial using the Heroku-provided sample application.
If you have your own application that you want to deploy instead, see Preparing a Codebase for Heroku Deployment.
Create a local copy of the sample app by executing the following commands in your local command shell or terminal:
$ git clone https://github.com/heroku/clojure-getting-started
$ cd clojure-getting-started
This functioning Git repository contains a simple Clojure application. The application includes a Procfile, a special plaintext file used by Heroku apps. You explicitly declare the processes and commands used to start your app in this file.
The Procfile in the example app source code looks like this:
web: java -Dclojure.main.report=stderr -cp target/uberjar/clojure-getting-started.jar clojure.main -m clojure-getting-started.core
This file declares a single process type, web, and the command needed to run it. The name web is important. It declares that this process type attaches to Heroku’s HTTP routing stack, and is able to receive web traffic.
Procfiles can contain additional process types. For example, you can declare a background worker that processes items off a queue. This tutorial doesn’t cover other processes but you can refer to The Procfile and The Process Model for more info.
The example app also includes a project.clj file which is used by Leiningen, a Clojure build tool. The next step covers how to use this file to declare dependencies.
Declare App Dependencies
Heroku automatically identifies an app as a Clojure app if it contains a project.clj file in the root directory. When a Clojure app is detected, Heroku adds the official Clojure buildpack to your app, which installs the dependencies for your application.
The example app you deployed already has a project.clj (see it here).
When deploying an app, Heroku reads this file and installs the dependencies. Take a look at the dependencies listed in your project.clj.
Another file, system.properties, indicates the version of Java to use. The contents of this optional file look like:
java.runtime.version=17
Heroku supports many different versions. You can push your own apps using a different version of Java.
Deploy the App
In this step you will deploy the app to Heroku.
Using a dyno and a database to complete this tutorial counts towards your usage. Delete your app and database as soon as you are done experimenting to control costs.
By default, apps use Eco dynos if you are subscribed to Eco. Otherwise, it defaults to Basic dynos. The Eco dynos plan is shared across all Eco dynos in your account and is recommended if you plan on deploying many small apps to Heroku. Learn more here. Eligible students can apply for platform credits through our Heroku for GitHub Students program.
Create an app on Heroku to prepare it to receive your source code for deployment:
$ heroku create
Creating app... done, ⬢ peaceful-inlet-84135
https://peaceful-inlet-84135.herokuapp.com/ | https://git.heroku.com/peaceful-inlet-84135.git
This command both creates an app and a Git remote (named heroku) associated with your local Git repository.
By default, Heroku generates a random name for your app. You can pass a parameter to specify your own app name.
If you create your app via the Heroku Dashboard instead of using the CLI command, add a remote to your local repo with heroku git:remote --app example-app.
Now deploy your code:
$ git push heroku main
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Building on the Heroku-22 stack
remote: -----> Determining which buildpack to use for this app
remote: -----> Clojure (Leiningen 2) app detected
remote: -----> Installing OpenJDK 17... done
remote: -----> Installing rlwrap...
...
remote: Compiling clojure-getting-started.config
remote: Compiling clojure-getting-started.core
remote: Compiling clojure-getting-started.db.core
remote: Compiling clojure-getting-started.env
remote: Compiling clojure-getting-started.handler
remote: Compiling clojure-getting-started.layout
remote: Compiling clojure-getting-started.middleware
remote: Compiling clojure-getting-started.middleware.formats
remote: Compiling clojure-getting-started.nrepl
remote: Compiling clojure-getting-started.routes.home
remote: Created /tmp/build_3a91ae40/target/uberjar/clojure-getting-started-0.1.0-SNAPSHOT.jar
remote: Created /tmp/build_3a91ae40/target/uberjar/clojure-getting-started.jar
remote: -----> Discovering process types
remote: Procfile declares types -> web
remote:
remote: -----> Compressing...
remote: Done: 136.7M
remote: -----> Launching...
remote: Released v5
remote: https://peaceful-inlet-84135.herokuapp.com/ deployed to Heroku
remote:
remote: Verifying deploy... done.
To https://git.heroku.com/peaceful-inlet-84135.git
* [new branch] main -> main
By default, your app deploys on a eco dyno. A dyno is a lightweight Linux container that runs the command specified in your Procfile. After deployment, ensure that you have one web dyno running the app. You can check how many dynos are running using the heroku ps command:
$ heroku ps
Eco dyno hours quota remaining this month: 1000h 0m (100%)
Eco dyno usage for this app: 0h 0m (0%)
For more information on Eco dyno hours, see:
https://devcenter.heroku.com/articles/eco-dyno-hours
=== web (Eco): java -Dclojure.main.report=stderr -cp target/uberjar/clojure-getting-started.jar clojure.main -m clojure-getting-started.core (1)
web.1: up 2023/03/09 17:00:28 +0100 (~ 1m ago)
The running web dynos serve requests. Visit the app at the URL generated by its app name. As a handy shortcut, you can open the website with:
$ heroku open
Eco dynos sleep after thirty minutes of inactivity (for example, if they don’t receive any traffic). This behavior causes a delay of a few seconds for the first request upon waking. Subsequent requests perform normally. Eco dynos consume from a monthly, account-level quota of eco dyno hours. As long as you haven’t exhausted the quota, your apps can continue to run.
To avoid dyno sleeping, upgrade to a Basic or Professional dyno type as described in Dyno Types.
Scale the App
Horizontal scaling an application on Heroku is equivalent to changing the number of running dynos.
Scale the number of web dynos to zero:
$ heroku ps:scale web=0
Access the app again by refreshing your browser or running heroku open. You get an error message because your app no longer has any web dynos available to serve requests.
Scale it up again:
$ heroku ps:scale web=1
You can also vertically scale your app by upgrading to larger dynos. See Dyno Types and Scaling Your Dyno Formation for more info.
View Logs
Heroku aggregates all output streams from both your app and the platform’s components into a single channel of time-ordered logs.
View information about your running app using the heroku logs --tail command:
$ heroku logs --tail
2023-03-09T16:03:01.968026+00:00 app[web.1]: 1585 INFO clojure-getting-started.env -
2023-03-09T16:03:01.968040+00:00 app[web.1]: -=[clojure-getting-started started successfully]=-
2023-03-09T16:03:02.014316+00:00 app[web.1]: 1632 INFO io.undertow - starting server: Undertow - 2.2.20.Final
2023-03-09T16:03:02.019140+00:00 app[web.1]: 1637 INFO org.xnio - XNIO version 3.8.7.Final
2023-03-09T16:03:02.124542+00:00 app[web.1]: 1743 INFO org.jboss.threads - JBoss Threads version 3.1.0.Final
2023-03-09T16:03:02.164333+00:00 app[web.1]: 1783 INFO luminus.http-server - server started on port 22329
2023-03-09T16:03:02.164583+00:00 app[web.1]: 1783 INFO clojure-getting-started.core - #'clojure-getting-started.db.core/*db* started
2023-03-09T16:03:02.164666+00:00 app[web.1]: 1783 INFO clojure-getting-started.core - #'clojure-getting-started.handler/init-app started
2023-03-09T16:03:02.164795+00:00 app[web.1]: 1783 INFO clojure-getting-started.core - #'clojure-getting-started.handler/app-routes started
2023-03-09T16:03:02.164888+00:00 app[web.1]: 1783 INFO clojure-getting-started.core - #'clojure-getting-started.core/http-server started
Visit your application in the browser again to generate another log message.
Press CTRL+C to stop streaming logs.
By default, Heroku stores your app’s 1500 most recent log lines. You can provision a logging add-on or implement your own log drain for long-term storage. In the next step, you add a logging add-on to your app.
Provision Add-ons
Add-ons are cloud services that provide additional services for your application, such as databases, logging, and monitoring.
Several logging add-ons are available that provide features such as log persistence, search, and alerting. Papertrail is one such add-on with a free plan.
Provision the add-on like so:
$ heroku addons:create papertrail
Creating papertrail on ⬢ peaceful-inlet-84135... free
Welcome to Papertrail. Questions and ideas are welcome (technicalsupport@solarwinds.com). Happy logging!
Created papertrail-slippery-84785 as PAPERTRAIL_API_TOKEN
Use heroku addons:docs papertrail to view documentation
This command provisions the add-on and configures it for your application. To see this particular add-on in action, visit your application’s Heroku URL a few times. Each visit generates more log messages, which routes to the Papertrail add-on. Visit the Papertrail console to see the log messages:
$ heroku addons:open papertrail
Your browser opens up a Papertrail web console that shows the latest log events. The interface lets you search and set up alerts.
You can list all of your app’s active add-ons like so:
$ heroku addons
Running this command for your sample app lists its Papertrail add-on.
Use a Database
Adding a database to complete this tutorial counts towards your usage. Delete your database as soon as you’re done to control costs. Learn about our low-cost plans. Eligible students can apply for platform credits through our Heroku for GitHub Students program.
Heroku provides managed data services for Postgres and Redis, and the add-on marketplace provides additional data services, including MongoDB and MySQL.
Use the heroku addons:create command to provision a Postgres database for your app:
$ heroku addons:create heroku-postgresql:essential-0
Creating heroku-postgresql:essential-0 on ⬢ peaceful-inlet-84135... ~$0.007/hour (max $5/month)
Database should be available soon
postgresql-fitted-70383 is being created in the background. The app will restart when complete...
Use heroku addons:info postgresql-fitted-70383 to check creation progress
Use heroku addons:docs heroku-postgresql to view documentation
Use the heroku addons command for an overview of the database provisioned for your app:
$ heroku addons
Add-on Plan Price State
─────────────────────────────────────────── ─────────── ──────── ───────
heroku-postgresql (postgresql-fitted-70383) essential-0 $5/month created
└─ as DATABASE
papertrail (papertrail-slippery-84785) choklad free created
└─ as PAPERTRAIL
The table above shows add-ons and the attachments to the current app (peaceful-inlet-84135) or other apps.
Listing your app’s config vars displays the URL that your app uses to connect to the database (DATABASE_URL):
$ heroku config
=== peaceful-inlet-84135 Config Vars
DATABASE_URL: postgres://avhrhofbiyvpct:3ab23026d0fc225bde4544cedabc356904980e6a02a2418ca44d7fd19dad8e03@ec2-23-21-4-7.compute-1.amazonaws.com:5432/d8e8ojni26668k
PAPERTRAIL_API_TOKEN: ChtIUu9fHbij1cBn7y6z
The heroku pg command provides more in-depth information on your app’s Heroku Postgres databases:
$ heroku pg
=== DATABASE_URL
Plan: Essential 0
Status: Available
Connections: 0/20
PG Version: 15.5
Created: 2024-05-01 16:00 UTC
Data Size: 8.6 MB/1.00 GB (0.84%) (In compliance)
Tables: 0
Fork/Follow: Unsupported
Rollback: Unsupported
Continuous Protection: Off
Add-on: postgresql-fitted-70383
Running this command for your app indicates that the app has an essential-0 Postgres database with no tables.
The example app you deployed already has database functionality, which you can reach by visiting your app’s /database path.
$ heroku open /database
You see something like this:
Database Output
* Read from DB: 2023-03-09 16:58:55.816605
* Read from DB: 2023-03-09 16:58:56.728701
* Read from DB: 2023-03-09 16:58:57.064755
Assuming that you have Postgres installed locally, use the heroku pg:psql command to connect to the remote database and see all the rows:
$ heroku pg:psql
--> Connecting to postgresql-fitted-70383
psql (15.2, server 14.7 (Ubuntu 14.7-1.pgdg20.04+1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.
peaceful-inlet-84135::DATABASE=> SELECT * FROM ticks;
tick
----------------------------
2023-03-09 16:58:55.816605
2023-03-09 16:58:56.728701
2023-03-09 16:58:57.064755
(3 rows)
peaceful-inlet-84135::DATABASE=> \q
The following info illustrates how the example app implements its database functionality. Don’t make changes to your example app code in this step.
The code in the example app looks like this:
(defn database [request]
(layout/plain (let [ticks (jdbc/with-db-connection [connection {:datasource db/*db*}]
(do (jdbc/execute! connection "CREATE TABLE IF NOT EXISTS ticks (tick timestamp)")
(jdbc/execute! connection "INSERT INTO ticks VALUES (now())")
(map :tick (jdbc/query connection "SELECT tick FROM ticks"))))]
(str "Database Output\n\n" (clojure.string/join "\n" (map #(str "Read from DB: " %) ticks))))))
The database function adds a new row to the tick table when you access your app using the /database route. It then returns all rows to render in the output.
The data source shown in the example app code is created based on the JDBC_DATABASE_URL environment variable.
The official Heroku Clojure buildpack that’s automatically added to your app sets this JDBC_DATABASE_URL environment variable. This variable is dynamic and doesn’t appear in your list of configuration variables when running heroku config. You can view it by running the following command:
$ heroku run echo \$JDBC_DATABASE_URL
Read more about Heroku PostgreSQL. You can also install Redis or other data add-ons via heroku addons:create.
Prepare the Local Environment
In the following steps, you learn how to work with your app locally and push changes to Heroku. Begin by installing your dependencies locally in this step.
Run lein uberjar in your local directory. This command installs the dependencies, preparing your system to run the app locally.
$ lein uberjar
Compiling clojure-getting-started.config
Compiling clojure-getting-started.core
Compiling clojure-getting-started.db.core
Compiling clojure-getting-started.env
Compiling clojure-getting-started.handler
Compiling clojure-getting-started.layout
Compiling clojure-getting-started.middleware
Compiling clojure-getting-started.middleware.formats
Compiling clojure-getting-started.routes.home
Created /Users/heroku.user/projects/clojure-getting-started/target/uberjar/clojure-getting-started-0.1.0-SNAPSHOT.jar
Created /Users/heroku.user/projects/clojure-getting-started/target/uberjar/clojure-getting-started.jar
The Leiningen process compiles and builds a JAR, with dependencies, placing it into your application’s target directory. The uberjar task that is configured in project.clj provides this process.
After installing dependencies, you can run your app locally. However, the app requires a Postgres database. Create a local Postgres database and update your local .env file. heroku local, the command used to run apps locally, automatically sets up your environment based on the .env file in your app’s root directory. Set the JDBC_DATABASE_URL environment variable with your local Postgres database’s connection string:
JDBC_DATABASE_URL=jdbc:postgresql://localhost:5432/java_database_name
Your local environment is now ready to run your app and connect to the database.
Run the App Locally
Ensure you’ve already run lein uberjar before running your app locally.
Start your application locally with the heroku local CLI command:
$ heroku local --port 5001
5:26:58 PM web.1 | 751 INFO clojure-getting-started.env -
5:26:58 PM web.1 | -=[clojure-getting-started started successfully]=-
5:26:58 PM web.1 | 780 INFO io.undertow - starting server: Undertow - 2.2.20.Final
5:26:58 PM web.1 | 785 INFO org.xnio - XNIO version 3.8.7.Final
5:26:58 PM web.1 | 841 INFO org.jboss.threads - JBoss Threads version 3.1.0.Final
5:26:58 PM web.1 | 867 INFO luminus.http-server - server started on port 5001
5:26:58 PM web.1 | 867 INFO clojure-getting-started.core - #'clojure-getting-started.db.core/*db* started
5:26:58 PM web.1 | 868 INFO clojure-getting-started.core - #'clojure-getting-started.handler/init-app started
5:26:58 PM web.1 | 868 INFO clojure-getting-started.core - #'clojure-getting-started.handler/app-routes started
5:26:58 PM web.1 | 868 INFO clojure-getting-started.core - #'clojure-getting-started.core/http-server started
Just like the Heroku platform, heroku local examines your Procfile to determine what command to run.
Open http://localhost:5001 with your web browser to see your app running locally.
If you want to access the app’s /database route locally, ensure that your local Postgres database is running before you visit the URL.
To stop the app from running locally, go back to your terminal window and press CTRL+C to exit.
Push Local Changes
In this step, you make local changes to your app and deploy them to Heroku. Add the following dependency and some code that uses it.
Modify project.clj to include a dependency for jscience by adding the following code to :dependencies:
[org.jscience/jscience "4.3.1"]
In file src/clj/clojure_getting_started/routes.clj, add the following :import for the library to the clojure-getting-started.routes namespace:
(:import
org.jscience.physics.amount.Amount
org.jscience.physics.model.RelativisticModel
javax.measure.unit.SI)
Add the following convert function to routes.clj:
(defn convert [request]
(layout/plain
(let [energy-amount (Amount/valueOf "12 GeV")]
(do (RelativisticModel/select)
(str "E=mc^2: " energy-amount " = " (.to energy-amount SI/KILOGRAM))))))
Add a mapping for the new route to the routes function in routes.clj:
["/convert" {:get convert}]
Here’s the final source code for routes.clj. Ensure that your changes look similar. Here’s a diff of all the local changes made.
Test your changes locally:
$ lein uberjar
Compiling clojure-getting-started.config
Compiling clojure-getting-started.core
Compiling clojure-getting-started.db.core
Compiling clojure-getting-started.env
Compiling clojure-getting-started.handler
Compiling clojure-getting-started.layout
Compiling clojure-getting-started.middleware
Compiling clojure-getting-started.middleware.formats
Compiling clojure-getting-started.routes.home
Created /Users/heroku.user/projects/clojure-getting-started/target/uberjar/clojure-getting-started-0.1.0-SNAPSHOT.jar
Created /Users/heroku.user/projects/clojure-getting-started/target/uberjar/clojure-getting-started.jar
$ heroku local --port 5001
6:05:29 PM web.1 | 738 INFO clojure-getting-started.env -
6:05:29 PM web.1 | -=[clojure-getting-started started successfully]=-
6:05:29 PM web.1 | 770 INFO io.undertow - starting server: Undertow - 2.2.20.Final
6:05:29 PM web.1 | 774 INFO org.xnio - XNIO version 3.8.7.Final
6:05:29 PM web.1 | 827 INFO org.jboss.threads - JBoss Threads version 3.1.0.Final
6:05:29 PM web.1 | 854 INFO luminus.http-server - server started on port 5001
6:05:29 PM web.1 | 854 INFO clojure-getting-started.core - #'clojure-getting-started.db.core/*db* started
6:05:29 PM web.1 | 854 INFO clojure-getting-started.core - #'clojure-getting-started.handler/init-app started
6:05:29 PM web.1 | 854 INFO clojure-getting-started.core - #'clojure-getting-started.handler/app-routes started
6:05:29 PM web.1 | 854 INFO clojure-getting-started.core - #'clojure-getting-started.core/http-server started
Visiting your application’s /convert path at http://localhost:5001/convert, which displays some scientific conversions:
E=mc^2: 12 GeV = (2.139194076302506E-26 ± 1.4E-42) kg
After testing, deploy your changes. Almost every Heroku deployment follows this same pattern. First, use the git add command to stage your modified files for commit:
$ git add .
Next, commit the changes to the repository:
$ git commit -m "Add convert endpoint"
Now deploy, just as you did previously:
$ git push heroku main
Finally, check that your updated code successfully deployed by opening your browser to that route:
$ heroku open /convert
Define Config Vars
Heroku lets you externalize your app’s configuration by storing data such as encryption keys or external resource addresses in config vars.
At runtime, config vars are exposed to your app as environment variables. For example, modify routes.clj so that the function obtains an energy value from the ENERGY environment variable:
In file src/clj/clojure_getting_started/routes.clj, change the convert function:
(defn convert [request]
(layout/plain (let [energy-env (System/getenv "ENERGY")]
(if (nil? energy-env)
"ENERGY environment variable is not set!"
(let [energy-amount (Amount/valueOf energy-env)]
(do (RelativisticModel/select)
(str "E=mc^2: " energy-amount " = " (.to energy-amount SI/KILOGRAM))))))))
Recompile the app to integrate this change by running lein uberjar.
heroku local automatically sets up your local environment based on the .env file in your app’s root directory. Your sample app already includes a .env file with the following contents:
ENERGY=20 GeV
Your local .env file also includes the JDBC_DATABASE_URL variable if you set it during the Run the App Locally step.
Don’t commit the .env file to version control as it often includes secure credentials. Include .env in your repo’s .gitignore file. The sample app repo only includes a .env file as an example for this tutorial step.
Run the app with heroku local --port 5001 and visit http://localhost:5001/convert to see the conversion value for 20 GeV.
Now that you know it works as expected locally, set this variable as a config var on your app running on Heroku. Execute the following:
$ heroku config:set ENERGY="20 GeV"
Setting ENERGY and restarting ⬢ peaceful-inlet-84135... done, v9
ENERGY: 20 GeV
View the app’s config vars using heroku config to verify you’ve done it correctly:
$ heroku config
=== peaceful-inlet-84135 Config Vars
DATABASE_URL: postgres://avhrhofbiyvpct:3ab23026d0fc225bde4544cedabc356904980e6a02a2418ca44d7fd19dad8e03@ec2-23-21-4-7.compute-1.amazonaws.com:5432/d8e8ojni26668k
ENERGY: 20 GeV
PAPERTRAIL_API_TOKEN: ChtIUu9fHbij1cBn7y6z
Deploy your local changes to Heroku and visit the /convert route to see your changes in action:
$ git add .
$ git commit -m "Use ENERGY environment variable"
$ git push heroku main
$ heroku open /convert
Start a One-off Dyno
The heroku run command lets you run maintenance and administrative tasks on your app in a one-off dyno. It also lets you launch a REPL process attached to your local terminal for experimenting in your app’s environment or your deployed application code:
$ heroku run java -version
Running java -version on ⬢ peaceful-inlet-84135... up, run.4406 (Eco)
openjdk version "17.0.6" 2023-01-17 LTS
OpenJDK Runtime Environment Zulu17.40+19-CA (build 17.0.6+10-LTS)
OpenJDK 64-Bit Server VM Zulu17.40+19-CA (build 17.0.6+10-LTS, mixed mode, sharing)
If you receive an error, Error connecting to process, configure your firewall.
Remember to type exit to exit the shell and terminate the dyno.
Next Steps
Congratulations! You now know how to deploy an app, change its configuration, scale it, view logs, attach add-ons, and run it locally.
Here’s some recommended reading to continue your Heroku journey:
- How Heroku Works provides a technical overview of the concepts encountered while writing, configuring, deploying, and running apps.
- The Clojure category provides more in-depth information on developing and deploying Clojure apps.
- The Deployment category provides a variety of powerful integrations and features to help streamline and simplify your deployments.