Deployment

This page covers 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. The kit's .env.example is for local development — Rails doesn't auto-load .env even in development (export with direnv, dotenv, or your process manager), and in production a .env file should never ship.

The kit doesn't fail-fast on missing Supabase env vars in production — supabase-rails will surface its own actionable error at first request if any are missing. If you want a louder boot-time check, add one to config/initializers/supabase.rb.

SSR build flag

Inertia SSR is wired but disabled by default. To ship SSR:

1. Set config.ssr_enabled = true in config/initializers/inertia_rails.rb.
2. Build the image with --build-arg SSR_ENABLED=true so the SSR bundle ships in public/vite-ssr/ssr.js and Node 22 stays in the final image.

With Kamal

Add to config/deploy.yml:

builder:
  args:
    SSR_ENABLED: true

By hand

docker build --build-arg SSR_ENABLED=true -t react_starter_kit .

When SSR_ENABLED=false (the default), the Dockerfile's branch-ssr-false stage skips the vite build --ssr step and the final image drops Node entirely — smaller image, faster cold boots. Flip the flag the day SEO or first-paint pressure makes SSR worthwhile.

If the SSR process crashes or times out at runtime, Inertia falls back to client-side rendering (config.on_ssr_error). The fallback is silent — wire an APM or log alert so you find out before the SEO impact does.

Database

The kit defaults to SQLite for all four roles — primary (app data), cache (Solid Cache), queue (Solid Queue), cable (Solid Cable). For a single-server Kamal deploy with persistent disk, that's a perfectly viable production posture; for multi-server deploys, you'll want Postgres for primary (and probably for the Solid roles too).

Choices to make:

• SQLite (default). Mount storage/ as a persistent Docker volume so the SQLite files survive container restarts. config/deploy.yml declares this volume. Back it up the way you'd back up any single-server datastore (LiteFS, Litestream, or filesystem snapshots).
• Postgres. Swap adapter: sqlite3 for adapter: postgresql in config/database.yml, add gem "pg" to the Gemfile, and set DATABASE_URL. For Solid Cache/Queue/Cable on Postgres, point each role at the same database with migrations_paths: separating them.
• Domain data vs Supabase Postgres. Remember the kit's split: auth.users lives in Supabase Postgres. Anything you add through the per-request RLS-scoped client (see Customization → Recipe 1) also lives in Supabase. Your ActiveRecord models live in primary (SQLite or Postgres of your choice).
• Migrations. Run Rails migrations once per deploy, before the new image takes traffic. With Kamal, add a pre-deploy hook in config/deploy.yml. Supabase migrations (supabase/migrations/) are a separate flow — supabase db push against a linked project, or apply through the dashboard.

Sessions

The encrypted sb-session cookie is signed and encrypted with Rails' message verifier. The key comes from Rails.application.secret_key_base, which the gem reads at boot.

Two things to confirm before going live:

• secret_key_base is stable across deploys. It's read from config/credentials.yml.enc (decrypted with RAILS_MASTER_KEY) or directly from the SECRET_KEY_BASE env var. If it rotates between deploys, every signed-in user is signed out at the rotation — their old sb-session cookies become undecryptable.
• Cookie domain. The kit relies on the default — the cookie scopes to the request host. If you serve the app from multiple subdomains, set Rails.application.config.supabase.session = { ..., domain: ".example.com" } in config/initializers/supabase.rb and the cookie will work across them.

TLS

