Docker Compose for Django


In order to follow this tutorial on using Docker Compose and Django please make sure you have Docker and Docker Compose installed. You can follow the instructions here.

For this tutorial I am using a linux like environment. If you are using windows you should be able to follow along if you use the docker terminal.


By the end of this tutorial you will be able to dockerize a Django application connected to a postgres database in two separate docker containers.


Docker Set Up

  • Create a new directory. mkdir tutorial. and CD into this directory.
  • Create a new file called Dockerfile  and add the following content:
FROM python:2.7 # Sets the base image for the following commands.
ENV PYTHONUNBUFFERED 1 # define environment variable
RUN mkdir /scripts # executes command in new layer on top of current image.
WORKDIR /scripts # defines working directory for RUN and ADD commands below.
ADD requirements.txt /scripts/ # copies requirements.txt into filesystem of image in /scripts/ directory.
RUN pip install -r requirements.txt #install python packages listed in requirements.txt
ADD . /scripts/ # copies everything in current directory into filesystem of image in /scripts/ directory.
  • Save and close the file.
  • Create a requirements.txt file in your project directory. This file is where you specify what packages to install via the RUN pip install -r requirements.txt  command in the Dockerfile.
  • Add the following lines into the requirements.txt file
  • Create a docker-compose.yml file in your project directory. (Note you can also use .yaml)
    • This file describes the services that this app will use. In this tutorial there will be a web server and a database using Postgres.
    • The docker-compose.yml file also describes which images the services will use, how the different containers link together, any volumes that might need to be mounted inside the individual containers. Finally, the docker-compose.yml file also describes which ports are exposed for these containers to communicate with each other. 
    • Please refer to this reference to learn more about how docker-compose.yml files work.
  • Add the following into the docker-compose.yml file:
version: '2' # docker-compose.yml files can either be version 1,2,2.1 or 3.
  services: # define services
    db: # service name
      image: postgres:latest # describes image the db service will use.
    web: # service name
      build: . # configuration option to be run at build time.
      command: python runserver [::]:8000 # Override the default command.
        - .:/scripts # mounts . in host to /scripts in container.
      ports: # expose ports [HOST:CONTAINER]
        - "8000:8000"
      links: # Link to containers in another service.
        - db:db
  • Save and close the docker-compose.yml file just created.

Django Project Setup

  • CD into the root of your project directory.
  • Create Django project using docker-compose command (this executes the docker-compose.yml commands defined in the previous step).
docker-compose run web startproject dockerdjango .
NOTE: You may need to start a docker-machine prior to running the above command.
docker-machine create -d virtualbox default
eval $(docker-machine env default)
  • After the docker-compose command completes the structure of your project should be like follows:
-rw-r--r-- 1 name staff 152 30 Jan 21:26 Dockerfile
-rw-r--r-- 1 name staff 562 30 Jan 21:33 docker-compose.yml
drwxr-xr-x 6 name staff 204 30 Jan 21:41 dockerdjango
-rwxr-xr-x 1 name staff 810 30 Jan 21:41
-rw-r--r-- 1 name staff 16 30 Jan 21:27 requirements.txt

if your file privileges do not match then you will need to change these privileges via 
sudo chown ...

Connecting to the database (Postgres)

  • In project directory edit the dockerdjango/ and replace the DATABASES variable as follow:
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': 'postgres',
        'USER': 'postgres',
        'HOST': 'db',
        'PORT': 5432,
  • Save and close the file.
  • Run the docker-compose up --build command in the terminal (make sure you are at the same directory level as the docker-compose.yml file created earlier.
  • You can now access your docker app by navigating to the IP address of the docker-machine docker-machine ip default and going to port 8000.

You should see the following screen below.

Django Success


Congratulations. You have know dockerized a django app and connected it to a postgres database docker container. You can now extend this template and build a django application that transfers data between the web container and the db container.

If you have a specific problem that you think I will be able to assist you with please do not hesitate to contact me here

Found this tutorial useful? Signup to programmathics' newsletter to be updated of the next tutorial.

Check out this tutorial to build a django application through docker

Subscribe to our mailing list

* indicates required