Spree Starter

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.

Quick Start

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-store

If 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

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:seed

The 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, or psql

How development works

The dev compose (docker-compose.dev.yml) is set up so editing local files takes effect immediately, with no rebuild loop:

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.

Common commands

# 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 down

If this is verbose, install the @spree/cli which wraps these as spree exec, spree rails, spree generate, spree migrate, etc.

Environment variables

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:

For production deployments (S3, SMTP, Sentry, etc.) see the environment variables docs.

Customization

This is a standard Spree application. Customize it however you need — see the Spree Customization Guide.

Native Ruby (advanced)

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 Foreman

Then visit http://localhost:3000. Default admin credentials are printed by db:seed.

Deployment

For self-hosted Docker deployment, one-click Render deploys, and managed-host guides, see the deployment docs.

License

MIT