How to debug a Python and Django application inside a Docker container

The rollercoaster of emotions experienced while developing systems is something that anyone with even minimal exposure to this can strongly state. However, for those with significant experience across various projects and applications, building a system from scratch is often considered the dream situation.

The real nightmare arises when you need to maintain, support, or evolve an existing and running system – sometimes with thousands or millions of users. And the deepest layer of The Inferno of Dante in software development is when you have to debug the code to fix an issue.

I know that sometimes, especially when you’re just starting out, you rely on the simplest and most informal print() and its equivalents in other languages. No worries, our secret is safe here. However, we also know that for the most painful and tricky bugs, we need to use an efficient, powerful, and comprehensive debugging tool.

I have been required to analyze some performance issues in my work. A shallow investigation of function/class returns or time tracking with Grafana wasn’t enough to find the real problem in all the tangled code. So… let’s debug!

Debugging

In Python, we have PDB, a straightforward library for debugging our code. To use it, you simply need to install it using pip. For example:

pip install pdb 

Then add one line in the code you want to debug:

import pdb; pdb.set_trace()

This will be your breakpoint. Now, you can run your application again, and it will pause execution right after the line you just added. You can then step through your code, line by line and function by function, to find the issue you need to address.

With Docker

The setup above should suffice for a simple Python project with Django, Flask, or FastAPI. However, if you’ve reached this point and are running your application inside a Docker container, facing issues, I’ve been on the same road. Stay calm and simply follow these next few steps:

1 – Instead of the usual PDB, you should install the remote debugger. Run it inside your Docker container (or include the library in your dependencies manager):

pip install remote-pdb 

2 – In your docker-compose.yml file, add a new port to expose the PDB entrypoint:

...
services: your-app: ... ports: - 8000:8000 # already existing port of your application - 4444:4444 # NEW LINE TO EXPOSE PDB PORT ...
...

3 – Still in your docker-compose.yml file, add these two lines, to allow sending commands from outside Docker to your running container:

...
services: your-app: ... ports: - 8000:8000 - 4444:4444 stdin_open: true # THIS tty: true # AND THIS ...
...

4 – Finally, change the breakpoint line in your code to this one:

__import__("remote_pdb").set_trace(host='0.0.0.0', port=4444)

Now you can run your Docker image as well and connect with PDB debugger from port 4444, which we opened, using a simple telnet command in your favorite terminal:

telnet 0.0.0.0 4444

PDB Commands

To cleverly sail through the sea of your code, you’ll need to use the helpful commands provided by PDB. Let’s see some of them here:

I normally just use the commands step (s) and next (n). The difference between both is that step execute each line, even those inside a function that is called on the current one. And next only execute the lines inside the current function, waiting for the return of called functions.

Other two useful commands are return (r), that execute all the function until it returns, and continue (c), that execute everything until the next breakpoint.

Conclusion

I hope this content has been helpful to you. Through investigating a significant performance issue and reinforcing my learning while writing this text, I can guarantee that

“using the right tool for the right job”

is something we should never forget as software developers. It can elevate our careers to a more effective level and bring more joy to this rollercoaster ride.