Ruby on Rails
Deploying Rails 8 with Kamal 2: Zero-Downtime Setup, Pitfalls & Rollbacks
Rails 8 ships with Kamal 2 as its default deployment tool, replacing PaaS lock-in with Docker containers on your own Linux servers. The promise is simple: zero-downtime deploys, automatic TLS via Let's Encrypt, and predictable hosting bills. In practice, teams upgrading from Capistrano or Heroku run into three predictable traps: database migrations that break the previous release mid-deploy, slow app boots hitting deploy_timeout, and missing rollback habits. This guide walks through how kamal-proxy handles traffic and what to configure before your first production push.
Planning a Rails or Ruby upgrade? Book a free 30-minute second opinion on your upgrade path, risky gems, or agency quote.How kamal-proxy achieves zero-downtime deploys
On every deploy, Kamal builds your Docker image, pushes it to a registry, and starts the new container alongside the running one on the target host. Rather than stopping traffic, kamal-proxy sends HTTP healthcheck requests to the new container (by default GET /up, which Rails 8 includes out of the box).
Only after /up returns HTTP 200 does kamal-proxy switch incoming traffic to the new container. In-flight requests on the old container are given a grace period to finish before the old container stops. If the healthcheck fails or times out, traffic never moves and your users see zero errors.
The migration trap: two versions run at the same time
Because old and new containers overlap during the cutover — and because you may need to roll back — your database schema must be compatible with both releases at once. Running a destructive migration during deploy (such as dropping or renaming a column that the old container still queries) causes immediate 500 errors.
Treat breaking schema changes as a two-deploy sequence instead of a single migration:
- Deploy 1: add the new column or table (nullable or with a default), and write to both columns if renaming.
- Backfill existing rows in a background job or rake task once Deploy 1 is live.
- Deploy 2: switch reads to the new column and add ignored_columns for the old one.
- Deploy 3: drop the old column in a later migration after the previous code is completely gone.
Pitfalls that trip up production deploys
Most failed Kamal deploys are configuration mismatches rather than Docker bugs. Check these four items in config/deploy.yml before going live:
- deploy_timeout: the default healthcheck window can be too short for apps with heavy initializers or cold asset precompilation. If boot exceeds deploy_timeout, Kamal aborts the deploy and leaves the old version running — bump deploy_timeout when your app needs more startup headroom.
- Database and Solid Queue separation: running Postgres on a dedicated host (or managed DB) keeps web host restarts clean. If you use SQLite with Solid Queue/Cache/Cable on a single server, make sure persistent volumes are mounted outside the container.
- Secrets via .kamal/secrets: never bake credentials or RAILS_MASTER_KEY into the Dockerfile. Fetch them at deploy time from environment variables or a secret manager.
- Asset digests and CDN caching: keep old fingerprinted assets available briefly or serve via Thruster/CDN so users with an open browser tab during a deploy do not hit 404s on JS/CSS chunks.
Fast rollbacks when something slips through
If a release passes /up but fails on a real business flow, Kamal lets you roll back to the previous image tag with kamal rollback <version> in seconds — without rebuilding Docker images. That only works cleanly if you kept migrations backward-compatible and did not delete the prior image tag from your registry.
Before migrating a production Rails 7 or 8 app off Heroku or an aging Capistrano setup, rehearse one full deploy-and-rollback cycle on a staging VPS so your team knows the exact commands under pressure.
Key takeaways
- kamal-proxy only switches traffic after /up returns 200 and drains in-flight requests on the old container.
- Keep database migrations backward-compatible across at least two releases so zero-downtime cutovers and rollbacks never break.
- Tune deploy_timeout, isolate secrets in .kamal/secrets, and verify persistent storage for SQLite or uploaded files.
- Test kamal rollback on staging before moving production traffic off Heroku or Capistrano.
Related
Want to review your case with context?
Share the codebase, workflow, or systems involved and the result you need. We will use the call to decide a practical next step.