A Rails application pre-configured with Spree Commerce. Use it as a starting point for your own store, as the backend for a headless storefront, or as the basis for customization.
If you want a full project scaffold (this backend + a Next.js storefront + the spree CLI), use create-spree-app:
npx create-spree-app my-storeIf you want just this backend (e.g. to fork and customize it on its own), clone it directly and follow the development setup below.
Development is Docker-based: the only thing you need on your host is Docker (Docker Desktop, OrbStack, or any compatible runtime). No Ruby, no Postgres, no Redis on the host.
git clone https://github.com/spree/spree-starter.git my-store
cd my-store
cp .env.example .env
# Edit .env and set SECRET_KEY_BASE — generate one with:
# docker run --rm ruby:slim ruby -e 'require "securerandom"; puts SecureRandom.hex(64)'
docker compose -f docker-compose.dev.yml up -d
docker compose -f docker-compose.dev.yml exec web bin/rails db:prepare db:seedThe app is now running at http://localhost:3000:
- Admin: http://localhost:3000/admin — seeded admin credentials are printed by
db:seed - Store API: http://localhost:3000/api/v3/store/products
- Sidekiq: http://localhost:3000/sidekiq
- Health: http://localhost:3000/up
- PostgreSQL (host):
localhost:5433(user:postgres, db:spree_development) — connect with TablePlus, DataGrip, orpsql
The dev compose (docker-compose.dev.yml) is set up so editing local files takes effect immediately, with no rebuild loop:
| What changed | What you do | Rebuild image? |
|---|---|---|
Any .rb, .erb, .yml, .tailwind.css under app/, config/, lib/ |
Just save the file — Zeitwerk reloads on next request | No |
| Add or update a gem | docker compose -f docker-compose.dev.yml exec web bundle add <gem> (or bundle update <gem>) — gems persist in a named volume |
No |
db/migrate/* |
docker compose -f docker-compose.dev.yml exec web bin/rails db:migrate |
No |
.ruby-version or Dockerfile changed |
docker compose -f docker-compose.dev.yml down -v (wipes volumes so the new image's gem baseline gets re-seeded), then up --build |
Yes |
Source is bind-mounted into the container (./:/rails), gems live in a Docker-managed bundle_cache volume, ActiveStorage uploads live in storage_data. The dev image is built from the dev target in the Dockerfile — it has build-essential and dev/test gems pre-installed so native-extension gems work out of the box.
# Compose alias (set once)
alias dc='docker compose -f docker-compose.dev.yml'
# Run any Rails command
dc exec web bin/rails console
dc exec web bin/rails db:migrate
dc exec web bin/rails routes
# Run Spree generators
dc exec web bin/rails g spree:model Brand name:string slug:string
# Run rake tasks (data backfills, search reindex, etc.)
dc exec web bin/rake spree:search:reindex
# Tail logs
dc logs -f web
# Stop everything
dc downIf this is verbose, install the @spree/cli which wraps these as spree exec, spree rails, spree generate, spree migrate, etc.
docker-compose.dev.yml sets sensible dev defaults for DATABASE_URL, REDIS_URL, and MEILISEARCH_URL, while RAILS_ENV is baked into the Dockerfile dev stage. Most of .env.example is production-shaped and ignored in dev. The only variable you must set is:
| Variable | Required | Notes |
|---|---|---|
SECRET_KEY_BASE |
Yes | Generate any 64-byte hex string. Stable across restarts so cookies/sessions survive. |
SPREE_PORT |
No | Host port for the web service (default 3000) |
SPREE_DB_PORT |
No | Host port for Postgres (default 5433) |
SIDEKIQ_DB_POOL |
No | Worker thread pool size (default 27) |
For production deployments (S3, SMTP, Sentry, etc.) see the environment variables docs.
This is a standard Spree application. Customize it however you need — see the Spree Customization Guide.
If you prefer the fastest possible inner loop and are happy installing Ruby, Postgres, and Redis on your host, you can skip Docker entirely.
Prerequisites: Ruby (see .ruby-version), PostgreSQL, Redis. bin/setup installs Ruby via mise if available, otherwise points you at brew bundle (from the included Brewfile).
bin/setup # installs deps, prepares the database, runs db:seed
bin/dev # starts web + worker + Tailwind watcher via ForemanThen visit http://localhost:3000. Default admin credentials are printed by db:seed.
For self-hosted Docker deployment, one-click Render deploys, and managed-host guides, see the deployment docs.