How to Setup Headless Dev Environment with Django and Docker

In this tutorial, I’ll go through how you can make a powerful development environment with Django and Docker. The inspiration for this tutorial came when I had a project with my friend and we divided the work so that I did the back-end services and my friend was responsible for all the action in front-end. My goal was to create a dev environment for effective back-end development without any hassle with deployments or anything else. My setup was rather simple, I used Django as a back-end framework and selected PostgreSQL for the database. If you want to skip the tutorial part, you can find the link for the boilerplate template at the bottom and jump straight to the code.

1. Make sure you have the Docker and git installed(if you use the provided template)

You can get the Docker from Official Docker pages and git from Official Git pages.

2. Start by creating a python environment

Create new directory for your project and navigate to it. After this let’s create new python environment. Creating a python environment with Python 3 is as easy as running python3 -m venv <venv_name> command. This will create a separate environment for our project where we can install our dependencies without affecting anything else on our system.

3. Create requirements file

Let’s create our requirements.txtfile to easy install our Python dependencies. Create new file called requirements.txt in the root project directory and add the following contents:

4. Activate python environment

To activate the environment run the following command in the project directory:
source <venv_name>/bin/activate

To deactivate the venv you can run deactivate but don’t run this yet!

5. Install all the dependencies

Install all dependencies defined in requirements.txt file by running pip install -r requirements.txt in the project directory where the requirements.txt is located

6. Create Dockerfile

Let’s create our Dockerfile to configure our docker image. Create new file called Dockerfile in the root project directory and add the following contents:

In this file we define how the image is going to be built when one is created. In short we install our dependencies and copy over all the project files to the container.

7. Create docker-compose.yml file

To keep the project easy to extend, let’s create a docker-compose.yml file to handle all our containers. Create a docker-compose.yml file in the root of our project directory and add the following contents there:

I think here it wouldn’t hurt to explain a bit. In this docker-compose file we define a PostgreSQL container which is a database container and where it should store it’s volumes. All the places with ${} syntax will get filled by env variables from the .env file which we will create on step 11.

8. Start a new project

Now let’s initiate a new Django project by calling django-admin startproject <your_project_name> . . This will create new Django project in the current directory with the name that we provided. Now you should see something like this in your working directory:

Contents of the project directory

9. Change the settings file by adding the PostgreSQL connection

Django defaults to SQLite database when creating a new project. This is totally fine since it can handle some testing and light development but we want something more so let’s put our freshly created PostgreSQL database in to use.

Let’s start this by navigating to out Django project directory and editing the database settings. In the settings.py file find the DATABASES = ... and replace it with the following:

Database connection settings

To utilize the settings from .env file add the following to the top of the file under the first Path import:

Use env variables from .env file

10. Move the django_secret to .env file

To keep our settings.py file nice and clean let’s move the SECRET_KEY to the .env file. But before that we need to create one so make the .env named file in the project root directory with following contents:

Contents of the .env file

Now go again to the settings.py file and copy the line with SECRET_KEY = ... to the end of .env file and replace the line in settings.py withSECRET_KEY = env("SECRET_KEY") . Note when adding the SECRET_KEY remove all the white space from the line, especially around the equals sign.

11. Congratulations, your dev environment is now set! 🎉

Now we should be able to run docker-compose up -d which starts the PostgreSQL container and after waiting it to boot up run ./manage.py runserver to start the django server. After this you should be able to navigate to http://localhost:8000 and see the following page:

Successfully launched Django project

Now we have achieved a fully working Django installation with PostgreSQL Database on our local machine. After you confirm that everything works please go ahead and modify the .env file contents to suit you better.

At the beginning of the tutorial, I promised to provide a template for an easier setup. You can find it from django-project-template repository. With the template, you can speed up the process by running the setup.sh script which removes my .git folder and creates a new one for you, initializes new project with the given name and makes all the needed changes that are required in the initial setup. Now I just wish you happy hacking and if you have any proposals or changes, please feel free to open a PR 🙂