# Saleor Enterprise Commerce

> High-performance GraphQL e-commerce platform with dashboard.

- Category: E-Commerce & Business
- Difficulty: advanced
- Components: saleor-api, saleor-dashboard, postgresql, redis, celery
- Tags: saleor, ecommerce, graphql, headless, enterprise
- Source: https://docker.recipes/ecommerce/saleor-commerce

## Overview

Saleor is an open-source, headless commerce platform built on Django and GraphQL that emerged as a modern alternative to traditional monolithic e-commerce solutions. Originally developed by Mirumee Software, Saleor provides a complete backend for e-commerce operations while maintaining API-first architecture that separates content management from presentation layers. The platform emphasizes developer experience with its comprehensive GraphQL API, extensive webhook system, and plugin architecture that enables custom business logic without core modifications. This enterprise stack combines Saleor's API server with its React-based dashboard, supported by PostgreSQL for complex relational data management and Redis for high-performance caching and task queuing. The architecture leverages Celery workers for background processing of orders, inventory updates, and email notifications, while the dashboard provides administrators with real-time insights into sales performance, inventory levels, and customer analytics. Organizations choose this stack when they need enterprise-grade e-commerce capabilities with the flexibility to build custom storefronts, integrate with existing systems, and scale across multiple sales channels while maintaining full control over the customer experience and business logic.

## Features

- GraphQL API with real-time subscriptions for inventory updates and order status changes
- Multi-channel sales support with separate pricing, inventory, and tax configurations per channel
- Advanced product catalog with variant management, digital products, and gift card functionality
- Comprehensive order management with split fulfillment, refunds, and automated tax calculations
- Plugin architecture supporting payment gateways, shipping providers, and custom business logic
- Celery-powered background processing for email campaigns, inventory synchronization, and analytics
- Redis-backed session management and caching for sub-second API response times
- PostgreSQL full-text search with product filtering and faceted navigation support

## Use cases

- Multi-brand retailers requiring separate storefronts with shared inventory management
- B2B marketplaces with complex pricing tiers and customer-specific catalogs
- Digital product platforms selling software licenses, courses, and subscription services
- International e-commerce with multi-currency support and localized tax calculations
- Headless commerce implementations using React, Vue, or mobile applications as frontends
- Enterprise migrations from Magento or Shopify requiring API-first architecture
- Omnichannel retail operations integrating online stores with POS and marketplace systems

## Prerequisites

- Minimum 4GB RAM for all services (PostgreSQL requires 1GB+, Saleor API needs 2GB+ for production workloads)
- Docker Engine 20.10+ and Docker Compose 2.0+ with BuildKit support enabled
- Ports 8000, 9000, and 5432 available on the host system
- Basic understanding of GraphQL queries and Django admin interface
- SSL certificates and reverse proxy configuration for production deployment
- SMTP server credentials for transactional emails and order notifications

## docker-compose.yml

```yaml
services:
  saleor-api:
    image: ghcr.io/saleor/saleor:latest
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://redis:6379/0
      SECRET_KEY: ${SECRET_KEY}
      ALLOWED_HOSTS: localhost,api
      DEBUG: "False"
      DEFAULT_FROM_EMAIL: noreply@example.com
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - saleor-net
    restart: unless-stopped

  saleor-worker:
    image: ghcr.io/saleor/saleor:latest
    command: celery -A saleor --app=saleor.celeryconf:app worker --loglevel=info -B
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://redis:6379/0
      SECRET_KEY: ${SECRET_KEY}
    depends_on:
      - saleor-api
    networks:
      - saleor-net
    restart: unless-stopped

  saleor-dashboard:
    image: ghcr.io/saleor/saleor-dashboard:latest
    ports:
      - "9000:80"
    environment:
      API_URI: http://localhost:8000/graphql/
    networks:
      - saleor-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - saleor-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - saleor-net
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

networks:
  saleor-net:
    driver: bridge
```

## .env

```bash
# Saleor Configuration
SECRET_KEY=$(openssl rand -hex 50)

# PostgreSQL
POSTGRES_USER=saleor
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=saleor
```

## Usage notes

- Saleor API at http://localhost:8000/graphql/
- Dashboard at http://localhost:9000
- Create superuser: docker compose exec saleor-api python manage.py createsuperuser
- Populate demo data: docker compose exec saleor-api python manage.py populatedb

## Troubleshooting

- saleor-api exits with 'relation does not exist' errors: Run `docker compose exec saleor-api python manage.py migrate` to apply database migrations
- Dashboard shows 'Network Error' when connecting to API: Verify API_URI environment variable matches the accessible URL from browser, not internal Docker network
- Celery workers fail with Redis connection errors: Ensure Redis container is healthy before starting workers, add health checks or init containers
- GraphQL queries timeout or return incomplete data: Increase PostgreSQL shared_buffers and effective_cache_size in custom postgresql.conf volume mount
- Image upload failures or missing media files: Add persistent volume mount for `/app/media` directory in saleor-api service
- Webhook delivery failures to external services: Configure ALLOWED_HOSTS to include webhook recipient domains and verify firewall rules

