Saleor Deployment
Before writing code
Fetch live docs:
- Web-search
site:docs.saleor.io deployment production setup for production deployment guide
- Fetch
https://github.com/saleor/saleor-platform for Docker Compose reference configuration
- Web-search
site:docs.saleor.io environment variables configuration for required environment variables
- Web-search
saleor Celery worker configuration production for Celery setup details
- Web-search
site:docs.saleor.io cloud for Saleor Cloud managed hosting options
Production Docker Setup
Saleor provides an official Dockerfile with a multi-stage build:
| Stage |
Purpose |
Base Image |
| build |
Install dependencies, compile assets |
python:3.12-slim |
| production |
Run the application |
python:3.12-slim |
Docker Compose Services
| Service |
Image |
Purpose |
Port |
| api |
saleor (custom build) |
GraphQL API server (Gunicorn) |
8000 |
| worker |
saleor (same image) |
Celery worker process |
N/A |
| db |
postgres:15-alpine |
PostgreSQL database |
5432 |
| redis |
redis:7-alpine |
Cache and Celery broker |
6379 |
| dashboard |
saleor-dashboard |
React admin UI |
9002 |
| storefront |
Custom Next.js |
Customer-facing storefront |
3000 |
Saleor Cloud (Managed Hosting)
| Feature |
Description |
| Managed API |
Fully managed Saleor backend, no server maintenance |
| Auto-scaling |
Scales based on traffic automatically |
| Managed database |
PostgreSQL with backups and replication |
| CDN |
Built-in CDN for media and static assets |
| Environments |
Staging and production environments per project |
| CLI integration |
Deploy and manage via saleor CLI |
Access via https://cloud.saleor.io/ — create projects, manage environments, and deploy Apps.
Environment Variables
Required Variables
| Variable |
Description |
Example |
DATABASE_URL |
PostgreSQL connection string |
postgres://user:pass@host:5432/saleor |
SECRET_KEY |
Django secret key (50+ chars) |
Random string |
ALLOWED_HOSTS |
Comma-separated hostnames |
api.example.com,localhost |
DEFAULT_FROM_EMAIL |
Sender email address |
noreply@example.com |
CELERY_BROKER_URL |
Redis URL for Celery |
redis://redis:6379/1 |
Optional Variables
| Variable |
Description |
Default |
DEBUG |
Django debug mode |
False |
ALLOWED_CLIENT_HOSTS |
Storefront origins for CORS |
localhost |
DEFAULT_CURRENCY |
Fallback currency code |
USD |
DEFAULT_COUNTRY |
Fallback country code |
US |
MAX_CHECKOUT_LINE_QUANTITY |
Max qty per checkout line |
50 |
JAEGER_AGENT_HOST |
OpenTelemetry/Jaeger host |
None |
SENTRY_DSN |
Sentry error tracking DSN |
None |
Celery Worker Configuration
Celery runs as a separate process using the same Saleor codebase:
| Setting |
Value |
Description |
| Broker |
Redis |
CELERY_BROKER_URL = redis://redis:6379/1 |
| Result backend |
Redis |
Optional, for task result storage |
| Concurrency |
--concurrency=4 |
Number of worker threads |
| Queues |
celery (default) |
Default task queue name |
| Beat |
Optional |
Periodic task scheduler |
Key Celery Tasks in Saleor
| Task |
Purpose |
| Webhook delivery |
Send async webhook payloads to Apps |
| Email sending |
Transactional emails (order confirmation, etc.) |
| Thumbnail generation |
Generate product image thumbnails |
| Search indexing |
Update search index entries |
| Export processing |
Handle CSV/XLSX data exports |
S3-Compatible Media Storage
| Variable |
Description |
Example |
AWS_MEDIA_BUCKET_NAME |
S3 bucket name |
saleor-media-prod |
AWS_MEDIA_CUSTOM_DOMAIN |
CDN domain for media |
media.example.com |
AWS_ACCESS_KEY_ID |
IAM access key |
IAM credential |
AWS_SECRET_ACCESS_KEY |
IAM secret key |
IAM credential |
AWS_S3_REGION_NAME |
S3 region |
us-east-1 |
AWS_S3_ENDPOINT_URL |
Custom S3 endpoint (for MinIO, GCS) |
https://s3.example.com |
- Works with any S3-compatible service (AWS S3, Google Cloud Storage, MinIO, DigitalOcean Spaces)
- Set a CDN in front of the bucket for performance
- Configure CORS on the bucket to allow Dashboard uploads
PostgreSQL Configuration
| Setting |
Recommendation |
| Version |
PostgreSQL 14 or 15 |
| Connection pooling |
Use PgBouncer in transaction mode |
| SSL |
Require SSL connections (sslmode=require in DATABASE_URL) |
| Backups |
Automated daily backups with point-in-time recovery |
| Extensions |
pg_trgm (required for search), btree_gin |
| Max connections |
Size for Gunicorn workers + Celery workers + buffer |
Redis Configuration
| Purpose |
Database |
Variable |
| Cache |
redis://redis:6379/0 |
CACHE_URL |
| Celery broker |
redis://redis:6379/1 |
CELERY_BROKER_URL |
- Use separate Redis databases (or instances) for cache and Celery
- Enable Redis persistence (RDB snapshots or AOF) for the Celery broker
Database Migrations
Run migrations during deployment before starting the new application version:
- Always run
python manage.py migrate --noinput before starting Gunicorn/Celery with new code
- Back up the database before applying migrations
- Review migration SQL with
python manage.py sqlmigrate <app> <migration>
- For zero-downtime: ensure migrations are backward-compatible with the running code
Scaling Strategies
Horizontal Scaling
| Component |
Strategy |
Notes |
| API (Gunicorn) |
Add replicas behind load balancer |
Stateless, scale freely |
| Celery workers |
Add worker processes/containers |
Scale based on queue depth |
| Database |
Read replicas for queries |
Write goes to primary |
| Redis |
Redis Cluster or managed Redis |
Separate cache from broker |
Vertical Scaling
| Component |
Tune |
| Gunicorn |
--workers (2 * CPU + 1), --threads per worker |
| Celery |
--concurrency based on task type (I/O vs CPU) |
| PostgreSQL |
shared_buffers, work_mem, effective_cache_size |
Monitoring and Logging
| Tool |
Purpose |
Integration |
| Sentry |
Error tracking |
SENTRY_DSN environment variable |
| OpenTelemetry |
Distributed tracing |
OTEL_EXPORTER_OTLP_ENDPOINT |
| Prometheus |
Metrics collection |
django-prometheus middleware |
| Health check |
Liveness and readiness probes |
/health/ endpoint |
Production Checklist
| Item |
Action |
DEBUG |
Set to False |
SECRET_KEY |
Strong random value, stored in env var |
ALLOWED_HOSTS |
Restrict to actual domain names |
| Database |
SSL enabled, connection pooling, backups configured |
| Media storage |
S3-compatible with CDN |
| Celery |
Running as separate process with monitoring |
| HTTPS |
SSL termination at load balancer or reverse proxy |
| Migrations |
Applied before deploying new code |
| Monitoring |
Sentry, metrics, and health checks enabled |
Best Practices
- Run Celery workers as a separate container or process, never in the API process
- Use connection pooling (PgBouncer) between Gunicorn/Celery and PostgreSQL
- Store all secrets in environment variables, never in source code or Docker images
- Use multi-stage Docker builds to minimize production image size
- Run database migrations in a separate init container or deployment step
- Configure health check endpoints for load balancer and orchestrator probes
- Use S3-compatible storage with a CDN for media files
- Monitor Celery queue depth to detect processing backlogs
- Set up automated database backups with tested restore procedures
Fetch the deployment documentation for current Docker setup, environment variables, and scaling recommendations before implementing.
1---2name: saleor-deploy3description: Deploy Saleor to production — Docker setup, Saleor Cloud, environment variables, Celery workers, S3 media storage, database management, and scaling. Use when deploying Saleor applications.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/saleor-deploy7---89# Saleor Deployment1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.saleor.io deployment production setup` for production deployment guide152. Fetch `https://github.com/saleor/saleor-platform` for Docker Compose reference configuration163. Web-search `site:docs.saleor.io environment variables configuration` for required environment variables174. Web-search `saleor Celery worker configuration production` for Celery setup details185. Web-search `site:docs.saleor.io cloud` for Saleor Cloud managed hosting options1920## Production Docker Setup2122Saleor provides an official Dockerfile with a multi-stage build:2324| Stage | Purpose | Base Image |25|-------|---------|------------|26| **build** | Install dependencies, compile assets | `python:3.12-slim` |27| **production** | Run the application | `python:3.12-slim` |2829### Docker Compose Services3031| Service | Image | Purpose | Port |32|---------|-------|---------|------|33| **api** | `saleor` (custom build) | GraphQL API server (Gunicorn) | 8000 |34| **worker** | `saleor` (same image) | Celery worker process | N/A |35| **db** | `postgres:15-alpine` | PostgreSQL database | 5432 |36| **redis** | `redis:7-alpine` | Cache and Celery broker | 6379 |37| **dashboard** | `saleor-dashboard` | React admin UI | 9002 |38| **storefront** | Custom Next.js | Customer-facing storefront | 3000 |3940## Saleor Cloud (Managed Hosting)4142| Feature | Description |43|---------|-------------|44| **Managed API** | Fully managed Saleor backend, no server maintenance |45| **Auto-scaling** | Scales based on traffic automatically |46| **Managed database** | PostgreSQL with backups and replication |47| **CDN** | Built-in CDN for media and static assets |48| **Environments** | Staging and production environments per project |49| **CLI integration** | Deploy and manage via `saleor` CLI |5051Access via `https://cloud.saleor.io/` — create projects, manage environments, and deploy Apps.5253## Environment Variables5455### Required Variables5657| Variable | Description | Example |58|----------|-------------|---------|59| `DATABASE_URL` | PostgreSQL connection string | `postgres://user:pass@host:5432/saleor` |60| `SECRET_KEY` | Django secret key (50+ chars) | Random string |61| `ALLOWED_HOSTS` | Comma-separated hostnames | `api.example.com,localhost` |62| `DEFAULT_FROM_EMAIL` | Sender email address | `noreply@example.com` |63| `CELERY_BROKER_URL` | Redis URL for Celery | `redis://redis:6379/1` |6465### Optional Variables6667| Variable | Description | Default |68|----------|-------------|---------|69| `DEBUG` | Django debug mode | `False` |70| `ALLOWED_CLIENT_HOSTS` | Storefront origins for CORS | `localhost` |71| `DEFAULT_CURRENCY` | Fallback currency code | `USD` |72| `DEFAULT_COUNTRY` | Fallback country code | `US` |73| `MAX_CHECKOUT_LINE_QUANTITY` | Max qty per checkout line | `50` |74| `JAEGER_AGENT_HOST` | OpenTelemetry/Jaeger host | None |75| `SENTRY_DSN` | Sentry error tracking DSN | None |7677## Celery Worker Configuration7879Celery runs as a separate process using the same Saleor codebase:8081| Setting | Value | Description |82|---------|-------|-------------|83| **Broker** | Redis | `CELERY_BROKER_URL = redis://redis:6379/1` |84| **Result backend** | Redis | Optional, for task result storage |85| **Concurrency** | `--concurrency=4` | Number of worker threads |86| **Queues** | `celery` (default) | Default task queue name |87| **Beat** | Optional | Periodic task scheduler |8889### Key Celery Tasks in Saleor9091| Task | Purpose |92|------|---------|93| Webhook delivery | Send async webhook payloads to Apps |94| Email sending | Transactional emails (order confirmation, etc.) |95| Thumbnail generation | Generate product image thumbnails |96| Search indexing | Update search index entries |97| Export processing | Handle CSV/XLSX data exports |9899## S3-Compatible Media Storage100101| Variable | Description | Example |102|----------|-------------|---------|103| `AWS_MEDIA_BUCKET_NAME` | S3 bucket name | `saleor-media-prod` |104| `AWS_MEDIA_CUSTOM_DOMAIN` | CDN domain for media | `media.example.com` |105| `AWS_ACCESS_KEY_ID` | IAM access key | IAM credential |106| `AWS_SECRET_ACCESS_KEY` | IAM secret key | IAM credential |107| `AWS_S3_REGION_NAME` | S3 region | `us-east-1` |108| `AWS_S3_ENDPOINT_URL` | Custom S3 endpoint (for MinIO, GCS) | `https://s3.example.com` |109110- Works with any S3-compatible service (AWS S3, Google Cloud Storage, MinIO, DigitalOcean Spaces)111- Set a CDN in front of the bucket for performance112- Configure CORS on the bucket to allow Dashboard uploads113114## PostgreSQL Configuration115116| Setting | Recommendation |117|---------|---------------|118| **Version** | PostgreSQL 14 or 15 |119| **Connection pooling** | Use PgBouncer in transaction mode |120| **SSL** | Require SSL connections (`sslmode=require` in DATABASE_URL) |121| **Backups** | Automated daily backups with point-in-time recovery |122| **Extensions** | `pg_trgm` (required for search), `btree_gin` |123| **Max connections** | Size for Gunicorn workers + Celery workers + buffer |124125## Redis Configuration126127| Purpose | Database | Variable |128|---------|----------|----------|129| **Cache** | `redis://redis:6379/0` | `CACHE_URL` |130| **Celery broker** | `redis://redis:6379/1` | `CELERY_BROKER_URL` |131132- Use separate Redis databases (or instances) for cache and Celery133- Enable Redis persistence (RDB snapshots or AOF) for the Celery broker134135## Database Migrations136137Run migrations during deployment before starting the new application version:138- Always run `python manage.py migrate --noinput` before starting Gunicorn/Celery with new code139- Back up the database before applying migrations140- Review migration SQL with `python manage.py sqlmigrate <app> <migration>`141- For zero-downtime: ensure migrations are backward-compatible with the running code142143## Scaling Strategies144145### Horizontal Scaling146147| Component | Strategy | Notes |148|-----------|----------|-------|149| **API (Gunicorn)** | Add replicas behind load balancer | Stateless, scale freely |150| **Celery workers** | Add worker processes/containers | Scale based on queue depth |151| **Database** | Read replicas for queries | Write goes to primary |152| **Redis** | Redis Cluster or managed Redis | Separate cache from broker |153154### Vertical Scaling155156| Component | Tune |157|-----------|------|158| **Gunicorn** | `--workers` (2 * CPU + 1), `--threads` per worker |159| **Celery** | `--concurrency` based on task type (I/O vs CPU) |160| **PostgreSQL** | `shared_buffers`, `work_mem`, `effective_cache_size` |161162## Monitoring and Logging163164| Tool | Purpose | Integration |165|------|---------|-------------|166| **Sentry** | Error tracking | `SENTRY_DSN` environment variable |167| **OpenTelemetry** | Distributed tracing | `OTEL_EXPORTER_OTLP_ENDPOINT` |168| **Prometheus** | Metrics collection | `django-prometheus` middleware |169| **Health check** | Liveness and readiness probes | `/health/` endpoint |170171## Production Checklist172173| Item | Action |174|------|--------|175| `DEBUG` | Set to `False` |176| `SECRET_KEY` | Strong random value, stored in env var |177| `ALLOWED_HOSTS` | Restrict to actual domain names |178| Database | SSL enabled, connection pooling, backups configured |179| Media storage | S3-compatible with CDN |180| Celery | Running as separate process with monitoring |181| HTTPS | SSL termination at load balancer or reverse proxy |182| Migrations | Applied before deploying new code |183| Monitoring | Sentry, metrics, and health checks enabled |184185## Best Practices186187- Run Celery workers as a separate container or process, never in the API process188- Use connection pooling (PgBouncer) between Gunicorn/Celery and PostgreSQL189- Store all secrets in environment variables, never in source code or Docker images190- Use multi-stage Docker builds to minimize production image size191- Run database migrations in a separate init container or deployment step192- Configure health check endpoints for load balancer and orchestrator probes193- Use S3-compatible storage with a CDN for media files194- Monitor Celery queue depth to detect processing backlogs195- Set up automated database backups with tested restore procedures196197Fetch the deployment documentation for current Docker setup, environment variables, and scaling recommendations before implementing.