Saleor Development Setup
Before writing code
Fetch live docs:
- Fetch
https://docs.saleor.io/docs/developer/getting-started/architecture for architecture overview
- Web-search
site:docs.saleor.io saleor-platform docker compose setup for Docker-based quickstart
- Web-search
site:docs.saleor.io saleor CLI installation for CLI tooling and commands
- Web-search
site:docs.saleor.io environment variables configuration for .env reference
- Web-search
site:github.com saleor/saleor-platform docker-compose for latest Compose file
Prerequisites
Required Software
| Software |
Minimum Version |
Purpose |
| Python |
3.12+ |
Saleor core runtime |
| PostgreSQL |
14+ |
Primary database |
| Redis |
6+ |
Celery broker, caching |
| Node.js |
18+ |
Dashboard and storefront apps |
| Docker & Docker Compose |
latest |
Recommended local environment |
| Git |
any |
Version control |
PostgreSQL Setup (Without Docker)
- Create a dedicated database:
CREATE DATABASE saleor;
- Create a user with full privileges on that database
- Connection string format:
postgres://user:password@localhost:5432/saleor
Redis Setup
- Default connection:
redis://localhost:6379
- Required for Celery task queue and caching layer
- Saleor does not fall back to an in-memory broker -- Redis is mandatory
Docker Compose Quickstart (saleor-platform)
The saleor-platform repository bundles all Saleor services into a single Compose stack:
| Service |
Container |
Port |
| Saleor Core (API) |
saleor-api |
8000 |
| Saleor Dashboard |
saleor-dashboard |
9000 |
| Saleor Storefront |
saleor-storefront |
3000 |
| PostgreSQL |
saleor-db |
5432 |
| Redis |
saleor-redis |
6379 |
| Celery Worker |
saleor-worker |
-- |
| Jaeger (tracing) |
jaeger |
16686 |
| Mailpit (email) |
mailpit |
8025 |
Clone the platform repository and start all services with docker compose up.
Saleor CLI
| Command |
Purpose |
saleor login |
Authenticate with Saleor Cloud |
saleor env list |
List available environments |
saleor env create |
Create a new Cloud environment |
saleor tunnel |
Expose local app to Saleor for webhook delivery |
saleor app create |
Scaffold a new Saleor App |
saleor app tunnel |
Tunnel local app for development |
saleor storefront create |
Scaffold a storefront project |
Install via npm i -g @saleor/cli -- fetch live docs for current CLI version.
Project Directory Structure (Saleor Core)
| Directory |
Purpose |
saleor/graphql/ |
GraphQL schema, types, resolvers, mutations |
saleor/product/ |
Product, category, collection models |
saleor/order/ |
Order, fulfillment, draft order models |
saleor/checkout/ |
Checkout models and calculations |
saleor/payment/ |
Payment gateway interfaces |
saleor/warehouse/ |
Stock, warehouse, allocation models |
saleor/plugins/ |
Legacy plugin system (deprecated in favor of Apps) |
saleor/webhook/ |
Webhook dispatch and event handling |
saleor/core/ |
Shared utilities, permissions, base models |
| Root |
manage.py, requirements.txt, setup.cfg, .env |
Environment Variables
| Variable |
Purpose |
DATABASE_URL |
PostgreSQL connection string |
REDIS_URL |
Redis connection for Celery and cache |
SECRET_KEY |
Django secret key |
ALLOWED_HOSTS |
Comma-separated allowed hostnames |
DEFAULT_FROM_EMAIL |
Sender email address |
EMAIL_URL |
SMTP connection string |
DASHBOARD_URL |
Dashboard URL for CORS and redirects |
ALLOWED_CLIENT_HOSTS |
Storefront hosts for CORS |
ENABLE_DEBUG_TOOLBAR |
Enable Django Debug Toolbar |
JAEGER_AGENT_HOST |
OpenTelemetry tracing endpoint |
Never hardcode secrets -- always use .env files excluded from version control.
manage.py Commands
| Command |
Purpose |
python manage.py migrate |
Apply database migrations |
python manage.py createsuperuser |
Create admin staff account |
python manage.py populatedb |
Seed sample data |
python manage.py collectstatic |
Collect static files for production |
python manage.py create_thumbnails |
Generate product image thumbnails |
Celery Worker
Saleor uses Celery for asynchronous tasks (email sending, webhook dispatch, thumbnail generation):
| Mode |
Command |
| Development |
celery -A saleor worker --loglevel=info |
| Production |
Use a process manager (systemd, supervisord) |
| Beat scheduler |
celery -A saleor beat for periodic tasks |
Common Issues
| Issue |
Resolution |
| Database connection refused |
Verify PostgreSQL is running and DATABASE_URL is correct |
| Celery tasks not executing |
Ensure Redis is running and REDIS_URL is correct |
| CORS errors from Dashboard |
Check DASHBOARD_URL matches the actual Dashboard origin |
| CORS errors from Storefront |
Check ALLOWED_CLIENT_HOSTS includes the storefront origin |
| Static files 404 |
Run collectstatic or check STATIC_URL config |
| Docker Compose port conflict |
Ensure ports 8000, 9000, 5432, 6379 are free |
Best Practices
- Use
saleor-platform Docker Compose for local development -- avoid manual dependency setup
- Always run
python manage.py migrate after pulling changes with new migrations
- Keep
.env in .gitignore and provide .env.example for team members
- Use
populatedb to seed sample data for development and testing
- Run Celery worker alongside the API server -- async tasks will silently fail without it
- Pin dependency versions in
requirements.txt to avoid unexpected breakage
- Use
saleor tunnel or saleor app tunnel when developing Apps that receive webhooks
Fetch the Saleor setup documentation for exact Docker Compose configuration, CLI flags, and latest environment variable reference before implementing.
1---2name: saleor-setup3description: Set up a Saleor development environment — saleor-platform Docker Compose, CLI, PostgreSQL/Redis prerequisites, manage.py commands, environment variables, project structure. Use when starting a new Saleor project.4---56# Saleor Development Setup78## Before writing code910**Fetch live docs**:111. Fetch `https://docs.saleor.io/docs/developer/getting-started/architecture` for architecture overview122. Web-search `site:docs.saleor.io saleor-platform docker compose setup` for Docker-based quickstart133. Web-search `site:docs.saleor.io saleor CLI installation` for CLI tooling and commands144. Web-search `site:docs.saleor.io environment variables configuration` for .env reference155. Web-search `site:github.com saleor/saleor-platform docker-compose` for latest Compose file1617## Prerequisites1819### Required Software2021| Software | Minimum Version | Purpose |22|----------|----------------|---------|23| Python | 3.12+ | Saleor core runtime |24| PostgreSQL | 14+ | Primary database |25| Redis | 6+ | Celery broker, caching |26| Node.js | 18+ | Dashboard and storefront apps |27| Docker & Docker Compose | latest | Recommended local environment |28| Git | any | Version control |2930### PostgreSQL Setup (Without Docker)3132- Create a dedicated database: `CREATE DATABASE saleor;`33- Create a user with full privileges on that database34- Connection string format: `postgres://user:password@localhost:5432/saleor`3536### Redis Setup3738- Default connection: `redis://localhost:6379`39- Required for Celery task queue and caching layer40- Saleor does not fall back to an in-memory broker -- Redis is mandatory4142## Docker Compose Quickstart (saleor-platform)4344The `saleor-platform` repository bundles all Saleor services into a single Compose stack:4546| Service | Container | Port |47|---------|-----------|------|48| Saleor Core (API) | `saleor-api` | 8000 |49| Saleor Dashboard | `saleor-dashboard` | 9000 |50| Saleor Storefront | `saleor-storefront` | 3000 |51| PostgreSQL | `saleor-db` | 5432 |52| Redis | `saleor-redis` | 6379 |53| Celery Worker | `saleor-worker` | -- |54| Jaeger (tracing) | `jaeger` | 16686 |55| Mailpit (email) | `mailpit` | 8025 |5657Clone the platform repository and start all services with `docker compose up`.5859## Saleor CLI6061| Command | Purpose |62|---------|---------|63| `saleor login` | Authenticate with Saleor Cloud |64| `saleor env list` | List available environments |65| `saleor env create` | Create a new Cloud environment |66| `saleor tunnel` | Expose local app to Saleor for webhook delivery |67| `saleor app create` | Scaffold a new Saleor App |68| `saleor app tunnel` | Tunnel local app for development |69| `saleor storefront create` | Scaffold a storefront project |7071Install via `npm i -g @saleor/cli` -- fetch live docs for current CLI version.7273## Project Directory Structure (Saleor Core)7475| Directory | Purpose |76|-----------|---------|77| `saleor/graphql/` | GraphQL schema, types, resolvers, mutations |78| `saleor/product/` | Product, category, collection models |79| `saleor/order/` | Order, fulfillment, draft order models |80| `saleor/checkout/` | Checkout models and calculations |81| `saleor/payment/` | Payment gateway interfaces |82| `saleor/warehouse/` | Stock, warehouse, allocation models |83| `saleor/plugins/` | Legacy plugin system (deprecated in favor of Apps) |84| `saleor/webhook/` | Webhook dispatch and event handling |85| `saleor/core/` | Shared utilities, permissions, base models |86| Root | `manage.py`, `requirements.txt`, `setup.cfg`, `.env` |8788## Environment Variables8990| Variable | Purpose |91|----------|---------|92| `DATABASE_URL` | PostgreSQL connection string |93| `REDIS_URL` | Redis connection for Celery and cache |94| `SECRET_KEY` | Django secret key |95| `ALLOWED_HOSTS` | Comma-separated allowed hostnames |96| `DEFAULT_FROM_EMAIL` | Sender email address |97| `EMAIL_URL` | SMTP connection string |98| `DASHBOARD_URL` | Dashboard URL for CORS and redirects |99| `ALLOWED_CLIENT_HOSTS` | Storefront hosts for CORS |100| `ENABLE_DEBUG_TOOLBAR` | Enable Django Debug Toolbar |101| `JAEGER_AGENT_HOST` | OpenTelemetry tracing endpoint |102103Never hardcode secrets -- always use `.env` files excluded from version control.104105## manage.py Commands106107| Command | Purpose |108|---------|---------|109| `python manage.py migrate` | Apply database migrations |110| `python manage.py createsuperuser` | Create admin staff account |111| `python manage.py populatedb` | Seed sample data |112| `python manage.py collectstatic` | Collect static files for production |113| `python manage.py create_thumbnails` | Generate product image thumbnails |114115## Celery Worker116117Saleor uses Celery for asynchronous tasks (email sending, webhook dispatch, thumbnail generation):118119| Mode | Command |120|------|---------|121| Development | `celery -A saleor worker --loglevel=info` |122| Production | Use a process manager (systemd, supervisord) |123| Beat scheduler | `celery -A saleor beat` for periodic tasks |124125## Common Issues126127| Issue | Resolution |128|-------|-----------|129| Database connection refused | Verify PostgreSQL is running and `DATABASE_URL` is correct |130| Celery tasks not executing | Ensure Redis is running and `REDIS_URL` is correct |131| CORS errors from Dashboard | Check `DASHBOARD_URL` matches the actual Dashboard origin |132| CORS errors from Storefront | Check `ALLOWED_CLIENT_HOSTS` includes the storefront origin |133| Static files 404 | Run `collectstatic` or check `STATIC_URL` config |134| Docker Compose port conflict | Ensure ports 8000, 9000, 5432, 6379 are free |135136## Best Practices137138- Use `saleor-platform` Docker Compose for local development -- avoid manual dependency setup139- Always run `python manage.py migrate` after pulling changes with new migrations140- Keep `.env` in `.gitignore` and provide `.env.example` for team members141- Use `populatedb` to seed sample data for development and testing142- Run Celery worker alongside the API server -- async tasks will silently fail without it143- Pin dependency versions in `requirements.txt` to avoid unexpected breakage144- Use `saleor tunnel` or `saleor app tunnel` when developing Apps that receive webhooks145146Fetch the Saleor setup documentation for exact Docker Compose configuration, CLI flags, and latest environment variable reference before implementing.
OrcaQubits