[App Name] · Rails 8 + Hotwire

A Rails 8 app. Hotwire for interactivity (Turbo + Stimulus). Tailwind v4 for styling. SQLite for prod (yes, really, Rails 8 made it viable).

Source of truth

The deployed Kamal release is canonical. Code on GitHub. Database is SQLite with Litestream replicating to S3 for backup.

Tech stack

Ruby 3.4 + Rails 8.0 + Hotwire (Turbo + Stimulus) + Tailwind v4. SQLite for DB, queue (Solid Queue), and cache (Solid Cache). Active Storage for uploads (S3 or local). Devise for auth (still the boring choice). Kamal 2 for deployment.

Deploy

• Local: bin/dev (runs Procfile.dev: server, Tailwind watch, jobs)
• Production: kamal deploy (build image, push, restart). Provision via kamal setup.
• Database: SQLite file on persistent volume. Litestream sidecar for S3 replication.

File map

• app/controllers/ Rails controllers
• app/models/ ActiveRecord models
• app/views/ ERB templates (Turbo Frames + Turbo Streams)
• app/javascript/controllers/ Stimulus controllers
• app/javascript/application.js Stimulus + Turbo entrypoint
• app/jobs/ background jobs (Solid Queue)
• db/schema.rb (auto-generated, don't hand-edit)
• config/deploy.yml Kamal config
• Dockerfile Rails-optimized

.env keys

• RAILS_MASTER_KEY (also in config/master.key, NOT committed)
• S3_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (Active Storage + Litestream)
• RESEND_API_KEY (or Postmark, SMTP, whatever)
• RAILS_ENV production

Hard rules

• ActiveRecord callbacks are forbidden for anything beyond trivial validation. Use service objects.
• Background jobs via Solid Queue. Never block a request on a slow third-party call.
• Hotwire first. Reach for a JS framework only when Turbo + Stimulus can't express it.
• Migrations go forward AND backward (change method or explicit up/down). Tested with rails db:rollback.
• Authorization (who can do what) via pundit or action_policy. Never inline in controllers.
• bin/setup works on a fresh clone. If a new dev can't go from git clone to bin/dev in 5 minutes, it's broken.

Recent significant changes

• 2026-05-10: Scaffolded. Locked: Rails 8 omakase (Solid suite, no Redis), Hotwire over React (less code), Kamal over Heroku (cost), SQLite over Postgres for v0 (Rails 8 made this real).

Next session: start here

1. rails new myapp --database=sqlite3 --css=tailwind --javascript=esbuild if from scratch.
2. Set up Devise: rails generate devise:install && rails generate devise User && rails db:migrate.
3. Generate first resource scaffold. Click through, including the Turbo Stream paths.
4. Configure Kamal: edit config/deploy.yml with your server IP.
5. kamal setup to provision, kamal deploy to ship.