Deploy Django with Docker Compose - Complete Production Guide

Before you start copy-pasting Docker configurations from Stack Overflow hoping they'll magically work, understanding why each component exists will save you from the debugging hell that starts at deployment time and continues through your first production outage.

The difference between deployments that work and those that collapse under real conditions isn't luck - it's architecture that accounts for how applications actually fail in production.

Required Components

A production Django deployment requires multiple services working in harmony:

Application Server: Gunicorn replaces Django's runserver because the development server will collapse under any real traffic load. Django's built-in server is single-threaded and blocks on each request - fine for development, catastrophic for production. Gunicorn's pre-fork worker model spawns multiple Python processes, each capable of handling requests independently. When one worker crashes from an unhandled exception, the others continue serving traffic while Gunicorn spawns a replacement.

Database: PostgreSQL because SQLite's file-based locking becomes a bottleneck the moment you have concurrent users. SQLite uses database-level locks for writes, meaning every INSERT/UPDATE blocks all other writes. PostgreSQL implements MVCC (Multi-Version Concurrency Control) where readers never block writers and writers rarely block readers. Real production benefits include connection pooling support, advanced indexing strategies like partial and expression indexes, and proper transaction isolation levels that prevent data corruption under load.

Reverse Proxy: Nginx because making Django serve static files wastes precious Python processes on tasks that don't require Python interpretation. Django loads your entire application stack just to return a CSS file - completely inefficient. Nginx serves static assets directly from disk using sendfile() system calls that bypass userspace copying, delivering files at near-memory speeds. More importantly, Nginx handles client connection buffering, protecting your Django processes from slow clients that would otherwise tie up workers for extended periods.

Container Orchestration: Docker Compose manages multi-container applications with service dependencies, networking, and persistent storage. It enables infrastructure as code with version control integration.

Architecture Benefits

This containerized approach provides several production advantages:

Consistent Environments: Docker eliminates "works on my machine" issues by packaging applications with their dependencies, ensuring identical behavior across development, staging, and production environments. Docker images provide immutable infrastructure that prevents configuration drift.

Scalability: Individual services can be scaled independently. Need more application instances? Scale the web service. Database performance issues? Upgrade just the database container. Horizontal scaling and load balancing become straightforward with containerized architectures.

Resource Isolation: Each service runs in its own container with defined resource limits, preventing one component from consuming all system resources. Container resource constraints and memory management ensure predictable performance.

Easy Deployment: Docker Compose files serve as infrastructure as code, making deployments reproducible and version-controllable. Blue-green deployments and rolling updates minimize downtime.

Prerequisites Checklist

Ensure your environment meets these requirements:

• Docker Engine 24.0+ and Docker Compose 2.20+ (latest versions as of August 2025)
• Django 5.1+ project with production settings configured (Django 5.2 is the current stable release)
• Basic understanding of Django applications and database migrations
• SSH access to your production server with sudo privileges
• Python 3.11+ (Python 3.13 is recommended for performance improvements)

With this architecture foundation solid, you understand not just what components you need, but why each one prevents specific production disasters. You're not just following a recipe - you're building a system designed to handle the failure modes that kill deployments in real environments.

But understanding the architecture is just the beginning. Real production deployments fail at predictable points: containers that build locally but crash on the server, database connections that work in development but timeout in production, and static files that serve perfectly until you add SSL.

The Docker configurations that follow aren't just examples - they're battle-tested setups that handle these exact failure scenarios, with specific fixes for each error message you'll encounter when things inevitably go wrong.

Here's where theory meets the harsh reality of production deployments. The Docker configurations in this section aren't the simplified examples you find in most tutorials - they're the hardened setups that prevent the specific failure modes that bring down production systems.

Each configuration addresses real problems: security vulnerabilities that create breach scenarios, performance bottlenecks that cause applications to collapse under load, and operational issues that turn deployments into maintenance nightmares.

Multi-Stage Production Dockerfile

Production Dockerfiles should use multi-stage builds to minimize final image size and improve security. This approach separates build dependencies from runtime requirements, reducing attack surface and improving deployment speed:

###########
## BUILDER #
###########
FROM python:3.13-slim as builder

WORKDIR /usr/src/app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

## Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends gcc

## Install Python dependencies
COPY ./requirements.txt .
RUN pip wheel --no-cache-dir --no-deps --wheel-dir /usr/src/app/wheels -r requirements.txt

#########
## FINAL #
#########
FROM python:3.13-slim

## Create non-root user
RUN mkdir -p /home/app && \
    addgroup --system app && \
    adduser --system --group app

