Dockerize Your Django: Effortless Project Deployment

Master the art of deploying Django applications with Docker. This hands-on guide takes you through building and running your Django project in a seamless, containerized environment.

How to Start

The first step to using Docker is to make sure it’s installed on your local machine or server. You can see official Docker's installation guide here.

Once installed, it’s crucial to understand why Docker is so beneficial! Docker allows you to create a consistent, reproducible environment, which is incredibly useful for deploying Django applications. With Docker, you and your team can easily replicate the same production or development setup across different machines or servers. This consistency helps prevent those “it works on my machine” issues and makes deploying changes to production faster and less error-prone. With these basics covered, let's dive into setting up a Docker environment for your Django project!

Project Structure

Check out the full Django project structure we’ll be using in this guide here.

Dockerfile

Dockerfile is a file used to create a custom image of python with additional configuration to serve django project.

Here a basic example of Dockerfile that you can add inside project-directory:

# Base Image
FROM python:3.11-slim

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

# Set work directory
WORKDIR /app

# Install dependencies
COPY requirements.txt /app/
RUN pip install --no-cache-dir -r requirements.txt

# Copy project
COPY . /app/
RUN rm /app/requirements.txt

They are istructions that Docker read from top to bottom to create your custom image.

FROM command used to say Docker how image read from Docker Hub.

ENV used to choose and set variables in our envirorment.

WORKDIR used to create a default working-directory for our project.

COPY used to copy file or folder from localhost to working-directory.

RUN used to execute a command and install dependencis in the image.

Running Application with Dockerfile

# Build image from Dockerfile
docker build -t image_name .

#  Run a container from dockerfile
docker run -dp 127.0.0.1:8000:8000 \
  --name container_name \
  image_name

Docker Compose

Docker compose is useful if you want to run lincked multi-container app for example, django with postgres database in developemnt envirorment or django, postgres, gunicorn and nginx in production envirorment. Here a simply but complet docker compose file example to run easely django with gunicorn and postgres database:

services:
  app:
    build:
      context: ./
      dockerfile: Dockerfile
    image: image_name
    container_name: container_name
    command: gunicorn --bind 0.0.0.0:8000 core.wsgi:application
    env_file:
      - ./.env.app
    volumes:
      - .:/app 
    networks:
      - production-network
    depends_on:
      - db

  db:
    image: postgres
    container_name: container_name
    volumes:
      - db-volume:/var/lib/postgresql/data/
    env_file:
      - ./.env.db
    networks:
      - production-network

volumes:
  db-volume:
    name: volume_name

networks:
  production-network:
    name: production-network

Before you use this docker compose file be sure of have all the dependencis on requirements.txt file:

asgiref==3.8.1
Django==5.1.1
gunicorn==23.0.0
psycopg2-binary==2.9.10
python-dotenv==1.0.1
sqlparse==0.5.1

modify settings.py on django project adding this:

from pathlib import Path
import os
from dotenv import load_dotenv

load_dotenv()

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': os.getenv("DB_NAME"),
        'USER': os.getenv("DB_USER"),
        'PASSWORD': os.getenv("DB_PASSWORD"),
        'HOST': os.getenv("DB_HOST"),
        'PORT': '',
    }
}

and create .env.db and .env.app files inside main project-directory:

# .env.db file that store ENVIRORMENT variables of postgres database
POSTGRES_USER=db_user
POSTGRES_PASSWORD=db_password
POSTGRES_DB=db_name

# .env.app file that store ENVIRORMENT variables of django app
DB_NAME=db_name
DB_USER=db_user
DB_PASSWORD=db_password
DB_HOST=db # name of instance setting on docker compose file

Running Application with Docker Compose

# Start containers
docker compose -p project_name up --build -d

# View running containers
docker compose -p project_name ps

# Prepare the django application
docker compose -p project_name exec app sh -c "python manage.py makemigrations"

docker compose -p project_name exec app sh -c "python manage.py migrate"

docker compose -p project_name exec app sh -c "python manage.py createsuperuser"

Conclusion

Dockerizing your Django project is a powerful way to simplify deployment and ensure consistency across development and production environments. By containerizing your application, you gain greater flexibility, faster setup times, and more reliable deployments—making it easier to collaborate with your team or deploy updates confidently. With the foundational steps covered in this guide, you’re now ready to leverage Docker for seamless Django deployments. Dive deeper, experiment with additional services, and watch your development process transform!

For a more advanced setup, check out our next post where we explore how to Dockerize a Django app with Nginx and Certbot, enhancing security with HTTPS and making your deployment even more robust.