A Rails application pre-configured with Spree Commerce. Use it as a starting point for your own store, or as the backend for a headless storefront.
The fastest way to get started is with create-spree-app:
npx create-spree-app my-storeThis scaffolds a full project with Docker, a Next.js storefront, and this backend — all configured and ready to run.
One click deploys the backend (web + worker), PostgreSQL, and Redis.
- Ruby (see
.ruby-version) - PostgreSQL
- Redis
bin/setup will use Mise to install all dependencies.
bin/setup
bin/devThe app starts at http://localhost:3000.
- Admin: http://localhost:3000/admin
- API: http://localhost:3000/api/v3/store/products
- Health check: http://localhost:3000/up
Default admin credentials are created during db:seed.
Build and run with Docker:
docker build -t my-spree .
docker run -p 3000:3000 \
-e DATABASE_URL=postgres://user:pass@host:5432/spree \
-e REDIS_URL=redis://localhost:6379/0 \
-e SECRET_KEY_BASE=$(bin/rails secret) \
my-spreeSee Docker deployment docs for a full docker-compose.yml example.
Copy .env.example to .env and configure:
| Variable | Required | Description |
|---|---|---|
DATABASE_URL |
Yes (production) | PostgreSQL connection URL |
REDIS_URL |
Yes (production) | Redis URL for jobs, caching, and Action Cable |
SECRET_KEY_BASE |
Yes (production) | Generate with bin/rails secret |
PORT |
No | Web server port (default: 3000) |
See Environment Variables docs for the full list (SMTP, S3, Sentry, SSL, etc.).
This is a standard Rails application. Customize it however you need:
- Add gems to
Gemfile - Override models with decorators in
app/models/ - Add controllers in
app/controllers/ - Configure Spree in
config/initializers/spree.rb - Add migrations with
bin/rails generate migration
See the Spree Customization Guide for details.
To develop against a local checkout of the Spree gems:
# Set SPREE_PATH to your local spree monorepo
echo 'SPREE_PATH=../spree' > .env
bundle install
bin/devThe Gemfile automatically uses local gems when SPREE_PATH is set.