# Spree Commerce

> Modular Ruby on Rails e-commerce platform.

- Category: E-Commerce & Business
- Difficulty: intermediate
- Components: spree, postgres, redis
- Tags: spree, ruby, rails, ecommerce
- Source: https://docker.recipes/ecommerce/spree

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

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

## Use cases

- Fashion retailers needing complex product variants with size, color, and style combinations
- B2B marketplaces requiring custom pricing, bulk orders, and vendor management
- Subscription commerce platforms with recurring billing and inventory automation
- Multi-brand retailers managing separate storefronts with shared backend systems
- International e-commerce sites needing multi-currency and localization support
- Digital product stores selling software, courses, or downloadable content
- Dropshipping 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

## docker-compose.yml

```yaml
services:
  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:
    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:
    image: redis:alpine
    container_name: spree-redis
    networks:
      - spree

volumes:
  spree_data:
  postgres_data:

networks:
  spree:
    driver: bridge
```

## .env

```bash
DB_NAME=spree
DB_USER=spree
DB_PASSWORD=changeme
SECRET_KEY=your-secret-key-here
```

## Usage notes

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

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

