# Django Production Stack

> Production Django with Gunicorn, Celery, PostgreSQL, and Redis.

- Category: Full Web Stacks
- Difficulty: advanced
- Components: django, gunicorn, celery, postgresql, redis, nginx
- Tags: django, python, gunicorn, celery, production
- Source: https://docker.recipes/full-stacks/django-production

## Overview

Django is a high-level Python web framework that follows the "batteries included" philosophy, providing a robust foundation for building complex web applications. Originally developed at a newspaper company in 2003, Django emphasizes rapid development, clean pragmatic design, and the DRY (Don't Repeat Yourself) principle. Its built-in admin interface, ORM, authentication system, and security features have made it the framework of choice for content-heavy sites like Instagram, Pinterest, and The Washington Post. This production stack combines Django's web framework with Gunicorn as the WSGI server, providing better performance and stability than Django's development server. PostgreSQL serves as the primary database, offering ACID compliance and advanced querying capabilities that complement Django's ORM perfectly. Redis handles caching, session storage, and serves as Celery's message broker for background task processing. Celery workers and beat scheduler enable asynchronous task processing, while Nginx acts as a reverse proxy and static file server. Flower provides real-time monitoring of Celery tasks and workers. This configuration addresses the core challenges of production Django deployments: database performance, background task processing, static file serving, and horizontal scaling. The stack is ideal for content management systems, e-commerce platforms, and data-driven applications that require robust background processing capabilities. Startups scaling beyond development environments, established companies modernizing legacy systems, and teams building API-heavy applications will find this combination provides the reliability and performance needed for production workloads.

## Features

- Gunicorn multi-worker WSGI server with 4 default workers for handling concurrent requests efficiently
- Celery distributed task queue with separate worker and beat scheduler containers for background job processing
- PostgreSQL 15 with Alpine Linux providing ACID-compliant storage with advanced JSON and full-text search capabilities
- Redis 7 serving dual roles as Django cache backend and Celery message broker with data persistence
- Nginx reverse proxy with static file serving, eliminating Django's overhead for CSS, JavaScript, and media files
- Flower web-based Celery monitoring dashboard accessible on port 5555 for real-time task inspection
- Django collectstatic integration with shared volumes for efficient static asset management
- Multi-container architecture enabling independent scaling of web workers, background workers, and database components

## Use cases

- Content management systems requiring background image processing and email notifications
- E-commerce platforms with inventory updates, order processing, and payment webhook handling
- Social media applications needing user-generated content moderation and notification systems
- Data analytics dashboards with scheduled report generation and CSV export functionality
- API-driven applications serving mobile apps with caching and session management requirements
- Multi-tenant SaaS platforms requiring database isolation and background tenant maintenance tasks
- News and publishing websites with automated content aggregation and social media posting

## Prerequisites

- Minimum 2GB RAM for all services combined (PostgreSQL 1GB, Redis 512MB, Django containers 512MB total)
- Docker Engine 20.10+ and Docker Compose V2 for proper networking and volume management
- Basic understanding of Django settings.py configuration and environment variables
- Familiarity with PostgreSQL connection strings and Redis URL formatting
- Knowledge of Nginx configuration for custom SSL certificates and domain routing
- Understanding of Celery task decorators and Django signal handlers for background processing

## docker-compose.yml

```yaml
services:
  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=django
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=django_app
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - django_net

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - django_net

  django:
    build:
      context: .
      dockerfile: Dockerfile
    command: gunicorn config.wsgi:application --bind 0.0.0.0:8000 --workers 4
    environment:
      - DATABASE_URL=postgres://django:${POSTGRES_PASSWORD}@postgres:5432/django_app
      - REDIS_URL=redis://redis:6379/0
      - SECRET_KEY=${DJANGO_SECRET_KEY}
      - DEBUG=false
      - ALLOWED_HOSTS=localhost,127.0.0.1
    volumes:
      - static_files:/app/staticfiles
      - media_files:/app/media
    depends_on:
      - postgres
      - redis
    networks:
      - django_net

  celery-worker:
    build:
      context: .
      dockerfile: Dockerfile
    command: celery -A config worker -l info
    environment:
      - DATABASE_URL=postgres://django:${POSTGRES_PASSWORD}@postgres:5432/django_app
      - REDIS_URL=redis://redis:6379/0
      - SECRET_KEY=${DJANGO_SECRET_KEY}
    depends_on:
      - postgres
      - redis
    networks:
      - django_net

  celery-beat:
    build:
      context: .
      dockerfile: Dockerfile
    command: celery -A config beat -l info
    environment:
      - DATABASE_URL=postgres://django:${POSTGRES_PASSWORD}@postgres:5432/django_app
      - REDIS_URL=redis://redis:6379/0
      - SECRET_KEY=${DJANGO_SECRET_KEY}
    depends_on:
      - postgres
      - redis
    networks:
      - django_net

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - static_files:/app/staticfiles:ro
      - media_files:/app/media:ro
    depends_on:
      - django
    networks:
      - django_net

  flower:
    build:
      context: .
      dockerfile: Dockerfile
    command: celery -A config flower --port=5555
    ports:
      - "5555:5555"
    environment:
      - DATABASE_URL=postgres://django:${POSTGRES_PASSWORD}@postgres:5432/django_app
      - REDIS_URL=redis://redis:6379/0
      - SECRET_KEY=${DJANGO_SECRET_KEY}
    depends_on:
      - celery-worker
    networks:
      - django_net

volumes:
  postgres_data:
  redis_data:
  static_files:
  media_files:

networks:
  django_net:
```

## .env

```bash
# Django Production
POSTGRES_PASSWORD=secure_postgres_password
DJANGO_SECRET_KEY=your_very_long_secret_key_here

# Django at http://localhost
# Flower at http://localhost:5555
```

## Usage notes

- Django at http://localhost
- Flower (Celery monitor) at http://localhost:5555
- Run migrations before start
- Collect static files
- 4 Gunicorn workers default

## Troubleshooting

- django.db.utils.OperationalError: FATAL: password authentication failed: Verify POSTGRES_PASSWORD environment variable matches in all Django containers
- Celery workers not processing tasks: Check Redis connectivity and ensure REDIS_URL points to redis:6379, not localhost
- Static files not loading (404 errors): Run docker-compose exec django python manage.py collectstatic before starting nginx service
- Gunicorn timeout errors under load: Increase worker count in command or add --timeout 120 flag for long-running requests
- PostgreSQL container fails to start: Remove postgres_data volume if changing POSTGRES_USER or database initialization parameters
- Flower dashboard showing no workers: Ensure celery-worker container is running and Redis connection is established before starting Flower

