Docker Debugging: How to Do it Right?

Docker is a powerful tool for containerizing applications, but it can also present unique challenges when things don't go as planned. From unexpected behaviors to performance issues, troubleshooting Docker containers requires a systematic and thoughtful approach.?

In this guide, we are going to explore what Docker is, when and why it is used, and provide an overview of the tools that can be used for debugging Docker containers.?

Understanding Docker

Docker is software that allows you to create “mini virtual computers’’ for the application that you are developing. It’s virtualization software that allows you to create, manage, run, and deploy those applications almost anywhere.?

What is Virtualization?

Virtualization enables the hardware resources of a single computer to be divided into multiple virtual computers, called virtual machines (VMs). Docker uses “containers” as an abstraction at the app layer that packages code and dependencies together into those smaller virtual machines. Each container is a lightweight, stand-alone executable package containing everything needed to run your application: packages, modules, and all the tools from the system layer required for your code or application to run.

Imagine a micro PC just right for your code or application. You might not need the whole robust computer; you just need this specific part. For example, you have a web server, and you need to get a request from a user, do something, and send a response back. Here is where you need a small virtual computer that does just those things and nothing else.

When to Use Docker?

Modern projects are very complex, requiring numerous modules, packages, libraries, etc. Setting them up locally for every developer can be a complicated and lengthy process. Having a project that is stable and works uniformly across all team members’ PCs is beneficial because everyone is on the same page regarding the project setup. It also speeds up the onboarding process for newcomers.

For example, as a backend developer, I know Python. However, our front-end developer, familiar with NodeJS and front-end packages, might find it challenging to set up locally if they need to run the code. With a dockerized project, they can simply tell me: “Hey, I have this front-end container service. Can you run it?” I can run it with one command, without needing to understand its internals, and immediately see how the front end interacts with my backend.

For continuous integration and deployment (CI/CD), having a dockerized project is like having bricks—separate, atomic parts—that we can build and deploy. For clients, dockerized projects are valuable because they are atomic, shippable, and deployable, reducing development, maintenance, and deployment costs.

Docker should be used in the early stages of a project, usually even before building the project "skeleton."

Docker vs. Alternatives

Historically, virtualization was very resource-intensive. Classic VMs required significant system resources, and interactions with them were not always smooth. Docker is different because its virtualization includes only a thin "application" layer, reusing the base computer’s resources for everything else. This approach allows the creation of numerous containers with minimal resources and overhead. Docker’s popularity and wide adoption also make it a preferred choice.

Alternatives to Docker include:

• Podman: Another container engine that doesn’t rely on the Linux “daemon” to work.
• LXD: An open-source container engine that works only on Linux.
• Containerd: A high-level container runtime that runs “runc” under the hood.

All these options involve containment, making debugging tricky, which brings us to today’s topic.

The Importance of Debugging

Debugging is the process of finding and fixing errors or bugs in software source code. It provides insight into software or a sub-system. As a developer, it’s crucial to interact with the software being developed to understand its execution flow, variables, etc. Debugging is often the first step in identifying and fixing problems.

Debugging is important because bugs can be costly. Sometimes, bugs have severe consequences. For example, a software bug in an airplane system could lead to a crash and loss of lives. In another scenario, a bug in banking software could cause financial losses or a market crash.

Debugging Applications Inside Docker Containers

Many developers debug applications on their local or cloud PCs, where the process is usually straightforward. However, once an application is containerized, the challenge is accessing tools within the virtual container. Integrated Development Environments (IDEs) can help here. There are two primary approaches for debugging in Docker containers:

1. Using an IDE from JetBrains (Paid). In Python projects, we use PyCharm, which has support for setting up debugging configurations with Docker or docker-compose. The main drawback is its price. The dockerized debug feature is available only in PyCharm professional edition.
2. Using the VSCode IDE (Free): With its “Remote” extensions, users can connect to various remote systems via ssh, wsl/wsl2, or inside a Docker container. The advantage is that it’s freeware. The drawback is that setting it up is more manual, and the learning curve is steeper.

Debugging with VSCode

The official VS Code documentation is here. Since the documentation can be tricky, I created a demo repository to show how to debug a Python application in Docker. You can try it out at github.com/dreamproit/docker-debug.?

Briefly, the steps are:

1. Install extensions for VSCode for Docker debugging.
2. Attach the IDE to the container.
3. Create a “launch.json” file with debug configurations.
4. Edit the “launch.json” file to add configurations for debugging your code.
5. Once the “launch.json” file is set up, you can run each configuration, place breakpoints in key locations in the code to stop execution, and investigate the results. From this point on, the debugging process is essentially equivalent to debugging locally, outside the container.

Written by Andrii Kovalov