Setting up a basic Python Django project with Poetry and Docker compose

I’ve been using Poetry a few times on some of my sample projects for managing my python dependancies and I must say I am a big fan of it. Maybe it’s just the Javascript developer seeing the similarities to npm but with the ability to manage and create your python dependancies in such an easy and straight forward manner I will continue to use it.

Pair it with docker and you have an easy to create and replicable development environment.

Defining the Docker Compose components

  1. Create an empty project directory
  2. Create a new file called Dockerfile in this directory
    • the Dockerfile defines an applications container setup and commands that configure the virtual image.
  3. Add the following to your Dockerfile
FROM python:3.10-alpine
RUN apk update && apk upgrade
RUN apk add --no-cache --virtual .build-deps \
ca-certificates gcc postgresql-dev linux-headers musl-dev \
libffi-dev jpeg-dev zlib-dev
WORKDIR /usr/src/app
COPY poetry.lock pyproject.toml /usr/src/app/
RUN pip3 install poetry
RUN poetry config virtualenvs.create false
RUN poetry install -n --no-ansi

this docker files selects a python 3 image based on alpine linux.

the apk lines ensure the linux libraries are up to date and the needed dependancies are installed for django

the last 4 lines configure poetry in your Docker container. the last two lines configure poetry to run against the global python environment, since we are running in a self contained Docker environment this is fine, but not recommened on a local poetry install.

4. Configure Docker Compose

Create a docker-compose.yml file in the root of your project directory

version: "3.9"
    image: postgres
      - ./data/db:/var/lib/postgresql/data
      - POSTGRES_DB=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    build: .
    working_dir: /usr/src/app
    tty: true
      - .:/usr/src/app
      - "8800:8800"
      - POSTGRES_NAME=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - app_db

this will create a database docker container and an application docker container. It will map your local source container to your current directory.

now open up a terminal in your project directory and run the following

docker-compose build

docker compose up -d

now to initialize the project you can run the following

docker compose exec app_django bash

and this will open a bash terminal in your django container

Now initialize the project

poetry new –name AppName

This will create a directory AppSrc with the package AppName

Configuring Django

from the same docker container run

poetry add django && poetry add psycopg2

this will add the django dependencies to your python environement

Now to initialize the django application

django-admin startproject mysite

and this will create a mysite directory, if there’s any issues creating the project you can use the following django docs to troubleshoot:

and now you should be able to run python runserver and see your django server running.

you can now exit out of the docker container

Running in PyCharm

to debug this from pycharm, all you need to do is setup you python interpreter (file->setting->project->python interpreter) to use docker-compose, just make sure you choose the service that matches your app_django docker compose container name

Then add a new debug configuration for a Django project


Port: 8800

Python Interpreter: Same one you configured above

Env Variables: app_django.setttings (path to your django settings file in your project directory)

hit ok, and attempt to run the project and you should now have a django server running on localhost:8800

Leave a Reply

Your email address will not be published.