Kamal deploys Docker containers to plain servers. It builds your image, pushes it to a registry, then connects to each server over SSH and swaps the old container for the new one behind its own proxy, without dropping requests. There’s no control plane and nothing to install on the servers beyond Docker, which Kamal sets up for you.

It’s the simplest setup I’ve found that still gives you zero-downtime deploys, automatic HTTPS and easy rollbacks. This is a practical guide to getting an app running with it, plus the settings worth changing before real traffic arrives.

What you need

  • An app with a Dockerfile.
  • A Linux machine you can SSH into as a user with sudo. A cheap VPS is plenty, and so is a Raspberry Pi.
  • A container registry: Docker Hub, GitHub’s, or your cloud provider’s.
  • A domain pointing at the server, if you want Kamal to handle HTTPS.

Install and initialise

Kamal is a Ruby gem (there’s also a Docker image if you’d rather not install Ruby). From your app’s directory:

terminal
gem install kamal
cd my-app
kamal init # creates config/deploy.yml and .kamal/secrets

The config

Everything lives in one file. A minimal version for a single web app looks like this:

config/deploy.yml
service: my-app
image: my-user/my-app
servers:
web:
hosts:
- 192.0.2.10
proxy:
host: app.example.com
ssl: true
app_port: 3000
healthcheck:
path: /up
registry:
server: ghcr.io
username: my-user
password:
- KAMAL_REGISTRY_PASSWORD
builder:
arch:
- amd64
env:
clear:
NODE_ENV: production
secret:
- DATABASE_URL

Taking it a section at a time:

  • service names the app, and Kamal uses it to name containers. image is where the image lives in your registry.
  • servers lists hosts by role. web is the role that serves traffic.
  • proxy configures kamal-proxy, which runs on each server and routes requests to your container. With ssl: true it gets a Let’s Encrypt certificate for host automatically. app_port is the port your app listens on inside the container.
  • The healthcheck path must return a 200 once the app is ready. Kamal won’t send traffic to a new container until it does.
  • builder.arch sets the architecture to build for. Match your servers, especially if you build on an Apple Silicon laptop and deploy to x86, or the other way round. ARM servers and Raspberry Pis want arm64.
  • env.clear is plain configuration. env.secret lists names whose values come from .kamal/secrets.

Secrets

.kamal/secrets maps each secret to where its value comes from, usually an environment variable or a password manager command. Commit the file if it only contains references like these, never actual values.

.kamal/secrets
# .kamal/secrets: read from your environment, never committed with values
KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
DATABASE_URL=$DATABASE_URL

Kamal injects the values into the container at deploy time, so they never live in the image or the repo. kamal secrets print shows what it resolved, which is handy when a deploy complains that one is missing.1

Accessories

Accessories are the long-lived services around your app: a database, Redis, a search engine. You boot them once and deploys leave them alone. Each runs in its own container on a host you choose:

config/deploy.yml
accessories:
redis:
image: redis:7-alpine
host: 192.0.2.10
# Bind to localhost only: reachable from the app, not the internet
port: "127.0.0.1:6379:6379"
directories:
- data:/data

Your app reaches an accessory by its container name, <service>-<accessory>, over the Docker network Kamal creates, so here the Redis URL would be redis://my-app-redis:6379. Bind any ports you publish to 127.0.0.1 so that only the server itself can reach them, never the public internet.

For a production database I’d still use a managed one rather than an accessory. Backups and upgrades are someone else’s problem, and the app servers become disposable.

The first deploy

terminal
kamal setup # first time: installs Docker, boots the proxy and accessories, deploys
kamal deploy # every time after that

A deploy builds and pushes the image, starts the new container next to the old one, and waits for the health check. When it passes, kamal-proxy moves traffic across and the old container stops. If it never passes, the old container keeps serving and the deploy fails. Nothing breaks for users either way, which is most of the point.

Day to day

terminal
kamal app logs -f # follow the app's logs
kamal app exec -i --reuse bash # a shell inside the running container
kamal rollback <version> # go back to an earlier release
kamal app details # what's running where
kamal accessory boot redis # start an accessory that isn't running
kamal accessory reboot redis # restart one after changing its config

Rollbacks are quick because the previous containers are still on the server. Kamal starts the old version and moves traffic back, with no rebuild.

Settings worth changing

The defaults are sensible for a small Rails app. For anything heavier, these are the ones worth looking at:

config/deploy.yml
# Default 30s. Raise it if your app is slow to boot (migrations count).
deploy_timeout: 180
# Default 5. Old releases are kept for rollback and their images use disk.
retain_containers: 2
proxy:
# Default 30s. Raise it if some requests legitimately take longer.
response_timeout: 60
builder:
# Build for the servers' architecture, not your laptop's.
arch:
- arm64
# Reuse layers between builds instead of starting from scratch.
cache:
type: registry
  • Deploy timeout. Kamal gives a new container 30 seconds to become healthy. Anything that runs migrations on boot or loads a lot of modules can need longer, and if it runs out, Kamal kills a container that was about to be fine.
  • Response timeout. kamal-proxy cuts off any request after 30 seconds. If some requests genuinely take longer, raise it, but keep it below any timeout in front of the server, like a CDN’s.
  • Retained containers. Each old release keeps its image on disk. With large images on a small disk, five of them add up quickly. One or two is usually enough to roll back to.
  • Build cache. A registry cache stops every build reinstalling the same system packages, which matters a lot once your image has large dependencies.

Putting it behind Cloudflare

Kamal works well behind Cloudflare, or any CDN, if you set it up so the two don’t fight:

  • Proxy your DNS records through Cloudflare and set SSL/TLS to Full (strict). kamal-proxy still serves a valid Let’s Encrypt certificate, so traffic is encrypted all the way to the server.
  • Don’t block or challenge /.well-known/acme-challenge/. Let’s Encrypt renews certificates through it, and if it’s blocked nothing goes wrong until the certificate expires a couple of months later.
  • Have your server’s firewall accept web traffic only from Cloudflare’s published IP ranges, so nobody can go around Cloudflare by visiting the server’s IP directly. Keep SSH locked down to your own addresses or keys.

More than one process

When an app needs background workers, add another role. It runs the same image with a different command, on the same server or a different one, and deploys alongside the web role:

config/deploy.yml
servers:
web:
hosts:
- 192.0.2.10
worker:
hosts:
- 192.0.2.10
cmd: npm run worker

Only the web role sits behind the proxy. Splitting work this way early is worth it: heavy background jobs then can’t slow down the requests your users are waiting on.

Why Kamal

If you look after your own infrastructure, it has to be something you can understand end to end and fix late at night. Managed platforms are the quickest start but get awkward once an app needs Redis, search or long-running background jobs. Kubernetes or ECS handle all of that, with far more moving parts than most small apps need.

Kamal sits in the gap. Servers are plain Linux boxes with Docker, the whole deployment is a YAML file in the repo, and when something goes wrong it’s usually something you can see, understand and fix in that file. If the app outgrows a couple of servers, the same config deploys to more of them.

It’s also cheap. Kamal itself is free, and because it only needs a machine with SSH and Docker, you can run on whatever server is good value rather than paying a platform’s markup. A small VPS costs a few pounds a month, and an ARM one often gets you more for the money. There’s nothing to pay for that sits idle between deploys: no load balancer, no cluster, no control plane.

You could even deploy to a Raspberry Pi on your desk. Set builder.arch to arm64 and point hosts at it. Serving it to the internet takes a bit more, a forwarded port or a tunnel such as Cloudflare Tunnel, but for side projects and internal tools it works.