The kit's Dockerfile exposes port 80 (via Thruster) and config/deploy.yml's proxy.app_port: 80 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 emit HSTS

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 in config/deploy.yml (after the DNS A/AAAA record points at the host so Let's Encrypt can issue a cert).

The sb-session cookie ships with Secure: nil (auto-detect) in the gem's defaults — once assume_ssl = true, the cookie is marked Secure automatically and never leaks over HTTP.

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.

Cache

The cache role in config/database.yml points Rails.cache at Solid Cache by default (config.cache_store = :solid_cache_store in production). Solid Cache is shared across Puma workers and containers (it's a database) — anything you put in Rails.cache (HTTP fragment caches, etag caches, your own application caches) works correctly out of the box on a multi-worker deploy.

If you swap Rails.cache for :memory_store, every Puma worker has its own in-process cache and you lose the cross-worker invariant. Don't.

Vite + asset pipeline

bin/rails assets:precompile runs as part of the Docker build. It calls npx vite build (and npx vite build --ssr if SSR_ENABLED=true), writes the digested client bundle to public/vite/, and emits public/vite/manifest.json. The <%= vite_tags … %> helper reads that manifest at runtime to emit the correct <script> and <link> tags.

Two things to keep in mind:

• The manifest is the source of truth. If a deploy ships without public/vite/manifest.json (e.g. assets:precompile was skipped), every page will 500 with RailsVite::ManifestMissing. The Dockerfile runs precompile before the final image stage — don't remove it.
• The client bundle is digested. Filenames are content-hashed, so the browser cache never serves a stale asset across deploys. Set Cache-Control: public, max-age=31536000, immutable for /vite/* at your CDN / proxy layer — Thruster does this by default.

After Vite finishes, the build deletes node_modules/ from the image (RUN ... && rm -rf node_modules). The final image only ships the JS runtime (Node 22) when SSR_ENABLED=true, and ships no Node at all otherwise — small and quick to boot.

Health checks

The kit ships GET /up — Rails' default health check. It returns 200 if the app booted and 500 otherwise. Wire your load balancer's health check at /up (the Kamal proxy uses /up out of the box).

config.silence_healthcheck_path = "/up" in production silences the /up line from access logs. If you also want /up to verify the database, replace it with a controller that runs ActiveRecord::Base.connection.execute("SELECT 1") — but be aware that turns the LB health check into a DB heartbeat, which can take a healthy host down on a transient DB blip.

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 latency on Inertia pages is the round-trip from React → Rails → Supabase, which traces cleanly when each hop is instrumented.
• Frontend error tracking. Sentry (and others) ship browser SDKs that capture React render errors and unhandled promise rejections. Mount it from entrypoints/inertia.tsx before createInertiaApp.
• Log aggregation. Whatever ingests STDOUT works (Better Stack, Papertrail, Datadog Logs, etc.). Keep request_id end-to-end if you also instrument the browser.

CI

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

bin/setup --skip-server                          # bundle + npm install + db:prepare
bin/rubocop                                       # Ruby style
npm run lint                                      # eslint over app/javascript
npm run format                                    # prettier check
npm run check                                     # tsc — both app and node tsconfigs
bin/bundler-audit                                 # vulnerable-gem audit
npm audit                                         # vulnerable-npm audit
bin/brakeman --quiet --no-pager --exit-on-warn    # Rails static security analysis
bin/rspec                                         # request specs
env RAILS_ENV=test bin/rails db:seed:replant      # seeds re-runnable

bin/ci chains all of the above. On hosted CI, no extra Docker is required — there's no bin/e2e equivalent in this kit, so the suite runs fully in-container.

Production readiness checklist

Walk this before your first cut to production:

• SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, SUPABASE_SECRET_KEY, and SUPABASE_JWKS_URL set in the production environment.
• RAILS_MASTER_KEY set (and secret_key_base stable across deploys — no rotation between releases).
• Database choice made — SQLite with a persistent volume, or Postgres with DATABASE_URL and gem "pg".
• supabase/migrations/ (if you have any) applied against the production Supabase project (supabase db push after supabase link, or paste through the dashboard SQL editor).
• config.force_ssl = true and config.assume_ssl = true uncommented in config/environments/production.rb.
• proxy.ssl: true and proxy.host set in config/deploy.yml (if using Kamal).
• Rails.cache points at a shared store — :solid_cache_store (the kit default), Redis, or another shared cache.
• SSR decision made — ssr_enabled flipped and --build-arg SSR_ENABLED=true set together, or both left off.
• Vite bundle precompiled in the image (bin/rails assets:precompile runs in the build stage — don't skip).
• Health check path on the LB is /up.
• Rails-side migrations run before traffic flips (Kamal pre-deploy hook or platform equivalent).
• Error tracking (server + browser) 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.