docker.recipes

Saleor E-commerce Platform

advanced

Saleor headless e-commerce with GraphQL.

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.

Key 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

Common Use Cases

  • 1Building custom e-commerce storefronts for fashion retailers requiring complex product variants and size matrices
  • 2Creating marketplace platforms where multiple vendors manage their own product catalogs and inventory
  • 3Developing mobile-first shopping apps that need native iOS/Android interfaces connected to robust backend APIs
  • 4Implementing B2B commerce solutions with custom pricing tiers, bulk ordering, and account-based purchasing workflows
  • 5Launching headless commerce for content-driven brands integrating shopping with editorial content management
  • 6Building subscription commerce platforms requiring recurring billing and automated inventory replenishment
  • 7Creating 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

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  saleor-api: 
3    image: ghcr.io/saleor/saleor:latest
4    container_name: saleor-api
5    restart: unless-stopped
6    ports: 
7      - "${API_PORT:-8000}:8000"
8    environment: 
9      - DATABASE_URL=postgres://${DB_USER}:${DB_PASSWORD}@saleor-db/saleor
10      - REDIS_URL=redis://saleor-redis:6379/0
11      - SECRET_KEY=${SECRET_KEY}
12      - ALLOWED_HOSTS=localhost
13    depends_on: 
14      - saleor-db
15      - saleor-redis
16
17  saleor-db: 
18    image: postgres:15-alpine
19    container_name: saleor-db
20    restart: unless-stopped
21    environment: 
22      - POSTGRES_USER=${DB_USER}
23      - POSTGRES_PASSWORD=${DB_PASSWORD}
24      - POSTGRES_DB=saleor
25    volumes: 
26      - saleor_db_data:/var/lib/postgresql/data
27
28  saleor-redis: 
29    image: redis:7-alpine
30    container_name: saleor-redis
31    restart: unless-stopped
32    volumes: 
33      - redis_data:/data
34
35  saleor-worker: 
36    image: ghcr.io/saleor/saleor:latest
37    container_name: saleor-worker
38    restart: unless-stopped
39    command: celery -A saleor worker --loglevel=info
40    environment: 
41      - DATABASE_URL=postgres://${DB_USER}:${DB_PASSWORD}@saleor-db/saleor
42      - REDIS_URL=redis://saleor-redis:6379/0
43      - SECRET_KEY=${SECRET_KEY}
44    depends_on: 
45      - saleor-db
46      - saleor-redis
47
48volumes: 
49  saleor_db_data: 
50  redis_data:

.env Template

.env
1# Saleor
2API_PORT=8000
3DB_USER=saleor
4DB_PASSWORD=saleor_password
5SECRET_KEY=your_secret_key

Usage Notes

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

Individual Services(4 services)

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

saleor-api
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
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
saleor-redis:
  image: redis:7-alpine
  container_name: saleor-redis
  restart: unless-stopped
  volumes:
    - redis_data:/data
saleor-worker
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

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  saleor-api:
5    image: ghcr.io/saleor/saleor:latest
6    container_name: saleor-api
7    restart: unless-stopped
8    ports:
9      - "${API_PORT:-8000}:8000"
10    environment:
11      - DATABASE_URL=postgres://${DB_USER}:${DB_PASSWORD}@saleor-db/saleor
12      - REDIS_URL=redis://saleor-redis:6379/0
13      - SECRET_KEY=${SECRET_KEY}
14      - ALLOWED_HOSTS=localhost
15    depends_on:
16      - saleor-db
17      - saleor-redis
18
19  saleor-db:
20    image: postgres:15-alpine
21    container_name: saleor-db
22    restart: unless-stopped
23    environment:
24      - POSTGRES_USER=${DB_USER}
25      - POSTGRES_PASSWORD=${DB_PASSWORD}
26      - POSTGRES_DB=saleor
27    volumes:
28      - saleor_db_data:/var/lib/postgresql/data
29
30  saleor-redis:
31    image: redis:7-alpine
32    container_name: saleor-redis
33    restart: unless-stopped
34    volumes:
35      - redis_data:/data
36
37  saleor-worker:
38    image: ghcr.io/saleor/saleor:latest
39    container_name: saleor-worker
40    restart: unless-stopped
41    command: celery -A saleor worker --loglevel=info
42    environment:
43      - DATABASE_URL=postgres://${DB_USER}:${DB_PASSWORD}@saleor-db/saleor
44      - REDIS_URL=redis://saleor-redis:6379/0
45      - SECRET_KEY=${SECRET_KEY}
46    depends_on:
47      - saleor-db
48      - saleor-redis
49
50volumes:
51  saleor_db_data:
52  redis_data:
53EOF
54
55# 2. Create the .env file
56cat > .env << 'EOF'
57# Saleor
58API_PORT=8000
59DB_USER=saleor
60DB_PASSWORD=saleor_password
61SECRET_KEY=your_secret_key
62EOF
63
64# 3. Start the services
65docker compose up -d
66
67# 4. View logs
68docker 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/saleor-ecommerce-stack/run | bash

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

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

saleorpostgresqlrediscelery

Tags

#saleor#ecommerce#headless#graphql

Category

E-Commerce & Business

Related Recipes

Ad Space