Docker Development Environment for Django with PostgreSQL

Adrian Sebuliba
4 min readMar 3, 2021
Image by Dominik Luckmann

Assuming you have python 3+ and docker already installed on your computer, the following are the steps you would take to set up a simple development environment for your Django Web Application.
Step 1:

Pick a location for your code, preferably the Desktop, and make a directory there through your terminal for Mac/Linux users or Command Line(CMD) for Windows users. I will call mine django_docker_playground. Then navigate to that directory as shown below.

$ cd ~/Desktop$ mkdir django_docker_playground$ cd django_docker_playgound

While inside the django_docker_playground folder, create the virtual environment by running the command below.

$ python3 -m venv venv

The command above will create a folder called venv inside the django_docker_playground folder.

Next, activate the virtual environment by running the command below

$ source venv/bin/activate

Now your terminal should look something like this

(venv) $

Now Install Django as shown below. I will be using Django 2.2 for this exercise

(venv) $ pip install django==2.2

Next, create a Django project called django_docker_project, using the django-admin’s startproject command as follows

(venv) $ django-admin startproject django_docker_project .

Notice the dot(.) character after the project name. This ensures that only one folder is created.

Finally, initialize the default SQLite database and start the development webserver with commands below respectively.

(venv) $ ./ migrate


(venv) $ ./ runserver

Visit in your web browser. The Django Welcome page should show up.

Step 2:

Create an App:

To the project, create a Django app by running one of the commands below.

(venv) $ ./ startapp shop_app


(venv) $ django-admin startapp shop_app

Add the created app to the INSTALLED_APPS config within the django_docker_project/ file for the django_docker_project to reorganize it. Add the full app name.


Set the URL route for the shop app at the project level.


Create a view shopp_app/ which will respond with a string “Welcome to the Django”.


Finally, create a file within the shop_app app and link it to index view.


At this point, when you start the server and visit: , in your favorite browser, you should see a result:

“Welcome to the Django!”, which confirms that everything is set up correctly.

Now create a requirements.txt file at the root of your project folder and run the following command:

(venv)$ touch requirements.txt(venv)$ pip freeze > requirements.txt

In the end, the folder structure should look something like this:

Dockerizing our Project.

Important notes:

  • A Dockerfile is a list of instructions required to build a Docker Image.
  • When the Dockerfile is run by the docker engine(or simply docker), a docker image gets built and possibly run.
  • A running instance of the docker image is called a Docker container
  • A Dockerfile is read from top-to-bottom during the image creation.
  • A Dockerfile must begin with a FROM command which lets docker import a base image on which the constructed image is based upon, in this case, the Python image.
  • The docker-compose file is used to automate docker commands and helps to control how the container is run.


The comments clearly explain what is going on in the Dockerfile

Add the above file to the root directory and build the image as shown below.

$ (venv) docker build .

The dot(.) above indicates, that the command applies to the Dockerfile in the current directory.

Running the image with docker-compose:

Again you should be able to access the message in your browser

Start by creating a docker-compose file

$ (venv) touch docker-compose.yml

And add the following content to the file:

The file above declares two services, web and db. The web services depend on the db service through the depends_on field; which means, db has to run first before web.

The Postgress password is set as “password”

To enable communication between the two, we need to install the database adapter and also change the database settings as shown below.

Start by running the image(s) in detached mode using the command:

$ (venv) docker-compose up -d

The -d flag indicates that we are running in detached mode.

When you visit the index/home page, nothing will show up; obviously, because the database settings and psycopg2 have not been configured yet.

In order to fix this issue, we need to install psycopg2.

Run the following command to install psycopg2.

$ (venv) docker-compose exec web python3 -m pip install psycopg2-binary==2.8.5

Also, head over to the django_docker_project/ file and change this section:

to this

The DB settings now do not point to SQLite; but instead, to the PostgreSQL DB server.

Next, run the below commands to migrate and create a superuser that will manage the PostgreSQL database.

$ docker-compose exec web python3 migrate
$ docker-compose exec web python3 createsuperuser

And follow the prompts. Head over to the admin dashboard by visiting and start performing some admin tasks :)

Notice that the commands above are not that different from the usual
python3 migrate and python3 createsuperuser commands except that in this case, we are running them inside a docker-container, while executing against each service by prefixing docker-compose exec [service_name] before the command(s).

Find the full project on GitHub: