by Andrew Vogel on April 1, 2025

I recently got the chance to build a small internal tool for our team. And when it came time to deploy, I really wanted to try out Kamal, the new deployment tool built by Basecamp (37Signals). It was easier than I had first anticipated.

Kamal is a CLI and deployment scripting tool that allows you to setup servers and subsequently deploy your app to them. You can use this to deploy many types of applications, you just need a Dockerfile and some changes to Kamal's configuration. It's different from using a managed hosting provider like Render or Heroku. But it affords you the ability to easily ship containerized apps to raw servers - either ones that you host yourself or Digital Ocean Droplets, EC2, or GCP.

Generally speaking, this has cost benefits as these raw resources are usually cheaper. At the time of writing, the cheapest Digital Ocean droplet is $4 a month and usually sufficient for a small footprint app. And it's also important to note that Kamal isn't just for Rails.

Today, I want to briefly cover some things that I learned about Kamal while building this app.

If you're going to use Kamal, it's necessary to loosley understand what it's doing.

The top 3 files we will focus on are -

1. config/deploy.yml - the main deployment configuration file
2. .kamal/secrets
3. Dockerfile - this is generated by Rails in new projects

The Kamal Setup docs are a great starting point, but I'll summarize some of the points below.

• It sets up dependencies on your application server - such as installing Docker.
• It builds your container image locally.
• It pushes your container image to your registry of choice - DockerHub, Github Container Registry, Microsoft Container Registry, etc.
• It pulls your image onto your application server.
• It swaps over the running images.
• It generates SSL certificates for your domain/DNS via Let's Encrypt
• Proxies traffic to your images for a zero downtime deploy.

As previously stated, the latest version of Rails 8 comes with Kamal and a Dockerfile. You can easily bootstrap your deployment by changing a few settings in the config/deploy.yml file. Then it's as simple as kamal deploy.

You'll need 2-3 things to get going with Kamal -

1. A hosting provider - in my case a Digital Ocean Droplet.
2. Configure your DNS with your server IP (optional)
3. Choose a container registry for your image. (Kamal requires this currently and has noted they are working on trying to change this in the future.)

Next you just need to configure a few details for deployment in deploy.yml. Those things are -

• The name of your container image - username/my_app (required)
• The IP of the server you are deploying to (required)
• The web address you configured with Hosting Provider (necessary for SSL)
• The user for your application server (optional)
• The registry username where the image is deployed to (required)

Here's a trimmed example of what that looks like

service: my_app

image: username/my_app

servers:
  web:
    - 192.168.0.1

proxy:
  ssl: true
  host: my_app.example.com

registry:
  server: ghcr.io
  username: registry_username

  # Always use an access token rather than real password when possible.
  password:
    - KAMAL_REGISTRY_PASSWORD

# Inject ENV variables into containers (secrets come from .kamal/secrets).
env:
  secret:
    - RAILS_MASTER_KEY
  clear:
    SOLID_QUEUE_IN_PUMA: true

aliases:
  console: app exec --interactive --reuse "bin/rails console"
  shell: app exec --interactive --reuse "bash"
  logs: app logs -f
  dbc: app exec --interactive --reuse "bin/rails dbconsole"

volumes:
  - "my_app_storage:/rails/storage"


asset_path: /rails/public/assets

builder:
  arch: amd64

Other items you may need to change for Kamal include -

• KAMAL_REGISTRY_PASSWORD - In my case, I used GHCR. This is not your account password, but rather a Personal Access Token. If you use GHCR, you'll need to create a PAT on Github with permissions for delete:packages, repo, and write:packages. You set this either in the environment or expand via .kamal/secrets (see below).
• .kamal/secrets - This file is used to for the build process should NOT contain any sensitive credentials as this is committed to version control. If you need senstive values, you can expand them out of the environment or use the kamal secrets API. For example, the first time I deployed my app, I explicitly set the KAMAL_REGISTRY_PASSWORD via the command line. KAMAL_REGISTRY_PASSWORD=xxxxxx kamal deploy

At this point you should be ready for your first deploy!

KAMAL_REGISTRY_PASSWORD=xxxxxx kamal setup

The next time you deploy, you can just run deploy -

KAMAL_REGISTRY_PASSWORD=xxxxxx kamal deploy

Note on Secrets

• Something that got me while deploying was the assets:precompile step. During the build, kamal swaps out your RAILS_MASTER_KEY with a dummy value. If you have calls to Rails.credentials in any initilizers, this step may fail if you don't safe navigate (&.).
• In addition, you can use a secrets manager to expand your secrets out of secrets manager like 1Password.

The default deploy.yml comes with configuration for commonly used commands. You can also add your own aliases!

aliases:
  console: app exec --interactive --reuse "bin/rails console"
  shell: app exec --interactive --reuse "bash"
  logs: app logs -f
  dbc: app exec --interactive --reuse "bin/rails dbconsole"

Follow the Logs

kamal logs

Console Access - Rails Console

kamal console

Interactive Shell/Bash

kamal shell

State a Database Console

kamal dbc

Lastly, Kamal has a facility for removing old container images on your server. By default it keeps the last 5 images. But I like to remove any unused when possible. You can accomplish this with -

kamal prune images

I'm really pleased with what Kamal has to offer. It makes deployment to bare metal, what was once a complicated process, more approachable. I can see the value in this tool, especially for small teams. This blog barely scratches the surface for Kamal's API, so I highly recommend checking out the docs.

If you're interested in switching your app over to Kamal, we'd be happy to help you out.

Until next time!

Image by Ian Taylor on Unsplash