# Rails starter

A Rails 8.1 starter on Ruby 3.4 and PostgreSQL for developers who want the Rails 8 authentication generator finished off with the sign-up it leaves out. It covers sign-up, sign-in, sign-out and password reset, a projects example scoped to each user, Propshaft and importmap with no Node.js, a database health check and a Dockerfile that migrates on start and runs Puma.

- Framework: Ruby on Rails (Ruby)
- Category: Starters / Full-stack
- Creates: a server app and a PostgreSQL database on the Shared tier (1 GB)
- Plan: Lite or above
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/starters/fullstack/rails-starter
- Updated: 2026-11-21

## Features

- The Rails 8.1 authentication generator: database-backed sessions in a signed, http-only cookie and has_secure_password with bcrypt
- A RegistrationsController for sign up, which the generator leaves out, with emails stored trimmed and lower case and one account per address
- Password reset links that expire after 15 minutes and stop working once the password changes, and every session signed out on reset
- A projects example with list, show, create, edit and a delete confirmation page, every query through Current.user.projects
- DATABASE_URL merged into config/database.yml, with sslmode=require for TLS and Node-only parameters dropped before libpq sees them
- Migrations run by the Docker entrypoint under Rails' advisory lock before Puma starts, and GET /up that answers 503 when the database is down
- Propshaft and importmap with Turbo and Stimulus pinned and no bundler; one CSS file with light and dark tokens that meets WCAG 2.2 AA
- 35 Minitest model, controller and integration tests against PostgreSQL, with RuboCop (Rails omakase) and Brakeman clean

## What you need

- A paid plan: deploying creates a PostgreSQL database, which the Free plan does not include
- To run it locally: Ruby 3.4, libpq, and Docker for a local PostgreSQL
- No API keys: DATABASE_URL and SECRET_KEY_BASE are set for you on deploy, and APP_URL at each deploy
- Optional: SMTP_ADDRESS, SMTP_USERNAME, SMTP_PASSWORD and MAIL_FROM to send reset emails; without them they are printed to the log
- Optional: FORCE_SSL=false to run the production image over plain http on your machine

## About

The usual first edits are app/views/home/index.html.erb, the colour tokens in app/assets/stylesheets/application.css and the projects example, which shows the pattern for your own resources: keep every query on Current.user so people only reach their own records. Production forces https and sends HSTS, which suits Light Cloud's edge, but a plain docker run on your machine with no proxy in front needs FORCE_SSL=false or every request is redirected. Sign-in, sign-up and reset allow 10 attempts per 3 minutes per IP address, counted in each instance's own cache, and behind a proxy that address may be the proxy's rather than the visitor's, so treat it as a rough limit. Without SECRET_KEY_BASE a key is derived from DATABASE_URL, which is stable but only as secret as the database password. Reset links use APP_URL, which Light Cloud sets at each deploy; on other hosts set it yourself, or links use the host of the request. Emails go to the log until SMTP_ADDRESS is set, SMTP delivery has not been tested against a real provider, and the projects list has no pagination yet.

## Variables

- `SECRET_KEY_BASE`: generated

## Questions

### How do I add sign up to the Rails 8 authentication generator?

The generator makes sign in, sign out and password reset but no sign up. This starter adds a RegistrationsController with new and create that saves a User with has_secure_password, starts a session with the generator's start_new_session_for and is rate-limited like sign in.

### How does a Rails app connect to PostgreSQL with DATABASE_URL over TLS?

Rails merges DATABASE_URL into the production entry of config/database.yml, and ?sslmode=require makes libpq use TLS without verifying the certificate. Parameters libpq does not know, such as uselibpqcompat and sslaccept in Light Cloud's URL, are dropped before connecting.

### Does this Rails 8 starter need Node.js?

No. Propshaft serves the CSS and importmap loads Turbo and Stimulus as ES modules straight from the app, so the Docker image has only Ruby, its gems and libpq.

### Why does the Rails Docker image redirect to https on my machine?

Production sets force_ssl, because it expects a proxy in front that ends TLS and sends X-Forwarded-Proto. Start the image with FORCE_SSL=false to serve plain http locally; leave it on behind Light Cloud or any other proxy.

### Can I host this Rails app without Light Cloud?

Yes. It has no Light Cloud code: build the Dockerfile on any Docker host behind a proxy that ends TLS, with DATABASE_URL and SECRET_KEY_BASE set, or run assets:precompile, db:migrate and bin/rails server with RAILS_ENV=production.
