Back to guides

Ruby on Rails

Deploying Rails 8 with Kamal 2: Zero-Downtime Setup, Pitfalls & Rollbacks

DEVRUBY engineering team 7 min read

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:

  1. Deploy 1: add the new column or table (nullable or with a default), and write to both columns if renaming.
  2. Backfill existing rows in a background job or rake task once Deploy 1 is live.
  3. Deploy 2: switch reads to the new column and add ignored_columns for the old one.
  4. 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.

More guides

Ruby on Rails

Rails 7 to 8 Upgrade Guide: What Breaks and How to Plan the Upgrade

How to upgrade a production app from Rails 7 to Rails 8: the version path, the Ruby requirement, the changes that actually break code, and a safe rollout plan.

AI workflow automation

AI Automation for Small Businesses: What to Automate First and What to Leave to People

How small businesses can choose their first AI automation: where language models remove real work, where simple rules work better, and how to stay in control.