Start shipping →

Answers · Deploying

What do I need before a first deploy to production?

Four things: a Linux server you can SSH into, somewhere to push a container image, a domain pointed at the server, and RAILS_MASTER_KEY. That last one is the only secret production will not boot without. Billing, email and bot checking all fall back to in-process fakes, so you can ship before you have those keys.

Updated · 2 min read

The four, in order

A server. Any Linux host with SSH access and 2GB of memory. Kamal installs Docker itself if it is missing, so a bare Ubuntu image is enough.

A registry. Docker Hub or GitHub Container Registry both work. This is where the built image goes so the server can pull it.

A domain. One A record at the server's IP. Kamal's proxy requests a certificate on the first request, so HTTPS needs no separate step.

RAILS_MASTER_KEY. Rails cannot decrypt credentials without it and raises during boot, so the deploy fails on the health check rather than serving a broken page.

bin/kamal setup
curl -sI https://yourdomain.com/up | head -1

What you do not need yet

This is the part that surprises people. Every external integration in the kit sits behind an adapter with a deterministic local fake, wired the way app/adapters/billing.rb shows: a real client when the credential is present, a fake when it is not. So a first deploy needs no Stripe account, no Resend account and no OAuth application. Checkout runs end to end against the fake, email opens locally instead of sending, and nothing raises.

Add each key when you actually want that integration live. docs/BRING_YOUR_OWN_KEYS.md lists all of them and marks which are optional, which is all of them except the master key.

Two settings worth doing on day one anyway

APP_HOST, so mailer links and the sitemap are absolute. And a statement descriptor in Stripe, before you charge anyone, because it is what appears on a customer's card statement and changing it later does not change past charges.

How long it takes

The first kamal setup runs five to ten minutes, mostly installing Docker and building the image for the first time. Deploys after that are one to three minutes, dominated by the image build. Nothing in that path needs you to watch it.

Related questions

Why does Kamal fail with pull access denied on deploy?

The server cannot log in to the registry that holds your image. Kamal pushes from your machine, where you are already authenticated, then asks the server to pull, where it is not. Check the registry block in config/deploy.yml names the right username, and that KAMAL_REGISTRY_PASSWORD is actually set in .kamal/secrets.

Why does a Kamal deploy hang on the health check?

The new container started and exited before Rails could answer /up. Kamal waits, then rolls back and leaves the old container serving. Run kamal app logs to see the real error. On a first deploy it is almost always a missing or wrong RAILS_MASTER_KEY, which raises before any route exists to answer the check.

Can I run SQLite in production for a Rails app?

Yes, for one server. Rails 8 ships SQLite configured for production use, and One Shot runs on it: the database is a file on a mounted volume, backups are a file copy, and there is no second service to operate. The limit is real though. Two application servers cannot write to the same SQLite file, so horizontal scaling is where it stops.