Docker & Compose for Django in production

Set it up

Guides that take this from nothing to running in production.

• Deploy Django with Docker Compose in Production

  Many Docker Compose examples for Django are built for local development, not production.

• How to Dockerize a Django App for Production

  A Dockerized Django app that works in development is not automatically safe for production.

• Deploy Django with Podman and Quadlet

  Run Django in rootless Podman containers managed by systemd with Quadlet: container, network, and volume units, Podman secrets, health checks, and auto-updates.

• Build Multi-Architecture Django Docker Images

  Build Django images for both amd64 and arm64 (Graviton, Ampere, Apple Silicon) with docker buildx: QEMU versus native runners, wheels, caching in GitHub Actions, and verifying manifests.

• Run Django Management Commands in Docker and Kubernetes

  Run Django manage.py commands against containerised deployments: docker compose exec versus run, kubectl exec versus one-off Jobs, loading the right settings and secrets, interactive shells, and keeping one-off commands out of web containers.

• Write a Docker Entrypoint Script for Django

  Write a robust docker-entrypoint.sh for Django: wait for dependencies, optionally run migrations and collectstatic behind flags, support web, worker, and one-off commands, exec the final process for signals, and keep secrets out of logs.

• Separate Dev and Prod With Docker Compose Override Files

  Use one compose.yaml for a Django stack with compose.override.yaml for development and compose.prod.yaml for production: bind mounts and runserver locally, built images, restart policies, and no exposed database ports in production.

• Run a Django Docker Container as a Non-Root User

  Run Django containers as a non-root user: create a dedicated user in the Dockerfile, fix ownership of app, static, and media paths, handle volume permissions, bind high ports, and add a read-only root filesystem and dropped capabilities.

• Use Docker Secrets With Django

  Pass Django secrets to containers as files instead of environment variables: Docker Compose and Swarm secrets mounted at /run/secrets, the _FILE convention, reading them in settings, and keeping secrets out of images and docker inspect.

• Docker vs a Plain VPS for Django

  Should you deploy Django with Docker or directly on a VPS with systemd? Compare reproducibility, deploy workflow, performance, debugging, security updates, and team skills, with a recommendation for solo developers, small teams, and growing apps.

• Deploy Django With Portainer Stacks

  Deploy a Django app with Portainer: define a Compose stack with web, worker, Postgres, and Redis, pull images from a private registry, set environment variables and secrets, enable Git-based redeploys or webhooks, and add a reverse proxy for HTTPS.

• Deploy Django on HashiCorp Nomad

  Deploy Django on HashiCorp Nomad: write a job with web, worker, and migration tasks, pull Docker images, inject secrets from Vault or Nomad Variables with templates, register services, route traffic through Traefik or Consul, and roll out safely.

• Build Django Images With Cloud Native Buildpacks

  Build production Django container images without a Dockerfile using Cloud Native Buildpacks and the pack CLI: choose a builder, configure Python version and start command with a Procfile, run collectstatic, rebase images for OS patches, and use it in CI.

• Deploy django CMS to Production

  Deploy a django CMS site to production: configure settings for CMS and filer, PostgreSQL, media on object storage, static files, caching of rendered pages and menus, search engine friendly URLs, and a release process for template and plugin changes.

• Deploy Saleor to Production

  Deploy the Saleor headless e-commerce platform, built on Django and GraphQL, to production: run the API container with PostgreSQL and Redis, configure Celery workers, media storage, secrets, allowed hosts and CORS for the dashboard and storefront, and run migrations on upgrade.

• Build a Distroless Docker Image for Django

  Build a minimal, shell-less production image for Django using a multi-stage build with a Debian builder and a distroless or Chainguard Python runtime: copy the virtualenv, run as non-root, handle collectstatic and migrations without a shell, and debug safely.

• Sign and Verify Django Docker Images With Cosign

  Sign Django container images with Sigstore Cosign in CI using keyless signing through GitHub Actions OIDC, attach SBOM and provenance attestations, and verify signatures before deploy or with a Kubernetes admission policy.

• Deploy Django on Google Cloud Run

  If you want to deploy Django on Google Cloud Run, the basic path is straightforward: build a container and run it. The production-safe part is where most deployments fail.

• Deploy Django on AWS ECS Fargate

  Run Django on AWS ECS Fargate with an ECR image, Secrets Manager credentials, an Application Load Balancer, one-off migration tasks, and safe rolling deploys.

• Deploy Django with Kamal

  Deploy a Dockerized Django app with Kamal 2: deploy.yml, secrets, kamal-proxy HTTPS, a Postgres accessory, safe migrations, health checks, and rollbacks.

• Deploy Django on Azure Container Apps

  Deploy a containerized Django app to Azure Container Apps with Azure Container Registry, PostgreSQL Flexible Server, secrets, a migration job, custom domains, and revisions.

• Deploy Django with Coolify

  Deploy Django on your own server with Coolify: Dockerfile builds from Git, managed PostgreSQL and Redis, automatic HTTPS, environment variables, migrations, and backups.

