How To Dockerize Django Application With PostgreSQL Database

Posted on 134 views

In this tutorial, I will show you how to set up a Docker environment for your Django project that uses PostgreSQL instead of the default SQLite DB in the development phase. In our previous article, we discussed how to dockerize A Django application.

Step 1: Install Docker Engine

You need a Docker runtime engine installed on your server/Desktop. Our Docker installation guides should be of great help.

How to install Docker on CentOS / Debian / Ubuntu

Step 2: Setup the Environment

I have set up a GitHub repo for this project called django-postgresql-docker-dev. Feel free to fork it or clone/download it. First, create the folder to hold your project. My folder workspace is called django-postgresql-docker-dev. CD into the folder then opens it in your IDE.

Step 3: Create Dockerfile

In a containerized environment, all applications live in a container. Containers themselves are made up of several images. You can create your own image or use other images from Docker Hub.

A Dockerfile is Docker text document that Docker reads to automatically create/build an image. Our Dockerfile will list all the dependencies required by our project.

Create a file named Dockerfile. In the file type the following:

# base image
FROM python:3

LABEL Author="CodeGenes"

# The enviroment variable ensures that the python output is set straight
# to the terminal with out buffering it first

#directory to store app source code
RUN mkdir /zuri

#switch to /app directory so that everything runs from here

#copy the app code to image working directory
COPY ./zuri /zuri

#let pip install required packages
RUN pip install -r requirements.txt

Create the Django requirements.txt file and add your projects requirements. Note that I have some requirements that you may not need but the most important one is the Django and psycopg2


Create the folder that will hold the source code; mine is zuri.

Step 3: Working With Docker Compose

From Docker docs;

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.

Our project uses PostgreSQL for database connections. We will, therefore, define two services in our docker-compose file. The first service is db which is the PostgreSQL image and the second is zuri which is our project. Create a file named docker-compose.yml and add these lines:

version: "3"
    image: postgres
      POSTGRES_USER: zuri
      POSTGRES_DB: zuri
      POSTGRES_PASS: zuri1234
      - pgdata:/var/lib/posgresql/data
      context: .
      - "8000:8000"
      - ./zuri:/zuri
    command: python runserver
      - db

The depends_on ensures that the Postgres image is available to our zuri service so it will be automatically created and run.

Also, note the properties under Postgres image. We have defined environment variables to be used by PostgreSQL and defined a volume. The volume pgdata will be created by docker and all the data stored by our project will be saved here. This is recommended because if we delete our containers it also deletes the data in it.

Defining the volume ensures that even if we delete the containers the data will still be available.

Next, we create the Django project itself by building the docker-compose file and using Django command to create the project. Note the name zuri after the run; it is the name of the service in the docker-compose file and the name zuri after startproject is the name of the project Django admin is going to create. In the root of the project open command line and type:

$ docker-compose run zuri django-admin startproject zuri .

Now if you check the folder zuri, you will see the Django project created!

However, we have a little problem. You will notice that the files and folders created are owned by root. We can easily change this by running this command:

$ sudo chown -R $USER:$USER .

Step 4: Connecting to the database

To connect to the database, open the Django settings file and edit the database settings by adding the following:

# Database

        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'zuri',
        'USER': 'zuri',
        'HOST': 'db',
        'PORT': 5432,

The parameters for the name, user and host must be the same as those on docker-compose file. Specifically, the host parameter is the name of the Postgres service name.

In Windows, you might need to edit ALLOWED_HOSTS inside and add your Docker hostname or IP address to the list.

Edit and add:


Okay, we are now done, to start our container run:

$ docker-compose up

Then visit http://localhost:8000/

To test if the database is working let us make migrations. Open a new terminal and execute:

 $ docker-compose run zuri python migrate

or if the container is already running:

 $ docker-compose exec zuri python migrate

From now onwards you will run django commands after docker-compose run zuri [cmd] or docker-compose exec zuri [cmd]

That’s it for now. Peace Out!. The project is available on GitHub here.


Gravatar Image
A systems engineer with excellent skills in systems administration, cloud computing, systems deployment, virtualization, containers, and a certified ethical hacker.