Deployment

This page covers the production-readiness concerns that aren't specific to your hosting provider. The kit ships a Dockerfile and a config/deploy.yml shaped for Kamal, but the same concerns apply if you're running on Fly, Render, Heroku, ECS, or anywhere else that boots a Linux container.

Secrets

Set these in your platform's secret manager. Don't ship .env to production — dotenv-rails only auto-loads in development and test, so they wouldn't be read anyway, but it's the kind of mistake that goes unnoticed until the secrets show up in a backup.

SECRET_KEY_BASE is read from config/credentials.yml.enc (or RAILS_MASTER_KEY). If you don't use encrypted credentials, set SECRET_KEY_BASE directly in the environment.

Database

A few decisions that matter:

• Use the pooler. For Supabase Cloud, the pooler URL (port 6543) is what you want — it shares connections across containers so you don't blow through Postgres' max_connections ceiling. The direct URL (port 5432) is fine for one-off db:migrate, not for the running web container.
• max_connections per container. config/database.yml reads RAILS_MAX_THREADS (default 5) — set it to match your Puma threads setting so the pool size matches concurrency.
• Run migrations once per deploy, before the new image takes traffic. With Kamal, hook this into pre-deploy; with most other platforms, a "release" or "pre-deploy" hook is the right place. Backwards-compatible migrations are non-negotiable during a rolling deploy.
• Solid Cache / Queue / Cable. Production runs on the three additional schemas defined in config/database.yml. bin/rails db:prepare sets them up; the schemas are static (no migrations).

Rate limiting in production

Rack::Attack's throttles count requests in Rails.cache. In development that's an in-process memory store, which is fine. In production with multiple Puma workers and multiple containers, the cache must be shared — otherwise each worker has its own counter and a limit: 300/5min becomes 300 × workers × containers / 5min.

The kit's production config defaults to Solid Cache (config.cache_store = :solid_cache_store), which is shared via Postgres — so the throttles work correctly out of the box. If you switch to a different cache store, make sure it's a shared one: Redis, Memcached, or another Solid Cache database. Don't point Rails.cache at :memory_store in production.

The throttled response is 429 {"error":"too_many_requests"} with a Retry-After header. Clients should honour it; servers should not retry on 429 with backoff disabled.

CORS

Rack::Cors is mounted only if CORS_ORIGINS is set in production. The default (CORS_ORIGINS=*) is not applied in production — set it explicitly:

CORS_ORIGINS=https://app.example.com,https://admin.example.com

If your API is only ever called server-to-server (mobile/SPA → API, never browser → API), leave CORS_ORIGINS empty and the middleware never mounts. That's the most secure posture.

TLS

The kit's Dockerfile exposes port 3000, and config/deploy.yml's proxy.app_port: 3000 forwards from the Kamal proxy. Two settings to flip in production:

# config/environments/production.rb
config.assume_ssl = true   # we're behind a TLS-terminating proxy
config.force_ssl = true    # redirect HTTP → HTTPS and use Strict-Transport-Security

Both are commented out by default — uncomment them once your TLS terminator is live. With Kamal, that's the moment you flip proxy.ssl: true (after the DNS A/AAAA record points at the host so Let's Encrypt can issue a cert).

If you're behind a load balancer or CDN (Cloudflare, ALB, Cloud Run), confirm the proxy forwards X-Forwarded-Proto so assume_ssl recognises the original scheme.

Health checks

Two endpoints, two jobs:

Wire your load balancer's health check at /healthz (the kit's default; see proxy.healthcheck.path in config/deploy.yml). Neither endpoint hits the database — they're cheap.

Note: config.silence_healthcheck_path = "/up" in production silences /up from the logs but not /healthz. If your LB hammers /healthz and floods your logs, add it to the silence list too.

Observability

The kit ships logs to STDOUT with :request_id tags — that's the floor. Add the layers you need:

• Error tracking. Sentry, Honeybadger, Bugsnag — all install as a gem and a single initializer. Wire it before you have your first 500.
• APM / tracing. Datadog, New Relic, OpenTelemetry — same shape. Particularly useful here because most of the auth latency is JWKS verification and Postgres round-trips, both of which trace nicely.
• Log aggregation. Whatever ingests STDOUT works (Better Stack, Papertrail, Datadog Logs, etc.). Make sure you keep request_id end-to-end if you also instrument the client.

CI

bin/ci runs the full quality gate locally — wire the same checks into your CI before letting a branch merge:

bin/rubocop           # style
bin/brakeman -q       # static security analysis
bin/bundler-audit     # vulnerable-gem audit
bundle exec rspec     # RSpec suite
bin/rails test        # Minitest infrastructure suite

Or run them all together with bin/ci. None of them need a running Supabase project — the spec suite uses an in-memory JWKS keyed by SUPABASE_JWT_SECRET, and the Minitest suite covers middleware in isolation.

Production readiness checklist

Walk this before your first cut to production:

• All four SUPABASE_* and DATABASE_URL secrets set in the production environment.
• DATABASE_URL uses the pooler URL (Supabase Cloud) or matches your Postgres connection-pooling story.
• CORS_ORIGINS set explicitly — or confirmed empty because there's no browser client.
• config.force_ssl = true and config.assume_ssl = true uncommented in config/environments/production.rb.
• SWAGGER_UI_ENABLED decided — usually off in production for closed APIs.
• Rails.cache points at a shared store (Solid Cache, Redis, Memcached) so Rack::Attack throttles count correctly across containers.
• Health check path on the LB is /healthz.
• Migrations run before traffic flips (Kamal pre-deploy hook or platform equivalent).
• Error tracking and log aggregation wired up.
• bin/ci is green in CI on every PR.

When all of the above is true, the kit is ready for production traffic. Anything provider-specific (Fly/Render/Heroku/ECS/etc.) goes on top — the host concerns are local to that platform and not in scope for this guide.