• Deploy Django with CapRover

  Deploy Django with CapRover: captain-definition, a Gunicorn Dockerfile, one-click PostgreSQL, container port and HTTPS settings, persistent media, and safe migrations.

• Deploy Django with Docker Swarm

  Deploy Django with Docker Swarm: a stack file with replicas, Docker secrets, rolling start-first updates with automatic rollback, one-off migrations, and Nginx in front.

• Deploy Django with Traefik and Docker

  Put Traefik in front of a Dockerized Django app: automatic Let's Encrypt certificates, HTTP to HTTPS redirects, Docker labels for routing, static files, and upload limits.

• Preview Environments for Django Pull Requests

  Spin up a temporary Django environment for every pull request: GitHub Actions, Docker Compose on a preview host, wildcard subdomains, per-PR databases with seed data, and automatic teardown.

• Deploy Django Docker Images from GitHub Container Registry

  Build Django images in GitHub Actions, push them to GHCR with immutable tags, pull them on servers with read-only credentials, deploy by tag or digest, and clean up old versions.

• Self-Host Django Media Storage With MinIO

  Run MinIO as self-hosted S3-compatible storage for Django uploads: deploy it with Docker Compose or systemd, create a bucket and scoped user, configure django-storages, put MinIO behind Nginx with TLS, and back it up.

• Create a Django Superuser in Production Without a Shell

  Create the first Django admin user in production non-interactively: createsuperuser --noinput with DJANGO_SUPERUSER_ environment variables, one-off containers and Jobs, PaaS consoles, an idempotent management command, and securing the account afterwards.

• Kubernetes vs Docker Compose for Django

  Compare Kubernetes and Docker Compose for running Django in production: single-host simplicity versus multi-node scheduling, rolling updates, autoscaling, secrets, operational cost, and when a team should move from Compose to Kubernetes.

• Deploy Django With Dokploy on Your Own Server

  Deploy Django with Dokploy, an open-source self-hosted PaaS: install it on a VPS, create an application from Git with a Dockerfile or Nixpacks, add PostgreSQL and Redis, configure domains with automatic HTTPS, run migrations, and schedule database backups.

• Deploy Django With Easypanel

  Deploy Django with Easypanel, a Docker-based server control panel: create an app service from GitHub with a Dockerfile or buildpacks, add Postgres and Redis services, set environment variables, mount volumes for media, and enable HTTPS on a custom domain.

• Deploy Django Behind Nginx Proxy Manager

  Put a Docker-based Django app behind Nginx Proxy Manager: create a proxy host with Let’s Encrypt, connect containers on a shared network, forward the right headers, serve static files, allow large uploads, and keep the admin UI private.

Run it well

Tuning, reliability, and operations once it works.

• Build Smaller, Faster Django Docker Images

  Shrink and speed up Django Docker images: slim base images, multi-stage builds, layer ordering, BuildKit cache mounts, .dockerignore, and measurement.

• Scan Django Docker Images for Vulnerabilities With Trivy

  Scan Django container images with Trivy for vulnerable OS packages and Python dependencies: run it locally and in CI, fail builds on fixable critical issues, ignore false positives with expiry, rebuild on new base images, and scan running registries.

• Speed Up Django Docker Builds With Layer and Cache Mounts

  Make Django Docker builds fast in CI and locally: order layers so dependencies cache, BuildKit cache mounts for pip and uv, registry-backed cache for CI, .dockerignore, and multi-stage builds that compile once.

Check it

Review lists to run before launch or after a change.

• Django Docker Production Checklist

  Review a Dockerized Django deployment before production: image build, non-root user, secrets, health checks, volumes, logging, resource limits, and release steps.

Fix it

Errors and symptoms, each traced to a cause and a fix.

• Fix a Django Docker Container That Exits Immediately

  Fix Django containers that exit or restart-loop on start: exit codes and logs, CMD and entrypoint mistakes, missing env vars, and database readiness.

• Fix Django Cannot Connect to Postgres in Docker Compose

  Fix Django connection errors to PostgreSQL in Docker Compose: localhost versus service names, readiness health checks, credentials in volumes, networks, and ports.

• Fix Environment Variables Not Loaded in Docker Compose

  Fix Django settings missing environment variables under Docker Compose: .env versus env_file, variable precedence, recreating containers, $ in values, build-time versus runtime, and docker compose config.

• Fix Permission Denied on Docker Volumes for Django

  Fix PermissionError Errno 13 when a non-root Django container writes to media or data volumes: numeric UIDs, named volume initialisation, bind mount ownership, SELinux labels, and rootless mappings.

• Fix a Django Docker Container Marked Unhealthy

  Fix a Django Docker container stuck in unhealthy status: debug the HEALTHCHECK command, use a health endpoint that works without curl, ALLOWED_HOSTS and HTTPS redirects, start_period for migrations, and dependent services.

