docker.recipes

Spree Commerce

intermediate

Modular Ruby on Rails e-commerce platform.

Overview

Spree Commerce is an open-source, modular e-commerce platform built on Ruby on Rails that has been empowering online retailers since 2007. Known for its API-first architecture and extensible design, Spree provides a complete e-commerce solution with support for multi-store operations, complex product catalogs, and sophisticated order management. The platform's modular approach allows developers to customize every aspect of the shopping experience while maintaining a stable core foundation. This Docker stack combines Spree with PostgreSQL and Redis to create a production-ready e-commerce environment. PostgreSQL serves as the primary database, handling complex product relationships, customer data, and transactional integrity that e-commerce applications demand. Redis complements the stack by providing high-speed caching for product catalogs, session management for customer logins, and background job processing for order fulfillment workflows. The combination delivers the performance and reliability needed for modern online retail operations. This configuration is ideal for startups launching their first online store, established retailers migrating from legacy platforms, and developers building custom e-commerce solutions. The stack's scalability makes it suitable for everything from boutique shops to enterprise marketplaces, while the containerized deployment ensures consistent performance across development and production environments.

Key Features

  • Multi-store and multi-vendor marketplace capabilities with shared customer databases
  • API-first architecture with both REST and GraphQL endpoints for headless commerce
  • Advanced inventory management with stock tracking, variants, and multi-location support
  • Flexible tax calculation system supporting multiple jurisdictions and complex rules
  • Built-in payment gateway integrations with support for multiple processors
  • Product catalog with unlimited variants, options, and digital asset management
  • Customer segmentation and promotional engine with coupon and discount management
  • Order state machine with customizable workflow and fulfillment tracking

Common Use Cases

  • 1Fashion retailers needing complex product variants with size, color, and style combinations
  • 2B2B marketplaces requiring custom pricing, bulk orders, and vendor management
  • 3Subscription commerce platforms with recurring billing and inventory automation
  • 4Multi-brand retailers managing separate storefronts with shared backend systems
  • 5International e-commerce sites needing multi-currency and localization support
  • 6Digital product stores selling software, courses, or downloadable content
  • 7Dropshipping operations requiring automated supplier integration and order routing

Prerequisites

  • Docker Engine 20.10+ and Docker Compose 2.0+ installed on your system
  • Minimum 2GB RAM available (1GB+ for PostgreSQL, 512MB+ for Redis, 512MB+ for Spree)
  • Port 3000 available for Spree storefront and admin interface access
  • Basic Ruby on Rails knowledge for customization and troubleshooting
  • Understanding of e-commerce concepts like SKUs, variants, and payment processing
  • SSL certificate and domain name for production deployments

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  spree: 
3    image: spreecommerce/spree:latest
4    container_name: spree
5    restart: unless-stopped
6    environment: 
7      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
8      REDIS_URL: redis://redis:6379
9      SECRET_KEY_BASE: ${SECRET_KEY}
10    volumes: 
11      - spree_data:/app/public
12    ports: 
13      - "3000:3000"
14    depends_on: 
15      - postgres
16      - redis
17    networks: 
18      - spree
19
20  postgres: 
21    image: postgres:16-alpine
22    container_name: spree-postgres
23    environment: 
24      POSTGRES_DB: ${DB_NAME}
25      POSTGRES_USER: ${DB_USER}
26      POSTGRES_PASSWORD: ${DB_PASSWORD}
27    volumes: 
28      - postgres_data:/var/lib/postgresql/data
29    networks: 
30      - spree
31
32  redis: 
33    image: redis:alpine
34    container_name: spree-redis
35    networks: 
36      - spree
37
38volumes: 
39  spree_data: 
40  postgres_data: 
41
42networks: 
43  spree: 
44    driver: bridge

.env Template

.env
1DB_NAME=spree
2DB_USER=spree
3DB_PASSWORD=changeme
4SECRET_KEY=your-secret-key-here

Usage Notes

  1. 1Docs: https://docs.spreecommerce.org/
  2. 2Access storefront at http://localhost:3000, admin at /admin
  3. 3API-first architecture with REST and GraphQL endpoints
  4. 4Built on Ruby on Rails - highly customizable via extensions
  5. 5Multi-store, multi-vendor, multi-currency support
  6. 6Default admin: spree@example.com / spree123 (change immediately)

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

spree
spree:
  image: spreecommerce/spree:latest
  container_name: spree
  restart: unless-stopped
  environment:
    DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    REDIS_URL: redis://redis:6379
    SECRET_KEY_BASE: ${SECRET_KEY}
  volumes:
    - spree_data:/app/public
  ports:
    - "3000:3000"
  depends_on:
    - postgres
    - redis
  networks:
    - spree
postgres
postgres:
  image: postgres:16-alpine
  container_name: spree-postgres
  environment:
    POSTGRES_DB: ${DB_NAME}
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - spree
redis
redis:
  image: redis:alpine
  container_name: spree-redis
  networks:
    - spree

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  spree:
5    image: spreecommerce/spree:latest
6    container_name: spree
7    restart: unless-stopped
8    environment:
9      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
10      REDIS_URL: redis://redis:6379
11      SECRET_KEY_BASE: ${SECRET_KEY}
12    volumes:
13      - spree_data:/app/public
14    ports:
15      - "3000:3000"
16    depends_on:
17      - postgres
18      - redis
19    networks:
20      - spree
21
22  postgres:
23    image: postgres:16-alpine
24    container_name: spree-postgres
25    environment:
26      POSTGRES_DB: ${DB_NAME}
27      POSTGRES_USER: ${DB_USER}
28      POSTGRES_PASSWORD: ${DB_PASSWORD}
29    volumes:
30      - postgres_data:/var/lib/postgresql/data
31    networks:
32      - spree
33
34  redis:
35    image: redis:alpine
36    container_name: spree-redis
37    networks:
38      - spree
39
40volumes:
41  spree_data:
42  postgres_data:
43
44networks:
45  spree:
46    driver: bridge
47EOF
48
49# 2. Create the .env file
50cat > .env << 'EOF'
51DB_NAME=spree
52DB_USER=spree
53DB_PASSWORD=changeme
54SECRET_KEY=your-secret-key-here
55EOF
56
57# 3. Start the services
58docker compose up -d
59
60# 4. View logs
61docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/spree/run | bash

Troubleshooting

  • Spree container exits with database connection errors: Ensure PostgreSQL container is fully started before Spree boots, add healthcheck or increase depends_on delay
  • Asset compilation fails with 'No space left on device': Increase Docker Desktop disk space allocation or clean up unused images and volumes
  • Redis connection timeouts during high traffic: Increase Redis memory limit and configure Redis maxmemory-policy to allkeys-lru for better cache management
  • PostgreSQL performance degrades with large catalogs: Enable PostgreSQL query logging and add indexes on frequently searched product attributes and categories
  • Spree admin interface returns 500 errors: Check SECRET_KEY_BASE environment variable is set and at least 30 characters long
  • Image uploads fail or return broken links: Verify spree_data volume is properly mounted and container has write permissions to /app/public directory

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

spreepostgresredis

Tags

#spree#ruby#rails#ecommerce

Category

E-Commerce & Business

Related Recipes

Ad Space