DEV Community: EXO

The complete Kamal 2 deploy.yml for a real Rails app: Postgres, Sidekiq, Redis and backups on one Hetzner box

EXO — Sat, 05 Sep 2026 23:36:58 +0000

Most Kamal tutorials stop at "hello world on one server". Real apps have a database, a background queue, a cache, cron jobs, file uploads that must survive a deploy, and a healthcheck that has to pass before traffic switches over. Here is the whole config/deploy.yml I use for that, on a single Hetzner box, with an explanation of every block that isn't obvious.

This is Kamal 2 (the one with kamal-proxy, not Traefik) and Rails 8.

The shape of the thing

One server, one app container, two accessories: Postgres and Redis. A separate role for the Sidekiq worker, running the same image with a different command. kamal-proxy terminates TLS and holds requests during the swap.

service: myapp
image: yourname/myapp

servers:
  web:
    hosts:
      - 5.161.0.0
  worker:
    hosts:
      - 5.161.0.0
    cmd: bundle exec sidekiq -C config/sidekiq.yml

proxy:
  ssl: true
  host: app.example.com
  app_port: 3000
  healthcheck:
    path: /up
    interval: 3
    timeout: 30

registry:
  server: ghcr.io
  username: yourname
  password:
    - KAMAL_REGISTRY_PASSWORD

builder:
  arch: amd64
  cache:
    type: registry

env:
  clear:
    RAILS_ENV: production
    RAILS_LOG_TO_STDOUT: "1"
    RAILS_SERVE_STATIC_FILES: "1"
    DB_HOST: myapp-db
    REDIS_URL: redis://myapp-redis:6379/0
  secret:
    - RAILS_MASTER_KEY
    - POSTGRES_PASSWORD

accessories:
  db:
    image: postgres:16
    host: 5.161.0.0
    port: "127.0.0.1:5432:5432"
    env:
      clear:
        POSTGRES_USER: myapp
        POSTGRES_DB: myapp_production
      secret:
        - POSTGRES_PASSWORD
    directories:
      - data:/var/lib/postgresql/data
  redis:
    image: redis:7-alpine
    host: 5.161.0.0
    port: "127.0.0.1:6379:6379"
    cmd: redis-server --appendonly yes
    directories:
      - data:/data

volumes:
  - "myapp_storage:/rails/storage"

asset_path: /rails/public/assets

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

Now the parts that bite.

`DB_HOST` is the accessory's container name, not localhost

Kamal names accessory containers <service>-<accessory>. So the db accessory of service myapp is reachable from the app container at the hostname myapp-db. Not localhost, not 127.0.0.1 — those point at the app container itself. This single line is behind a large share of "the app boots and immediately dies" reports.

Bind accessory ports to 127.0.0.1

Note the "127.0.0.1:5432:5432" rather than "5432:5432". The second form publishes Postgres on the public interface, and Docker writes its own iptables rules that bypass ufw — so your firewall reports port 5432 as closed while the internet can reach it. Bind to loopback and reach the database over an SSH tunnel when you need psql from your laptop:

ssh -L 5432:localhost:5432 deploy@5.161.0.0

Two roles, one server, one image

The worker role has the same host as web. Kamal builds one image and starts a second container from it with cmd overridden. You do not need a separate Dockerfile, a separate build, or a separate server to run Sidekiq. When you outgrow the box, you change the hosts list under worker and nothing else.

If you're on Solid Queue instead, set SOLID_QUEUE_IN_PUMA to false and run it as its own role the same way — leave it inside Puma and your jobs get killed mid-flight on every deploy.

The healthcheck decides whether your deploy is a deploy

kamal-proxy will not send traffic to the new container until /up returns 200. Rails 8 routes that by default. Two things people get wrong:

interval: 3, timeout: 30 means ten attempts. If your app takes 40 seconds to boot (heavy initializers, slow migrations), the deploy fails while the app is perfectly fine. Raise the timeout instead of removing the check.
Make /up mean something. The default only proves Rails booted. If a broken database connection should block a deploy, point it at a controller that touches the database:

# config/routes.rb
get "up" => "health#show"

