Ir al contenido principal

Dockerize your Django App (for local development on macOS)

I'm writing this guide on how to containerize an existing (simple) Python Django App into Docker for local development since this is how I learned to to develop with Docker, seeing that the existing django images and guides seem to focus on new projects.

For more complete (production-level) stack guides you can refer to Real Python's Django Development with Docker Compose and Machine or transposedmessenger's Deploying Cookiecutter-Django with Docker-Compose.


  • An existing Django app which you can run locally (directly or in Virtualenv). We will run the local dev server with runserver.
  • A requirements.txt file with the app dependencies, as is standard for Python projects; including MySQL-python.
  • Working local MySQL server and existing database. (This guide could easily be adapted for other SQL engines such as Postgres.)
  • Install Docker. You can see Docker as a virtual machine running Linux on top of your OS ("the host"), which in turn can run containers – which act as individual machines.
Keep in mind I'm currently working on a MacBook (macOS 10.13). Locally I'm using stock Python 2.7, Homebrew MySQL 5.7, and Django 1.11 (via pip)


  1. Make sure your Django settings are compatible with the conteinerization;
  2. Create a Dockerfile (and .dockerignore) to define the web app container;
  3. Create docker-compose.yml to setup the web and database services;
  4. Find/Set local MySQL data directory, and run docker-compose!

Django settings

