IN SHORT

  • Install a current Ruby with a version manager, then generate the app with PostgreSQL and Tailwind from day one.
  • Commit the generated app before writing any code, so every later change is a readable diff.
  • Add the authentication generator, a first model, a request spec and a deploy in the first week, not the last.
  • Rails 8 ships its own queue, cache and deploy tooling. Do not add Redis, Sidekiq or a separate frontend until the app asks for them.

I wrote an earlier version of this guide when Rails 6 was in beta and clients were asking whether to start on it. That question is settled: start on the current stable release. Rails 8 is the version I use for new projects, and the setup below is what I do on the first day of every one of them.

1. Prerequisites

You need Ruby, a database and Git. Install Ruby through a version manager such as mise or rbenv rather than the system package, so each project can pin its own version. PostgreSQL is the database I recommend for anything that will run in production. Node is no longer required for a standard Rails 8 app because the asset pipeline and Tailwind run without it.

# Ruby via mise (or rbenv)
mise use --global ruby@3.4
gem install rails

# PostgreSQL on macOS
brew install postgresql@17 && brew services start postgresql@17

2. Generate the application

The generator flags you pick here save hours later. Choose the production database now, so development and production behave the same, and pick a CSS approach so you are not restyling the app in month two.

rails new invoicer --database=postgresql --css=tailwind
cd invoicer
bin/rails db:create
bin/dev

Open http://localhost:3000 and you have a running application. Make the first commit now, before any changes. From this point on, every commit is a small, reviewable diff on top of the generated code.

3. Learn the layout

  • app/models holds the classes that map to database tables and carry business rules.
  • app/controllers receives requests and decides what to render.
  • app/views contains the HTML templates, organised by controller.
  • config/routes.rb maps URLs to controller actions.
  • db/migrate holds versioned changes to the database schema.
  • test or spec is where the safety net lives.

4. Add authentication and a first model

Rails 8 includes an authentication generator that creates sessions, password resets and the supporting views. Run it first, because almost everything else will hang off the current user.

bin/rails generate authentication
bin/rails generate scaffold Invoice number:string amount:decimal due_on:date user:references
bin/rails db:migrate

The scaffold gives you working create, read, update and delete screens in under a minute. You will replace most of the views, but the controller and model are a solid starting point. Add the constraints the database should enforce straight away: a unique index on the invoice number, a foreign key to the user and not-null columns for anything required.

5. Write the first test

One request test that signs in, creates an invoice and checks the response proves the whole stack works together. Keep it running on every push. A test suite that exists from the first week gets maintained; one added in month six gets skipped.

# test/controllers/invoices_controller_test.rb
test "creates an invoice for the signed-in user" do
  sign_in_as users(:alex)
  post invoices_url, params: { invoice: { number: "INV-1", amount: 250, due_on: Date.tomorrow } }
  assert_redirected_to invoice_url(Invoice.last)
end

6. Deploy in the first week

Rails 8 ships with Kamal, which deploys the app as a Docker container to any Linux server with one command. Deploying early surfaces environment problems while they are still small: missing environment variables, asset compilation, database credentials. Solid Queue, Solid Cache and Solid Cable run on the same database, so the first production server needs Postgres and nothing else.

kamal setup    # first time: installs Docker, boots the app
kamal deploy   # every time after that

7. What not to add yet

New projects accumulate tooling faster than they accumulate users. Hold off on Redis, Sidekiq, a separate React frontend, GraphQL, microservices and Kubernetes until a real constraint shows up. The stack that ships with Rails covers a product well past its first thousand customers, and every addition is a thing someone has to maintain.

First-week checklist

  1. Ruby pinned in .ruby-version, app generated with PostgreSQL and a CSS choice.
  2. Initial commit of the generated app, then small commits.
  3. Authentication generator run and one real model with database constraints.
  4. One request test passing in CI.
  5. Error tracking and a first deploy with Kamal.
  6. A README that tells the next developer how to run it.

Want a second pair of eyes on a new project, or help setting one up properly from the start? Send me a message and tell me what you are building.