# app/controllers/health_controller.rb
class HealthController < ApplicationController
  def show
    ActiveRecord::Base.connection.execute("SELECT 1")
    head :ok
  rescue StandardError
    head :service_unavailable
  end
end

Do not check Redis or third-party APIs here. A healthcheck that fails when Stripe is slow will refuse to deploy your app during a Stripe outage.

`asset_path` prevents the 404 flash

During the swap, both containers run. A browser that loaded the old HTML asks for the old fingerprinted asset, and the new container doesn't have it. asset_path: /rails/public/assets tells Kamal to keep both sets available during the overlap. One line, and the mystery 404s during deploys go away.

Volumes are the only thing that survives

Everything written inside a container is gone on the next deploy. Two consequences:

Active Storage's local disk service needs the myapp_storage volume above, with config/storage.yml pointing at Rails.root.join("storage").
The Postgres accessory needs its directories: entry, or your database goes away the first time you rebuild that accessory. Yes, really.

Cron

Do not install cron on the host. Use solid_queue's recurring tasks or sidekiq-cron, both of which live inside the worker you already have. A separate cron container that runs rails runner is a third thing to debug at 2am, and it will drift from your app's code the first time you forget to redeploy it.

Backups, because a volume is not a backup

A volume protects you from deploys, not from DROP TABLE, a disk failure, or your provider having a bad day. The smallest thing that works, on the host, nightly:

docker exec myapp-db pg_dump -U myapp myapp_production \
  | gzip > /var/backups/myapp-$(date +%F).sql.gz

Then push it off the machine — any S3-compatible bucket will do. A backup on the same disk as the database is a rehearsal, not a backup. And a backup you have never restored is a guess: restore one into a scratch database this week, before you need it.

What this costs

A CPX21 at Hetzner (3 vCPU, 4 GB) runs about €8/month and comfortably holds Rails, Postgres, Redis and Sidekiq for a small production app. The €4 tier works too if you add swap — Tailwind and esbuild will otherwise get OOM-killed during assets:precompile.

I keep this as a kit: the deploy.yml above, plus scripts that create and harden the Hetzner box through the API, set up the Cloudflare DNS record and SSL mode, run 15 preflight checks before the first kamal setup, and install the nightly backup to S3. It's $10 here: https://payhip.com/b/yrO3i

And if you'd rather not do any of it: I'll do the whole setup on your server for $150 — server created and hardened, DNS and SSL, Kamal configured, first deploy done, backups running, and a walkthrough at the end. You keep every account; nothing to pay until it's deployed and working. Email me at gilbergarciata@gmail.com.

Either way, ask in the comments — I'll answer Kamal, Hetzner and Cloudflare questions whether or not you buy anything.

The 14 errors you will hit deploying Rails with Kamal on Hetzner behind Cloudflare (and the fix for each)

EXO — Sat, 05 Sep 2026 21:50:29 +0000

I run every one of my side projects the same way: a Rails 8 app, a €4/month Hetzner box, Kamal 2, Cloudflare in front. It's cheap and it works. But the first deploy of every new project costs me an evening, and it's almost always one of the same 14 mistakes. Here they are, with the fix for each, in the order you'll probably hit them.

1. `hcloud: command not found`

You're creating the server from a script and the Hetzner CLI isn't installed. brew install hcloud on macOS, or grab the binary from the GitHub releases page. Create a Read & Write API token in the Hetzner console (project → Security → API tokens).

2. `Permission denied (publickey)` right after the server boots

The key you uploaded to Hetzner isn't the one your ssh-agent offers. Run ssh-add ~/.ssh/id_ed25519, or point your bootstrap at the key you actually use. If the box was created with the wrong key, delete it and recreate — it's 30 seconds.

3. `docker: permission denied` during `kamal setup`

Your deploy user isn't in the docker group yet (cloud-init still running) or you connected before usermod ran. Wait a minute, or sudo usermod -aG docker deploy and reconnect. Kamal 2 defaults to root; if you use a non-root user, set ssh.user in deploy.yml.

4. `Missing secret 'KAMAL_REGISTRY_PASSWORD'`