• Make Docker Compose Wait for PostgreSQL Before Django Starts

  Stop Django failing with could not connect to server or connection refused when Docker Compose starts it before PostgreSQL is ready: use depends_on with service_healthy, pg_isready health checks, and retry logic in the entrypoint.

• Fix Docker Entrypoint "permission denied" or "no such file" for Django

  Fix Django containers that fail with exec ./entrypoint.sh: permission denied or exec format error and no such file or directory: set the executable bit in Git, convert CRLF line endings, and use the right shebang.

• Stop Docker Logs From Filling the Disk on a Django Host

  Stop Docker container logs from filling the disk on a Django server: find the large json.log files, set max-size and max-file in daemon.json or Compose, use the local driver, and reduce noisy logging.

• Fix Docker "No Space Left on Device" When Building or Running Django

  Fix Docker no space left on device during Django image builds and deploys: measure what docker system df reports, prune build cache, images, and volumes safely, set log limits, and stop CI runners and servers from filling up again.

• Fix Docker "exec format error" for a Django Image

  Fix the Docker error exec /usr/local/bin/docker-entrypoint.sh exec format error for Django containers: rebuild for the right CPU architecture with buildx, fix Windows line endings and missing shebangs, and verify image platforms before deploy.

• Fix Docker "Port Is Already Allocated" for Django Compose Stacks

  Fix Docker Compose errors Bind for 0.0.0.0:8000 failed port is already allocated and address already in use for Django, Postgres, and Redis: find the process or container holding the port, remove orphans, and stop publishing ports you do not need.

• Fix pip "Temporary Failure in Name Resolution" During Docker Builds

  Fix pip install failing during a Django Docker build with Temporary failure in name resolution or Failed to establish a new connection: diagnose Docker DNS, corporate proxies, VPNs, and IPv6, and configure daemon DNS or build-time proxy arguments.

• Why Django Docker Builds Fail on Alpine, and How to Fix Them

  Fix Django Docker builds that fail or crawl on python:alpine: understand musl and missing wheels, install the right build packages for psycopg, Pillow, and cryptography, or switch to python:slim for faster, smaller, more reliable images.

• Fix Django Static Files Not Updating With a Docker Volume

  Fix Django CSS and JavaScript that stay old after a Docker deploy because a named volume hides the new collectstatic output: understand how volumes shadow image files, collect at the right time, and share static files with Nginx correctly.

• Fix Django Logs and print() Output Not Showing in docker logs

  Fix Django, Gunicorn, and Celery output missing from docker logs or appearing late: set PYTHONUNBUFFERED, log to stdout instead of files, configure Gunicorn access and error logs, and keep LOGGING from silencing django.request errors.

• Fix WeasyPrint "Cannot Load Library" for Django PDF Generation in Docker

  Fix WeasyPrint OSError cannot load library gobject-2.0-0, libpango, or libharfbuzz when generating PDFs in Django on Docker, Heroku, or a slim server: install Pango and fonts, use the right package names, and keep PDF rendering in a worker.

• Fix Django Static Files 404 in Docker

  Fix Django static files returning 404 in Docker: collectstatic in the image, shared volumes between Django and Nginx, bind mounts hiding files, and WhiteNoise setup.

• Fix Uploaded Files Disappearing After a Django Redeploy

  Fix Django media uploads that vanish after a redeploy: ephemeral container and PaaS filesystems, MEDIA_ROOT inside release directories, missing volumes, and moving uploads to object storage.

• Fix Let's Encrypt "too many certificates" Rate Limits

  Fix Let’s Encrypt rate limit errors such as too many certificates already issued for this exact set of domains and too many failed authorizations: stop reissuing on every deploy, persist certificates, and use the staging environment.

• Fix PostgreSQL "Could Not Resize Shared Memory Segment" in Docker

  Fix the PostgreSQL error could not resize shared memory segment No space left on device in Docker and Kubernetes: raise /dev/shm with shm_size or a memory-backed emptyDir, and tune parallel query and work_mem for Django workloads.

• Fix Celery Beat "Pidfile Already Exists" in Docker and systemd

  Fix Celery beat failing with ERROR: Pidfile (celerybeat.pid) already exists. Seems we’re already running? after container or server restarts: disable the pidfile in Docker, place it in /run under systemd, and make sure only one beat runs.

• Fix GeoDjango "Could Not Find the GDAL Library" in Production and Docker

  Fix the GeoDjango ImproperlyConfigured error could not find the GDAL library (tried gdal, GDAL...) on servers and in Docker: install GDAL, GEOS, and PROJ system packages, set GDAL_LIBRARY_PATH when needed, and match library versions to Django.

• Fix ECS "Essential Container in Task Exited" for a Django Service

  Fix AWS ECS tasks that stop with Essential container in task exited for Django on Fargate or EC2: read the stopped reason and CloudWatch logs, fix missing secrets and permissions, health check failures, exit codes 137 and 1, and migration commands.

Learning paths through this topic

• Docker, from image to productionBuild a production image, run it with Compose, ship it from CI, and check the result.

Related topics