Secret Key Base: One Shot Docs

Secret Key Base

The one required secret, and the two ways to set it.

Every other credential on this docs site is optional. This one isn't: Rails will not boot in production without a secret key base, since it's what signs sessions and cookies. It's also the single most common first-deploy failure, precisely because it never shows up locally: development and test each generate a temporary key automatically, so a fresh clone runs perfectly right up until the first real kamal deploy fails with no obvious clue why.

The kit ships with no credentials file at all, so you generate your own. There are two ways; pick one.

Option 1: encrypted credentials, recommended

bin/rails credentials:edit

This creates config/master.key and config/credentials.yml.enc, with a secret_key_base value already inside. Commit the .enc file; never commit the key itself, which is gitignored by default. Ship RAILS_MASTER_KEY to production, already wired through .kamal/secrets. You'll want encrypted credentials anyway if you're setting up Google or Apple sign-in, since both need credentials stored the same way; see Sign in with Google and Apple.

Option 2: a bare environment variable

Skip credentials entirely:

bin/rails secret

Add the output as SECRET_KEY_BASE in env.secret inside config/deploy.yml, and supply it like any other deploy secret.

Secrets resolve ENV first, then credentials

Everywhere in the app, a secret resolves from the environment first, falling back to Rails encrypted credentials. In production, inject secrets through Kamal secrets (see First Deploy Checklist); locally, use a .env file, copying .env.example as a starting point.

Turn on real transactional email: Email with Resend.

Common questions

How do I rotate an API key without taking the app down?

Create the new key at the provider while the old one still works, set it, deploy, verify the app is using it, and only then revoke the old one. Most providers allow several active keys for exactly this reason. Revoking before deploying is what turns a routine rotation into an outage.

Should I use Rails credentials or environment variables for secrets?

Either. The app reads ENV first and falls back to Rails.application.credentials, so a value set in the environment wins and a value in the encrypted file is the default. Use credentials when you want secrets versioned with the code, and environment variables when a platform or a team already manages them elsewhere.

What does SECRET_KEY_BASE actually do in a Rails app?

It is the root secret Rails derives every other key from: the one that signs session cookies, encrypts encrypted cookies, and verifies signed global ids and Active Storage URLs. Change it and every existing session becomes invalid, so every signed-in user is logged out at the moment of deploy.

What happens if I lose the Rails master key?

The encrypted credentials are gone. RAILS_MASTER_KEY is the only thing that decrypts config/credentials.yml.enc, and there is no recovery path by design. Delete both files, regenerate them, and re-enter every secret from its source. Production will not boot until the key reaching the server matches the file in the repo.