Kamal reads .kamal/secrets, which reads your environment. If your secrets live in a .env file, source it first: set -a; . ./.env; set +a. A Makefile that sources the file before every kamal command removes this class of bug entirely.

5. `denied: permission_denied: write_package` (ghcr.io)

The GitHub token needs write:packages and read:packages. Fine-grained tokens don't support packages — use a classic token.

6. `exec format error` on the server

You built the image on an Apple Silicon Mac and shipped an arm64 image to an amd64 box. Set builder.arch: amd64 in deploy.yml, and make sure Docker Desktop has a multi-arch builder (docker buildx create --use once).

7. "Waiting for app to boot" then the healthcheck fails

Get the real error with kamal app logs. Four usual suspects:

RAILS_MASTER_KEY is wrong → ActiveSupport::MessageEncryptor::InvalidMessage.
The DB isn't reachable → DB_HOST must equal the accessory container name (<service>-db), and POSTGRES_PASSWORD must match what the accessory was booted with. Changed the password after first boot? kamal accessory remove db then kamal accessory boot db.
Your app listens on a port other than 3000 → set proxy.app_port.
/up isn't routable (Rails < 7.1) → add get "up" => "rails/health#show" or change proxy.healthcheck.path.

8. `ERR_TOO_MANY_REDIRECTS` in the browser

Cloudflare's SSL mode is Flexible. Set it to Full (strict) — kamal-proxy already has a valid Let's Encrypt cert, so Cloudflare can talk HTTPS to your origin.

9. Let's Encrypt fails: `acme: error 403` / connection refused

Cloudflare's proxy (orange cloud) was on during the first certificate issuance, or DNS hadn't propagated. Keep the record DNS-only (grey cloud) for the very first kamal setup, confirm dig +short app.example.com returns the server IP, run kamal proxy reboot, retry. Turn the proxy on afterwards.

10. Assets 404 for a few seconds after every deploy

The old container stops serving old fingerprints during the swap. Add asset_path: /rails/public/assets to deploy.yml so both containers can serve both sets of assets during the overlap.

11. Uploads disappear after a deploy

They were written inside the container. Active Storage's local disk must live on a volume: mount <app>_storage:/rails/storage in deploy.yml and keep config/storage.yml pointing at Rails.root.join("storage").

12. The build dies with an out-of-memory error during `assets:precompile`

Small boxes plus Tailwind/esbuild. Add 2 GB of swap in your cloud-init (fallocate -l 2G /swapfile …), build locally instead of builder.remote, or move up one server size.

13. Every deploy takes 5+ minutes

Docker layer cache isn't reused. Your Dockerfile must copy Gemfile* and run bundle install before COPY . . (the Rails 8 Dockerfile does this). Also check you're not pushing a 2 GB image: docker images | head.

14. You have no idea what Kamal is doing

kamal deploy --verbose. To see the configuration exactly as Kamal parsed it: kamal config.

The part I got tired of redoing

The fixes above are easy once you know them. What's annoying is doing the setup by hand every time: creating the server, hardening it, opening the firewall, the Cloudflare records, the SSL mode, the secrets, checking everything before kamal setup.

So I scripted it. make server creates and hardens the box through the Hetzner API (Docker, deploy user, ufw 22/80/443, fail2ban, unattended upgrades, swap, sshd lockdown). make dns creates the A record and sets SSL Full (strict) through the Cloudflare API. make check runs 15 preflight checks. make first runs kamal setup. It also includes nightly Postgres backups to any S3-compatible bucket, a GitHub Actions deploy workflow, and this troubleshooting doc.

If it's useful to you, it's $10 here: https://payhip.com/b/yrO3i — with a refund if it doesn't save you an evening. Either way, happy to answer Kamal/Hetzner/Cloudflare questions in the comments.

Don't want to do it at all?

If you'd rather not spend the evening, I'll do the whole setup on your server for $150: Hetzner box created and hardened, Cloudflare DNS and SSL, Kamal 2 configured, first deploy done, nightly Postgres backups to S3, and a walkthrough of how to deploy from then on. You keep everything — the server, the domain, the accounts are all yours; I just set it up and hand it over. Nothing to pay until it's deployed and working.

Email me at gilbergarciata@gmail.com and tell me what the app is.