ENV HOME=/home/app
ENV APP_HOME=/home/app/web
RUN mkdir $APP_HOME && \
    mkdir $APP_HOME/staticfiles && \
    mkdir $APP_HOME/mediafiles

WORKDIR $APP_HOME

## Install dependencies from builder stage
COPY --from=builder /usr/src/app/wheels /wheels
RUN pip install --no-cache /wheels/*

## Copy application
COPY . $APP_HOME
RUN chown -R app:app $APP_HOME

## Switch to non-root user
USER app

EXPOSE 8000

Docker Compose Production Configuration

The production compose file defines services, networking, and persistent storage:

version: '3.8'

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile.prod
    command: gunicorn myproject.wsgi:application --bind 0.0.0.0:8000 --workers 3
    volumes:
      - static_volume:/home/app/web/staticfiles
      - media_volume:/home/app/web/mediafiles
    expose:
      - 8000
    env_file:
      - .env.prod
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=${DB_NAME}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 30s
      timeout: 10s
      retries: 5

  nginx:
    image: nginx:alpine
    volumes:
      - static_volume:/home/app/web/staticfiles
      - media_volume:/home/app/web/mediafiles
      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf
    ports:
      - "80:80"
    depends_on:
      - web

volumes:
  postgres_data:
  static_volume:
  media_volume:

Environment Variables Security

Production environments require secure configuration management. Create .env.prod with these essential variables following Django security guidelines and Docker secrets best practices:

DEBUG=0
SECRET_KEY=your-super-secure-secret-key-here
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com

DATABASE_URL=postgres://user:password@db:5432/dbname
DB_USER=django_user
DB_PASSWORD=secure_database_password
DB_NAME=django_production

DJANGO_STATIC_ROOT=/home/app/web/staticfiles
DJANGO_MEDIA_ROOT=/home/app/web/mediafiles

Security Best Practices:

• Generate strong SECRET_KEY using Django's `get_random_secret_key()` function
• Use environment-specific database credentials with proper password policies
• Never commit `.env.prod` files to version control - use .gitignore
• Consider using Docker secrets for highly sensitive data or external secret management

Nginx Configuration

Nginx handles static files and proxies dynamic requests efficiently:

upstream django_app {
    server web:8000;
}

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    
    client_max_body_size 100M;
    
    location /static/ {
        alias /home/app/web/staticfiles/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    location /media/ {
        alias /home/app/web/mediafiles/;
        expires 30d;
    }
    
    location / {
        proxy_pass http://django_app;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }
}

This configuration optimizes static file serving with proper caching headers while ensuring Django receives necessary request metadata for security and functionality. The upstream directive enables load balancing across multiple Gunicorn instances.

These configurations handle the most common production scenarios, but here's what every deployment guide fails to mention: Murphy's Law applies to Docker deployments with surgical precision. The container that builds perfectly in your staging environment will discover the exact configuration edge case that kills production. The database connections that work flawlessly during testing will mysteriously start timing out the moment real traffic hits your server.

Perfect configurations aren't enough. Production success requires knowing how to diagnose and fix the inevitable problems when they surface at 3am with angry users flooding your support channels.

What follows isn't theoretical troubleshooting - it's the exact error messages you'll encounter and the specific fixes that actually work, compiled from deployments where downtime measured in lost revenue and failure taught lessons that documentation never could.

Time to put everything together. This isn't another "run these commands and hope for the best" tutorial - this is the systematic deployment process that works when servers have quirks, networks have latency, and Murphy's Law is actively working against your deadline.

Every command includes the context you need to understand what's happening, why it might fail, and exactly how to fix it when it does. Because in production, "it should work" doesn't pay the bills - only "it actually works" matters.

1. Project Structure Setup

Organize your Django project with these essential production files following Django's project layout conventions and Docker best practices:

myproject/
├── app/
│   ├── myproject/
│   │   ├── settings/
│   │   │   ├── base.py
│   │   │   ├── production.py
│   │   │   └── development.py
│   │   ├── wsgi.py
│   │   └── urls.py
│   ├── manage.py
│   ├── requirements.txt
│   ├── Dockerfile
│   └── Dockerfile.prod
├── nginx/
│   ├── Dockerfile
│   └── nginx.conf
├── docker-compose.yml
├── docker-compose.prod.yml
├── .env.dev
└── .env.prod

2. Configure Production Settings

Create settings/production.py with production-specific configurations following Django's deployment checklist:

from .base import *
import os

DEBUG = False
SECRET_KEY = os.environ.get('SECRET_KEY')
ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', '').split(',')

## Database
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME'),
        'USER': os.environ.get('DB_USER'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST', 'db'),
        'PORT': os.environ.get('DB_PORT', '5432'),
    }
}

## Static and Media Files
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'mediafiles')

## Security Settings - See https://docs.djangoproject.com/en/stable/topics/security/
SECURE_BROWSER_XSS_FILTER = True  # https://docs.djangoproject.com/en/stable/ref/settings/#secure-browser-xss-filter
SECURE_CONTENT_TYPE_NOSNIFF = True  # https://docs.djangoproject.com/en/stable/ref/settings/#secure-content-type-nosniff
X_FRAME_OPTIONS = 'DENY'  # https://docs.djangoproject.com/en/stable/ref/clickjacking/
SECURE_HSTS_SECONDS = 31536000  # https://docs.djangoproject.com/en/stable/ref/settings/#secure-hsts-seconds
SECURE_HSTS_INCLUDE_SUBDOMAINS = True  # https://docs.djangoproject.com/en/stable/topics/security/#ssl-https
SECURE_HSTS_PRELOAD = True  # https://hstspreload.org/

## Logging
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'level': 'ERROR',
            'class': 'logging.FileHandler',
            'filename': '/home/app/web/django.log',
        },
    },
    'loggers': {
        'django': {
            'handlers': ['file'],
            'level': 'ERROR',
            'propagate': True,
        },
    },
}

3. Build and Deploy Commands

Execute these commands in sequence for production deployment, following Docker Compose production guidelines and container orchestration best practices:

Initial Build:

## Build production images (this takes forever the first time - 10+ minutes on most servers)
docker-compose -f docker-compose.prod.yml build --no-cache

## Start services in detached mode
docker-compose -f docker-compose.prod.yml up -d

## If it fails with "network django_default not found" error, run this first:
docker network create django_default

## Check that all services are actually running (not just started)
docker-compose -f docker-compose.prod.yml ps

Database Setup:

## Wait for database to be ready (watch for "database system is ready to accept connections")
docker-compose -f docker-compose.prod.yml logs -f db

## Run migrations (this will fail if Postgres isn't ready yet)
docker-compose -f docker-compose.prod.yml exec web python manage.py migrate --noinput

## Collect static files (Django copies everything to the nginx volume)
docker-compose -f docker-compose.prod.yml exec web python manage.py collectstatic --no-input --clear

## Create superuser (skip this if you plan to use social auth)
docker-compose -f docker-compose.prod.yml exec web python manage.py createsuperuser

4. Verification and Testing

Confirm successful deployment with these verification steps following Django testing best practices and Docker health check guidelines:

Service Health Checks:

## Check all containers are running
docker-compose -f docker-compose.prod.yml ps

## View recent logs
docker-compose -f docker-compose.prod.yml logs --tail=50

## Test database connection
docker-compose -f docker-compose.prod.yml exec web python manage.py dbshell

Application Testing:

• Visit your domain or server IP address
• Test admin panel at /admin/
• Verify static files load correctly
• Upload a file to test media handling
• Check application logs for errors

5. Monitoring and Maintenance

Implement ongoing monitoring procedures using Django logging framework and Docker monitoring tools:

Log Monitoring:

## Follow real-time logs
docker-compose -f docker-compose.prod.yml logs -f

## Check specific service logs
docker-compose -f docker-compose.prod.yml logs nginx
docker-compose -f docker-compose.prod.yml logs web

Database Maintenance:

## Database backup
docker-compose -f docker-compose.prod.yml exec db pg_dump -U $DB_USER $DB_NAME > backup_$(date +%Y%m%d_%H%M%S).sql

## Check database size
docker-compose -f docker-compose.prod.yml exec db psql -U $DB_USER -d $DB_NAME -c "SELECT pg_size_pretty(pg_database_size('$DB_NAME'));"

Resource Monitoring:

## Check container resource usage
docker stats

## Monitor disk space
df -h
docker system df

Following these procedures gives you a Django deployment that responds to requests and passes basic functionality tests. You've achieved what most tutorials promise and then abandon you to figure out on your own.

But here's the reality check: production deployment success isn't measured by "it works on deployment day" - it's measured by "it still works six months later when traffic has grown 10x, you haven't touched the server, and your application is handling real business-critical workflows."

From Working to Production-Ready

Deployment success creates new challenges. Your application is live, users are depending on it, and the stakes for every failure just got dramatically higher. Traffic will grow, security threats will evolve, and performance requirements will increase.

The practices that follow separate deployments that scale gracefully from those that collapse under their first real stress test. These aren't theoretical best practices from documentation - they're the operational disciplines that prevent the disasters that destroy businesses: security breaches that expose customer data, performance bottlenecks that drive users to competitors, and system failures that create downtime measured in lost revenue per minute.