Here, we just want to make sure that our app settings (typically in, use environment variables –which can be provided by Docker (in following sections), to connect to MySQL for example:

import os

# ... your settings

    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': os.getenv('DB_NAME'),
        'USER': os.getenv('USERNAME'),
        'PASSWORD': os.getenv('PASSWORD'),
        'HOST': os.getenv('HOSTNAME'),
        'PORT': os.getenv('PORT'),

# ... more stuff


Note: I use os.getenv because it just returns None if the env var doesn't exist, like for PASSWORD in my case.


This file informs Docker how to build your container image. In the root of your project directory, create a file called Dockerfile (no extension) with these contents:

# Use slim Python as a parent image
FROM python:2.7-slim

# Set the working dir.
ADD . /web

# Install required system libs (so pip install succeeds)
RUN apt-get update
RUN apt-get install -y libmysqlclient-dev
RUN apt-get install -y gcc
# Install server-side dependencies
RUN pip install -r requirements.txt


# Env vars
ENV DB_NAME my_database
ENV HOSTNAME localhost
ENV TOKEN_FOR_MY_APP 3FsMv8pTt62aDwaKkCzsPbBQZ0dSaff4tiP5a2eP

# Run Python's dev web server when the container launches
CMD ["/web/", "runserver", ""]

What this does, first, is that it sets the python:2.7-slim image as the base for our to-be container. I chose 2.7-slim to keep the new image small (2.7 is over 681MB in size while 2.7-slim is 139MB),. Then it installs the libmysqlclient-dev library (needed for Pyton's MySQL-python package) and gcc tool (needed for pip install) on the system. 
(Note that these build dependencies are already included in the python:2.7 image so we wouldn't need to specify installing them if using that heavier option.)

This will also create the /web folder in the container image, and move all the project files (except those specified in .dockerignore) to /web . And it sets some environment variables needed in the application, most notably credentials for the database connection – this we could omit though, since they can be set in the docker command line tool so feel free to adjust at will.

Finally, we have a CMD entry to run the  /web/ runserver  command by default when starting the container. Specifying "" is important because without that, runserver only listens to; That would be a problem because the HTTP request to the web server in the container will not come from its localhost, but from an IP address assigned to the host by Docker (most likely but this could differ among Docker versions).

1. I'm not sure PYTHONUNBUFFERED is needed;
2. For an even smaller image, you can try a Multistage Build.
3. Actually, much of the behavior specified here (/web folder, env vars, CMD) will be overwritten by the compose file (see next section), but I felt it was important keeping it to the Dockerfile to make the web app useful on its own, as it could be built into a separate image with docker build; and for educational purposes (:

You probably also want to create a file called .dockerignore to tell the Docker Builder which files NOT to put in your image at build time. I thought of Python bytecode files and macOS Finder's metadata:


# MacOS

# Python

Notice I also added lines for ".git" and ".env", which you may or may not need. I'm using Git to control the code versioning in my project, and python-dotenv to keep secrets out of the code repository. If you're not familiar with dotenv, I recommend you check it out (originally for Ruby).

Compose file

Note: If I was running Docker on a Linux host (or perhaps Docker on Docker), this step would probably not be necessary, since we could just use a "host" network driver and let the web container defined above connect to the MySQL running on the Docker host directly.
However, host networks do not work on Docker for Mac at the time of writing :/ but I took this challenge as an opportunity to learn how to use Docker Compose.

Create a file called docker-compose.yml (See YAML format) next to the previous files with:

version: '3.2'

    image: mysql:5.7
      - type: bind
        source: ${MYSQL_DATADIR}
        target: /var/lib/mysql
    restart: on-failure
      - db
    build: .
      - .:/web
      - "8000:8000"
      - HOSTNAME=db
    command: "python runserver"
    restart: on-failure

Note: We need version 3.2 for some of the newest format options such as expanded volumes key.

This file defines 2 "services" (each run as a separate container) in the same image. The first one, "db" uses the official MySQL image from Docker Hub, and mounts a special folder from the host (detailed in the next section) into the container's /var/lib/mysql dir. This is a trick for the db service to use the host's MySQL data directory (as described in the mysql image's documentation) – with all the data and permissions you already have established locally, neat! (Although useless for remote deployment.)

The 2nd service, "web" is our Django app. It depends on db. Here, we map the project directory to /web in the container, as well as the 8000 ports between container and host. We also (over)write the HOSTNAME env var with the name of the mysql service for the app to know where to look for it's database connection. (Docker compose, used in the next section, will automatically setup a network where this hostname corresponds to the db service container.)

Show time!

Just one more detail. To complete the local MySQL data dir trick, we need to actually find its location in our system. With mysql.server running locally, run this in Terminal:

mysql -u root -p -N -B -e 'SELECT @@GLOBAL.datadir'

(And enter the password for root user, if any.) Now copy the value (/usr/local/var/mysql in my case) into the following command:

MYSQL_DATADIR=/usr/local/var/mysql docker-compose up

Docker compose reads docker-compose.yml by default and begins the entire process of building the image (in turn looking in .dockerignore and Dockerfile by default for the web service), creating and initializing both service containers, the Docker network, and starting their default commands (mysql, and runserver, respectively).

Keep an eye on the output in the terminal window (conveniently from both containers), and head to http://localhost:8000/ in your browser to see the app running. As usual, Django's runserver will reload when any changes to the app's source code is saved, and this is reflected in the web service container.

OK Bye

Thanks for reading!  ᕕ( ᐛ )ᕗ  I hope you found this guide useful and concise. 

Keep in mind there may be some redundant stuff happening above, which was left for educational purposes as it was a long process for me to figure each step out (so I left traces of each one). There may also be unexplained code here and there, left for you to investigate ;)

Last note: If your Django app is more complex (e.g. using Redis or needing load balancing), I hope this at least gives you an idea on how to begin containerizing it.

Author: @jorgeorpinel
Jorge A Orpinel Pérez (
Independent Software Engineer Consultant


    Entradas populares de este blog

    sqlalchemy ProgrammingError can't adapt type numpy.float64 - Python troubleshooting

    Are you getting a

    sqlalchemy.exc.ProgrammingError: (ProgrammingError) can't adapt type 'numpy.float64'

    It's because psycopg (psycopg2) - which is used inherently by SQL Alchemy but if you're just dealing directly with alchemy you might not know this - has no idea how to make the numpy.core.numerictypes.float64 (complete type path: another thing they don't tell you) a string for SQL querying.

    Simple solution, add:

    # solution by Jorge Orpinel found at rehalcon.blogspotcom
    import numpy
    from psycopg2.extensions import register_adapter, AsIs
    def addapt_numpy_float64(numpy_float64):
    return AsIs(numpy_float64)
    register_adapter(numpy.float64, addapt_numpy_float64)
    somewhere in the program.

    For a more complete reference of the problem see

    Mapa del Metrobus de la Ciudad de México

    Update: Por fin el Gobierno hizo su chamba luego de años de que mi mapa fuera el único en Google Maps. Hoy (05-11-2013) me percaté que en (solo con "www"...) se puede apreciar ya este mapa (zoom centrado en centro de la ciudad):

    Ver Plano de Sistema de Corredores de Transporte Público de Pasajeros del D.F., Metrobús en un mapa ampliado

    Para quien prefiera los iconos que yo utilicé, aquí dejo la última versión que actualicé (hasta línea 4 y proyecto de línea 5): En mi post "Mapa del Metrobus en Google Maps" publiqué el mapa del metrobus en Abril dl 2009. Ahora que hay más estaciones y más líneas, es necsaria esta actualización.
    Incluye íneas 1 a 4 (actual a Junio 13 del 2012). La descripción de cada estación incluye correspondencias con otras líneas de MB y con el meto.
    Además quiciera es incluir el ten ligero, las rutas/paradas del turibus, y algunas rutas de RTP - y tal vez el ten suburbano.
    * En la vista satelital aun no aparecen m…