# Saleor E-commerce Platform

> Saleor headless e-commerce with GraphQL.

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

## Overview

Saleor is a modern, headless e-commerce platform built with Python and Django that provides a GraphQL-first API for building custom shopping experiences. Originally created by Mirumee Software in 2018, Saleor separates the commerce backend from the frontend presentation layer, allowing developers to build native mobile apps, progressive web applications, or traditional websites while maintaining a single source of truth for product catalogs, inventory, and order management. This Docker stack combines Saleor's core API with PostgreSQL for robust relational data storage, Redis for high-performance caching and session management, and Celery workers for asynchronous task processing. PostgreSQL handles complex product relationships, customer data, and transactional integrity required for e-commerce operations, while Redis accelerates API responses through intelligent caching and manages real-time features like cart sessions. The Celery worker processes background tasks such as sending order confirmation emails, processing webhook notifications to external systems, and generating product export files without blocking the main API. This configuration is ideal for developers building scalable e-commerce solutions that require API-first architecture, whether creating multi-channel retail experiences, marketplace platforms, or custom B2B commerce applications that need to integrate with existing enterprise systems.

## Features

- GraphQL API with real-time playground for testing queries, mutations, and schema exploration at /graphql/
- Headless architecture enabling custom storefront development with React, Vue, mobile apps, or any frontend framework
- Multi-tenant product catalog with variant support, digital products, and complex pricing rules managed through Django admin
- PostgreSQL-powered inventory tracking with stock locations, reservations, and automated low-stock notifications
- Redis-cached session management for cart persistence, user preferences, and API response optimization
- Celery-based asynchronous processing for email campaigns, payment webhooks, order fulfillment, and data exports
- Built-in payment gateway integrations supporting Stripe, Braintree, and custom payment processors through plugins
- Advanced tax calculation engine with support for multiple jurisdictions and automated compliance reporting

## Use cases

- Building custom e-commerce storefronts for fashion retailers requiring complex product variants and size matrices
- Creating marketplace platforms where multiple vendors manage their own product catalogs and inventory
- Developing mobile-first shopping apps that need native iOS/Android interfaces connected to robust backend APIs
- Implementing B2B commerce solutions with custom pricing tiers, bulk ordering, and account-based purchasing workflows
- Launching headless commerce for content-driven brands integrating shopping with editorial content management
- Building subscription commerce platforms requiring recurring billing and automated inventory replenishment
- Creating omnichannel retail experiences connecting online stores with point-of-sale and warehouse management systems

## Prerequisites

- Docker Engine 20.10+ and Docker Compose with minimum 4GB RAM allocated for PostgreSQL and Redis operations
- Available ports 8000 (Saleor API) with additional ports needed if deploying separate Saleor Dashboard frontend
- Environment variables configured: DB_USER, DB_PASSWORD, SECRET_KEY (generate 50+ character Django secret key)
- Basic understanding of GraphQL queries and mutations for API interaction and testing
- Python/Django knowledge helpful for customizing Saleor models, adding payment integrations, or developing plugins
- PostgreSQL administration skills for database maintenance, backup strategies, and performance optimization

## docker-compose.yml

```yaml
services:
  saleor-api:
    image: ghcr.io/saleor/saleor:latest
    container_name: saleor-api
    restart: unless-stopped
    ports:
      - "${API_PORT:-8000}:8000"
    environment:
      - DATABASE_URL=postgres://${DB_USER}:${DB_PASSWORD}@saleor-db/saleor
      - REDIS_URL=redis://saleor-redis:6379/0
      - SECRET_KEY=${SECRET_KEY}
      - ALLOWED_HOSTS=localhost
    depends_on:
      - saleor-db
      - saleor-redis

  saleor-db:
    image: postgres:15-alpine
    container_name: saleor-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=saleor
    volumes:
      - saleor_db_data:/var/lib/postgresql/data

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

  saleor-worker:
    image: ghcr.io/saleor/saleor:latest
    container_name: saleor-worker
    restart: unless-stopped
    command: celery -A saleor worker --loglevel=info
    environment:
      - DATABASE_URL=postgres://${DB_USER}:${DB_PASSWORD}@saleor-db/saleor
      - REDIS_URL=redis://saleor-redis:6379/0
      - SECRET_KEY=${SECRET_KEY}
    depends_on:
      - saleor-db
      - saleor-redis

volumes:
  saleor_db_data:
  redis_data:
```

## .env

```bash
# Saleor
API_PORT=8000
DB_USER=saleor
DB_PASSWORD=saleor_password
SECRET_KEY=your_secret_key
```

## Usage notes

- Docs: https://docs.saleor.io/
- GraphQL Playground at http://localhost:8000/graphql/
- Deploy Saleor Dashboard separately: npx saleor-dashboard
- Celery worker handles async tasks: emails, webhooks, exports
- Migrate: docker exec saleor-api python manage.py migrate
- Create superuser: docker exec -it saleor-api python manage.py createsuperuser

## Troubleshooting

- saleor-api container exits with database connection errors: Ensure PostgreSQL container is fully initialized before API startup, increase depends_on wait time or add healthcheck
- GraphQL playground returns 500 errors on queries: Run database migrations with 'docker exec saleor-api python manage.py migrate' to create required tables
- Celery worker shows 'No module named saleor' errors: Verify both saleor-api and saleor-worker containers use identical environment variables and image versions
- Redis connection timeouts during high traffic: Increase Redis memory limits and configure Redis persistence (AOF) for session data recovery
- Product images not displaying in API responses: Configure MEDIA_URL and MEDIA_ROOT environment variables, ensure proper volume mounting for file uploads
- Payment webhooks failing with timeout errors: Check Celery worker logs and increase task timeout settings, verify external payment provider webhook URLs are reachable

