Setup your Django app with Docker and Compose

Setup your Django app with Docker and Compose

Youssef Naimi - 06 September 2016

6 minutes read

Why Docker!

Docker provides an integrated technology suite that enables development and IT operations teams to build, ship, and run distributed applications anywhere.

And here in OBytes we love Docker because of its :

  • Agility: Docker helps developers create and deploy more applications faster and easier, and flexibility for IT ops to quickly respond to change.
  • Portability: Docker gives your full stack portability across the application lifecycle, teams and physical, virtual and cloud infrastructure.
  • Control: Docker empowers IT ops to securely orchestrate, manage and operate container based applications at scale.

Dockerizing your Django app

This guide demonstrates how to use docker and docker compose to setup and run a simple Django/PostgreSQL application.

Define the project components

For this project we need to have a Dockerfile,a python dependencies (called requirements.txt file later),and docker-compose.yml file. I’m going to assume you’ve installed Docker, if not Do that first, for Docker Compose see here .

  • Create an empty Folder for the project.
  • Create a new file called Dockerfile in your project directory.
  • A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image.
  • Add the following content to the Dockerfile.
  •   FROM python: 2.7
      RUN mkdir /code
      WORKDIR /code
      ADD requirements.txt /code/
      RUN pip install -r requirements.txt
      ADD . /code/

    We use python:2.7 as a base image,The base image is modified by adding a new code directory. The base image is further modified by installing the Python requirements defined in the requirements.txt file.

  • Save and close the Dockerfile.
  • Create a requirements.txt in your project directory.
  • requirements.txt contains all the dependencies for you app to work,and is used by the RUN pip install -r requirements.txt command in your Dockerfile.
  • -Add the required software in the file.
  •   Django
  • Save and close the requirements.txt file.
  • Create a file called docker-compose.yml in your project directory.
  • The docker-compose.yml file describes the services that make your app. In this project we have two services (a web server and database). The compose file also describes which Docker images these services use, how they link together, any volumes they might need mounted inside the containers. Finally, the docker-compose.yml file describes which ports these services expose.
  • Add the content bellow to the file
  •   version: '2'
          image: postgres
          build: .
          command: python runserver
            - .:/code
            - "8000:8000"
            - db

    We use in this file two services the db service and the web service.

  • Save and close the docker-compose.yml file.

Create a Django app

  • Now we create a Django project to start with by building the image from the build context defined in the previous procedure.
  • Go to the root of you project directory.
  • Create the Django app using docker-compose command
  •   $ docker-compose run web startproject myexample

    This will build the web service's image, once the image is built, Compose runs it and create the django project's directory with files representing the project.

  • You can list those files by :
  •   $ ls -l
      drwxr-xr-x 2 root   root   myexample
      -rw-rw-r-- 1 user   user   docker-compose.yml
      -rw-rw-r-- 1 user   user   Dockerfile
      -rwxr-xr-x 1 root   root
      -rw-rw-r-- 1 user   user   requirements.txt

    Setup the database

  • Edit the myexample/ file.
  • Replace the DATABASES = ... with the following :
  •   DATABASES = {
        'default': {
          'ENGINE': 'django.db.backends.postgresql_psycopg2',
          'NAME': 'postgres',
          'USER': 'postgres',
          'HOST': 'db',
          'PORT': 5432,

    These settings are determined by the postgres Docker image specified in docker-compose.yml.

  • Save and close.
  • Run the docker-compose command
  •   $ docker-compose up
      Starting composepractice_db_1...
      Starting composepractice_web_1...
      Attaching to composepractice_db_1, composepractice_web_1
      db_1  | PostgreSQL init process complete; ready for start up.
      db_1  | LOG:  database system is ready to accept connections
      db_1  | LOG:  autovacuum launcher started
      web_1 | Django version 1.8.4, using settings 'composeexample.settings'
      web_1 | Starting development server at
      web_1 | Quit the server with CONTROL-C.

    Congratulation now your Django app is up and running on port 8000 on your Docker host. If you are using a Docker Machine VM, you can use the docker-machine ip MACHINE_NAME to get the IP address.

Docker Running

Best practices for writing Dockerfiles

  • Use a .dockerignore file
  • In most cases, it’s best to put each Dockerfile in an empty directory. Then, add to that directory only the files needed for building the Dockerfile. To increase the build’s performance, you can exclude files and directories by adding a .dockerignore file to that directory as well. This file supports exclusion patterns similar to .gitignore files.
  • Avoid installing unnecessary packages
  • Run only one process per container
  • Minimize the number of layers
  • Sort multi-line arguments
  • Whenever possible, ease later changes by sorting multi-line arguments alphanumerically. This will help you avoid duplication of packages and make the list much easier to update. This also makes PRs a lot easier to read and review. Adding a space before a backslash () helps as well.