This guide uses Docker Compose to run Spree 5.3 with a custom Docker image.
Current Version: 5.3 (released January 27, 2026)
⚠️ Important: The spreecommerce/spree Docker Hub image is 7 years outdated (last updated 2019, Spree 3.5). You must build a custom Docker image for Spree 5.3.
For Docker installation, see Docker.
Build your own Spree Docker image for production use.
FROM ruby:3.2-slim
# Install system dependencies
RUN apt-get update && apt-get install -y \
build-essential \
libpq-dev \
libvips-dev \
nodejs \
npm \
git \
&& rm -rf /var/lib/apt/lists/*
# Install Yarn
RUN npm install -g yarn
WORKDIR /app
# Install bundler
RUN gem install bundler:2.4.0
EXPOSE 3000
version: '3.8'
services:
postgres:
image: postgres:15
container_name: spree-postgres
restart: unless-stopped
environment:
POSTGRES_DB: spree
POSTGRES_USER: spree
POSTGRES_PASSWORD: spree-password-change-me
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- spree-net
spree:
build: .
container_name: spree
restart: unless-stopped
depends_on:
- postgres
ports:
- "3000:3000"
environment:
DATABASE_URL: postgresql://spree:spree-password-change-me@postgres:5432/spree
RAILS_ENV: production
SECRET_KEY_BASE: change-me-to-random-secret-key
volumes:
- spree_app:/app
networks:
- spree-net
command: >
bash -c "
bundle install &&
rails db:setup &&
rails server -b 0.0.0.0
"
volumes:
postgres_data:
spree_app:
networks:
spree-net:
# Create a new Spree app
mkdir spree-app && cd spree-app
echo 'source "https://rubygems.org"' > Gemfile
echo 'gem "spree", "~> 5.3"' >> Gemfile
echo 'gem "spree_auth_devise"' >> Gemfile
echo 'gem "spree_gateway"' >> Gemfile
# Build and start
docker compose build
docker compose up -d
# Install Spree in the container
docker compose exec spree bash
rails spree:install --migrate=false --sample=false --seed=false --copy_files=false
Use the official Spree starter template:
version: '3.8'
services:
postgres:
image: postgres:15
environment:
POSTGRES_DB: spree
POSTGRES_USER: spree
POSTGRES_PASSWORD: spree-password-change-me
volumes:
- postgres_data:/var/lib/postgresql/data
spree:
image: ruby:3.2-slim
ports:
- "3000:3000"
depends_on:
- postgres
volumes:
- ./spree-app:/app
working_dir: /app
command: >
bash -c "
apt-get update && apt-get install -y build-essential libpq-dev nodejs &&
gem install bundler &&
bundle install &&
rails db:setup &&
rails server -b 0.0.0.0
"
volumes:
postgres_data:
# Create new Spree app locally
rails new spree-app -m https://raw.githubusercontent.com/spree/spree_starter/main/template.rb
cd spree-app
docker compose up -d
For development/testing only:
version: '3.8'
services:
postgres:
image: postgres:15
environment:
POSTGRES_DB: spree_development
POSTGRES_USER: spree
POSTGRES_PASSWORD: spree-password
spree:
image: ruby:3.2-slim
ports:
- "3000:3000"
volumes:
- ./app:/app
working_dir: /app
stdin_open: true
tty: true
command: bash
Then manually install Spree:
docker compose up -d
docker compose run spree bash
gem install bundler
rails new . --database=postgresql
# Add Spree gems to Gemfile
bundle install
rails spree:install
docker compose exec spree rails runner "Spree::AdminUser.create!(email: 'admin@example.com', password: 'password123', password_confirmation: 'password123')"
For production, use a reverse proxy (Nginx/Traefik) with Let’s Encrypt:
# Add to docker-compose.yml
services:
traefik:
image: traefik:v2.10
command:
- "--providers.docker=true"
- "--entrypoints.web.address=:80"
- "--entrypoints.websecure.address=:443"
- "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
- "--certificatesresolvers.letsencrypt.acme.email=your@email.com"
- "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
ports:
- "80:80"
- "443:443"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:ro"
- letsencrypt:/letsencrypt
# Backup PostgreSQL database
docker compose exec postgres pg_dump -U spree spree > backup.sql
# Backup app files
tar -czf spree-app-backup.tar.gz spree_app/
rails assets:precompile for production