How to Debug Django Backend in Docker compose

When working with Docker Compose to deploy applications, it’s not uncommon to run into mysterious issues. Recently, while deploying a ReactJS frontend, Django backend, and PostgreSQL database using Docker Compose, I faced an issue that seemed simple at first but required a bit of digging to resolve. Here’s a detailed account of the problem, the debugging process, and the eventual fix.

The Setup

The goal was straightforward: use Docker Compose to spin up a ReactJS frontend, Django backend, and PostgreSQL database. The docker-compose.yml file was configured, Dockerfiles for each service were written, and the commands were as follows:

docker compose build
docker compose up -d

After executing these commands, all containers appeared to start successfully:

• Frontend: Running and accessible via the browser.
• Database: Running with no issues.
• Backend: Container status showed “Up,” and ports were exposed.

But despite the backend container being up and running, I couldn’t access the application via the browser. Instead, I was greeted with “Connection Refused.”

The Problem

At first glance, everything seemed fine:

• The backend container status was “Up” in Docker.
• The exposed ports in the docker-compose.yml were correctly mapped.
• Logs from the backend container showed no errors.

But the backend application wasn’t reachable at the exposed port. This raised several questions:

• Was the application actually running inside the container?
• Was the container listening on the correct port?
• Was the CMD instruction in the Dockerfile properly configured?

The Debugging Process

1. Manually Running the Backend Application

To rule out runtime issues, I accessed the backend container using:

docker exec -it <backend_container_id> bash

Inside the container, I manually started the Django application:

python manage.py runserver

To my surprise, the application started successfully and was listening on http://localhost:8000. This confirmed:

• The application itself was working fine.
• There was no issue with Django or Python configurations.

2. Investigating the Dockerfile

Since the application was running fine manually, the issue had to be with the way the container was configured. On reviewing the Dockerfile for the backend, I noticed this CMD instruction:

This was a red flag. Django was set up to listen on port 8000, but the CMD was attempting to start the application on 3000.

CMD ["python", "manage.py", "runserver", "0.0.0.0:3000"]

3. Fixing the Issue

To resolve this, I updated the CMD instruction in the Dockerfile to use the correct port:

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

This ensured that the backend application would start on the correct port.

Rebuilding and Redeploying

After making the change, I rebuilt the Docker images and redeployed the containers:

docker compose up --build
docker compose up -d

This time, the backend application started properly, and I was able to access it via the browser at the expected address.

Key Learnings

This debugging experience taught me a few important lessons:

1. Check Port Configurations: Ensure that the port specified in the CMD instruction matches the port your application is configured to listen on.
2. Debug Inside the Container: If logs don’t provide enough information, manually run commands inside the container to diagnose the issue.
3. Understand Dockerfile Instructions: A small misconfiguration in the Dockerfile can lead to larger runtime issues. Always double-check CMD and EXPOSE instructions.
4. Iterative Debugging: Debugging in a containerized environment requires patience and a methodical approach. Break down the problem step by step.

Conclusion

Containerized environments like Docker are powerful tools, but they require careful configuration. In this case, a simple port mismatch in the Dockerfile caused hours of debugging. However, by systematically diagnosing the issue, I was able to pinpoint the problem and fix it.

If you’ve faced similar challenges while working with Docker, I’d love to hear about your experiences in the comments. Let’s learn and grow together! 🚢💡

rjshk013@gmail.com

Meet Rajesh K, a seasoned DevOps professional with six years of experience in designing and executing sophisticated software development processes. Specializing in high-availability architecture and leading AWS cloud projects, Rajesh excels at deploying containerized applications using Terraform and is proficient in Kubernetes, Docker, Helm, and Ansible. Through his blog, he offers expert, practical guidance to empower tech professionals with the knowledge they need to excel in cloud and infrastructure automation.