Deploy a Clojure Luminus App
Luminus is a Clojure micro-framework based on a set of lightweight libraries. It aims to provide a robust, scalable, and easy to use platform. With Luminus you can focus on developing your app the way you want without any distractions.
This guide covers how to deploy a Luminus app to Railway in four ways:
Now, let's create a Luminus app!
Create a Luminus App
Note: If you already have a Luminus app locally or on GitHub, you can skip this step and go straight to the Deploy Luminus App to Railway.
To create a new Luminus app, ensure that you have JDK and Leiningen installed on your machine.
Run the following command in your terminal to create a new Luminus app with Postgres and a production ready server:
lein new luminus helloworld +postgres +immutant
A new Luminus app will be provisioned for you in the helloworld
directory with support for PostgreSQL as the database and configures Immutant as the web server, which is production-ready and optimized for Clojure applications.
Note: If you use MySQL or another database, you can pass it as an option when trying to create a new app.
Run the Luminus App Locally
Open dev-config.edn
and add your Postgres database URL like so:
:database-url "postgresql://username:[email protected]:5432/helloworld_dev"
username:password
is your database user and password.helloworld_dev
is the database you have created locally.
Next, run lein run migrate
to run the database migrations.
Finally, run lein run
to launch your app!
Open your browser and go to http://localhost:3000
to see the app.
Prepare Clojure Luminus App for Deployment
- We need to add the
ceshire
library to our dependencies.cheshire
is a popular JSON encoding/decoding library in Clojure.
Open your project.clj
file and ensure you have the following under :dependencies
:
...
[cheshire "5.10.0"]
Run the command below in your terminal to ensure it is installed:
lein deps
- Create a
nixpacks.toml
file in the root directory of the app.
The nixpacks.toml file is a configuration file used by Nixpacks, a build system developed and used by Railway, to set up and deploy applications.
In this file, you can specify the instructions for various build and deployment phases, along with environment variables and package dependencies.
Add the following content to the file:
# nixpacks.toml
[start]
cmd = "java -jar $(find ./target -name '*.jar' ! -name '*SNAPSHOT*') migrate && java -jar $(find ./target -name '*.jar' ! -name '*SNAPSHOT*')"
Here, we are specifically instructing Nixpacks to use the following command to start the app.
The command searches for all .jar
files in the target
directory (where the standalone JAR file is located after the build), excludes any file with "SNAPSHOT" in its name, and passes the selected file to java -jar
to run.
It starts by running the JAR file with the migrate
option to apply database migrations. Once migrations are complete, it reruns the JAR file to launch the application.
Deploy the Luminus App to Railway
Railway offers multiple ways to deploy your Clojure app, depending on your setup and preference.
One-Click Deploy From a Template
If you’re looking for the fastest way to get started, the one-click deploy option is ideal.
Click the button below to begin:
We highly recommend that you eject from the template after deployment to create a copy of the repo on your GitHub account.
Note: You can also choose from a variety of Clojure app templates created by the community.
Deploy From the CLI
- Install the Railway CLI:
- Install the CLI and authenticate it using your Railway account.
- Initialize a Railway Project:
- Run the command below in your Luminus app directory.
railway init
- Follow the prompts to name your project.
- After the project is created, click the provided link to view it in your browser.
- Run the command below in your Luminus app directory.
- Add a Postgres Database Service:
- Run
railway add -d postgres
. - Hit Enter to add it to your project.
- A database service will be added to your Railway project.
- Run
- Add a Service and Environment Variable:
- Run
railway add
. - Select
Empty Service
from the list of options. - In the
Enter a service name
prompt, enterapp-service
. - In the
Enter a variable
prompt, enterDATABASE_URL=${{Postgres.DATABASE_URL}}
.- The value,
${{Postgres.DATABASE_URL}}
, references the URL of your new Postgres database. Learn more about referencing service variables.
- The value,
- Run
- Deploy the Application:
- Run
railway up
to deploy your app.- This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
- Once the deployment is complete, we can proceed to generate a domain for the app service.
- Run
- Set Up a Public URL:
- Run
railway domain
to generate a public URL for your app. - Visit the new URL to see your app live in action!
- Run
Deploy From a GitHub Repo
To deploy a Clojure Luminus app to Railway directly from GitHub, follow the steps below:
-
Create a New Project on Railway:
- Go to Railway to create a new project.
-
Deploy from GitHub:
- Select Deploy from GitHub repo and choose your repository.
- If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
- Select Deploy from GitHub repo and choose your repository.
-
Add Environment Variables and Provision a Database Service:
- Click Add Variables, but hold off on adding anything just yet. First, proceed with the next step.
- Right-click on the Railway project canvas or click the Create button, then select Database and choose Add PostgreSQL.
- This will create and deploy a new PostgreSQL database for your project.
- Once the database is deployed, you can return to adding the necessary environment variables:
DATABASE_URL
: Set the value to${{Postgres.DATABASE_URL}}
(this references the URL of your new Postgres database). Learn more about referencing service variables.
-
Deploy the App Service:
- Click Deploy on the Railway project canvas to apply your changes.
-
Verify the Deployment:
- Once the deployment completes, go to View logs to check if the server is running successfully.
Note: During the deployment process, Railway will automatically detect that it’s a Clojure app.
-
Set Up a Public URL:
- Navigate to the Networking section under the Settings tab of your new service.
- Click Generate Domain to create a public URL for your app.
Use a Dockerfile
- Create a
Dockerfile
in the Luminus app's root directory. - Add the content below to the
Dockerfile
:# Use the Clojure official image # https://hub.docker.com/_/clojure FROM clojure:temurin-23-lein-bookworm # Create and change to the app directory. WORKDIR /app # Copy local code to the container image. COPY . ./ # Build the app. RUN lein uberjar # Run the app by dynamically finding the standalone JAR file in the target/uberjar directory CMD ["sh", "-c", "java -jar $(find target/uberjar -name '*.jar' ! -name '*SNAPSHOT*')"]
- Either deploy via the CLI or from GitHub.
Railway automatically detects the Dockerfile
, and uses it to build and deploy the app.
Note: Railway supports also deployment from public and private Docker images.
This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Clojure apps seamlessly!
Next Steps
Explore these resources to learn how you can maximize your experience with Railway:
Edit this file on GitHub