Alpha Coder
Dockerizing Django in development and production

Setting up Docker can sometimes be confusing. There are many little pieces that need to come together for everything to work as expected. Outlined in this post is a simple Docker setup you can use for your Django projects in development and production environments.

TL;DR: Sample project

You can check out the code on GitHub.


FROM python:3.6-alpine

RUN apk --update add \
    build-base \
    postgresql \
    postgresql-dev \
    libpq \
    # pillow dependencies
    jpeg-dev \

RUN mkdir /www
COPY requirements.txt /www/
RUN pip install -r requirements.txt


COPY . /www/

This Dockerfile is pretty straightforward. It starts from a Python-Alpine base image, then installs the dependencies that Django needs, notably postgresql and postgresql-dev. This Django project is setup to use PostgreSQL. If you want to use another database engine like MySQL or MongoDB, you need to install the required adapters/dependencies. Also, if you’re dealing with images (ImageField), you need to install jpeg-dev and zlib-dev as well (see Pillow dependencies).

Afterwards, it installs the packages in requirements.txt, then copies everything in the project root to /www/ where the image would be executed from. ENV PYTHONUNBUFFERED 1 causes all output to stdout to be flushed immediately, so that you can easily see what’s going on inside your Python app from a terminal.


I almost always use Docker Compose with Docker. With Compose, you can run multiple containers at once, and you don’t have to memorize long Docker commands.

version: "3"
    build: .
    restart: on-failure
      - ./.env
    command: python runserver
      - .:/www
      - "8000:8000"
      - db
    image: "postgres:10.3-alpine"
    restart: unless-stopped
      - ./.env
      - "5432:5432"
      - ./postgres/data:/var/lib/postgresql/data

There are two services in this Compose file — web and db. The web service builds the Django app using the Dockerfile in the previous section. A volume is created to map the project directory in the host to the one in the container (- .:/www) so that any changes made on the host are mirrored in the container. The command parameter uses Django’s dev server to run the app (python runserver

The db service uses a PostgreSQL image and maps PostgreSQL’s data directory to ./postgres/data in the host, so that DB data is persisted even if the container gets destroyed. This very PostgreSQL image (the official postgreSQL image) uses several environment variables to configure PostgreSQL, including POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DB.

# .env


The above variables are made available to the services using the env_file parameter. The postgres variables are used by both the web and db service (see the file in the sample project).

My production configs usually differ a bit from their development counterpart. I use Gunicorn to serve the Django app, and NGINX as a reverse proxy and static/media file server.

This setup, while good for production, is not very convenient in development where the goal is often to break things and move fast. Sometimes, I decide to use a managed database service so there’s no need for a Dockerized database server. All these are reflected in my file.

version: "3"
    build: .
    restart: on-failure
      - ./.env
    command: gunicorn --bind dockerizeddjango.wsgi
      - "8080:8080"
      - nginx
    image: "nginx"
    restart: always
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./staticfiles:/static
      - ./mediafiles:/media
      - "80:80"

The web service in the production Compose file looks identical to one in the development file, except for the command parameter (majorly). It uses Gunicorn (which is more suitable) to serve the application (gunicorn — bind dockerizeddjango.wsgi).

There’s also an NGINX service. Notice the volume definitions in this service. The first volume maps /etc/nginx/conf.d to the ./nginx/conf.d folder on the host which contains dockerizeddjango.conf.

# dockerizeddjango.conf
server {
  listen 80;
  server_name localhost;

  # serve static files
  location /static/ {
    alias /static/;

  # serve media files
  location /media/ {
    alias /media/;

  # pass requests for dynamic content to gunicorn
  location / {
    proxy_pass http://web:8080;

This is a very basic Nginx config file. It’s also pretty self-explanatory. It passes requests with /static (e.g and /media (e.g to the /static and /media directories on the web container respectively. These directories are mapped to the /staticfiles and /mediafiles directories on the host where staticfiles are collected and media files uploaded. Other requests are proxied to Gunicorn.

Did you observe the use of service names in some files? e.g POSTGRES_HOST=db and proxy_pass http://web:8080;. db and web resolve to the IP addresses of their containers. This is handled by Docker Compose so that we don’t have to worry about what the IP address of a container is or hardcode IP addresses that might change later.

Use the following command to run the Compose file:

docker-compose -f up --build -d

The -f parameter specifies the production Compose file, (Docker Compose defaults to docker-compose.yml). --build tells Compose to rebuild the images each time the command is run, and the -d flag runs the containers in detached mode so that they keep running in the background even when your terminal is closed.

You can run migrations and create an admin user with the following commands:

docker-compose -f run web python migrate
docker-compose -f run web python collectstatic --noinput

Last modified on 2018-08-15

Comments powered by Disqus