Django debug guide of PyCharm on Docker environment

PyCharm is my favorite IDE

Photo by Faisal on Unsplash

I have been using JetBrains IDEs for several years for my work. Specifically, I love using products of JetBrains like IntelliJ (for Java), PyCharm (for Python), and PhpStorm (for PHP). Recently I have been working on python based projects and using PyCharm a lot in the docker environment.

Debugging Django which runs on Docker

Debugging is an essential process for developers. And debugging python applications including Django, Flask, or other simple applications is a very simple task on PyCharm if I run the application directly on my laptop.

However, when it comes to running a python application within docker, it becomes a little bit complicated. Because it becomes debugging code/framework which is running on a remote server. So, I wanted to summarize it for readers and to myself in the future.

Guide to building remote debugger

This guide is assumed there is already a Django application running on the docker-compose environment.

These are rough configuration steps:

1. Add python remote interpreter
2. Add Run/Debug Configuration and configure it runs on the Docker environment correctly

1. Add python remote interpreter

Open Preferences and go to Project: project-name , Python Interpreter . Then click on the right top gear button and select Add to add a new python interpreter.

Project preferences -> Python Interpreter

Then you need to select Docker Compose on the left side and make sure select web application container service on the Service .

2. Add Run/Debug Configuration

Open Run/Debug Configuration window from the top tool bar list. Then select Django Server configuration after clicking on the left right plus (+) button.

Add new Run/Debug Configuration

On the newly created Run/Debug Configuration window, you need to setup three main places.

Mainly, 3 places need to configured

Host: this should be 0.0.0.0 since we are testing application from our laptop to remotely running django on Docker.
Python interpreter: Select the remote python interpreter created above.
Path mappings: Need to map laptop’s Django project path to Docker’s local path.

Test debugging

Now it is ready to start debugging. Simply add breakpoint wherever we want, and then click on the Debug button would be enough for it.

Actually debugging as test

What problem I have struggled

There are good articles for the guide. However, whenever I try them I was facing problems, and the problem I have worked for a long time is about using CMDinstead of ENTRYPOINT inside the Dockerfile and docker-compose files. When I try to run the docker application from the PyCharm, it was showing this error message.

/usr/local/bin/docker-compose -f /Users/huchka/Developer/blog/djangorestframework/docker-compose.yml -f /Users/huchka/Library/Caches/JetBrains/PyCharm2021.3/tmp/docker-compose.override.1545.yml up --exit-code-from webapp_django --abort-on-container-exit webapp_django
djangorestframework_mysqldatabase_1 is up-to-date
Recreating djangorestframework_webapp_django_1 ... 
Attaching to djangorestframework_webapp_django_1
webapp_django_1  | usage: manage.py runserver [-h] [--ipv6] [--nothreading] [--noreload]
webapp_django_1  |                            [--nostatic] [--insecure] [--version]
webapp_django_1  |                            [--settings SETTINGS] [--pythonpath PYTHONPATH]
webapp_django_1  |                            [--no-color] [--force-color] [--skip-checks]
webapp_django_1  |                            [addrport]
webapp_django_1  | manage.py runserver: error: unrecognized arguments: python -u /code/manage.py runserver 0.0.0.0:8000
djangorestframework_webapp_django_1 exited with code 2
Aborting on container exit...
ERROR: 2

My Dockerfile for the Django web application was ending with

ENTRYPOINT ["python", "manage.py", "runserver", "0.0.0.0:8000"]

and when I changed it to CMD it worked. PyCharm allows us to debug on the docker-compose environment by creating a temporary docker-compose file to override. If you look closely to the command executed from the error message (first line), you can look at the overriding docker-compose file. I have looked inside that docker-compose file and it was running CMD a command for the entrypoint.

Khureltulgas-MacBook-Pro:djangorestframework huchka$ cat /Users/huchka/Library/Caches/JetBrains/PyCharm2021.3/tmp/docker-compose.override.1545.yml
version: "3.4"
services:
  webapp_django:
    command:
    - "python"
    - "-u"
    - "/code/manage.py"
    - "runserver"
    - "0.0.0.0:8000"
    environment:
      PYTHONPATH: "/code:/opt/.pycharm_helpers/pycharm_matplotlib_backend:/opt/.pycharm_helpers/pycharm_display"
      DJANGO_SETTINGS_MODULE: "djangorestframework.settings"
      PYTHONUNBUFFERED: "1"
      PYTHONIOENCODING: "UTF-8"
      PYCHARM_HOSTED: "1"
      PYCHARM_DISPLAY_PORT: "63342"
    stdin_open: true
    volumes:
    - "/Users/huchka/Developer/blog/djangorestframework:/opt/project:rw"
    - "pycharm_helpers_PY-213.7172.26:/opt/.pycharm_helpers"
    working_dir: "/code"
volumes:
  pycharm_helpers_PY-213.7172.26: {}

Since any CMD command, which runs after ENTRYPOINT, becomes only an argument, this ENTRYPOINT need to be changed to CMD for working PyCharm debugging integration with Docker environment.

Summary

I have summarized the steps on how to build and configure Django debugging environment using PyCharm and Docker. This guide is focused on only this purpose so I did not talk deeply about how docker-compose or Dockerfile works. With this guide, I was finally able to debug my Django projects. And possibly I can make it work for any python projects.

My consideration

One thing I am a little bit considering is what happens if we want to debug a python project on M1, however, the docker environment is with Intel/AMD architecture. Because now there are lot of projects which has developers some are suing intel architecture laptop and ARM architecture (M1). I am one of the M1 developers.