Debugging Django application with Docker Compose: No debug option or connection issues

Problem

When attempting to debug a Django application using a Docker Compose configuration in PyCharm, the debug option is not available when using the Docker Compose type configuration. Additionally, when using a Django Server Run/Debug configuration with a Docker Compose interpreter, not all containers are started, and there is a traceback indicating that the container cannot connect back to the IDE (socket.gaierror: [Errno -2] Name or service not known).

Cause

1. Docker Compose start behavior: PyCharm does not recognize all needed services as dependencies for the main application container when starting the stack.
2. Network resolution issue: Using Docker Engine under WSL2 (without Docker Desktop) results in the hostname host.docker.internal being unavailable, which leads to connection issues for the debugger.

Resolution

Step 1: Configure Docker Compose Run/Debug Configuration

1. Create a Docker Compose run configuration in PyCharm.
2. Explicitly select all required services and profiles in the configuration.
3. Set the configuration to run detached (Attach to: None), so it mimics docker compose up -d behavior.
4. Add this Docker Compose run configuration as a Before launch step for your Django Server Debug configuration. Alternatively, use a Compound configuration.

This ensures that the entire stack, including dependencies, is already running when the debugger starts.

Step 2: Resolve Networking Issue

For systems using Docker Engine under WSL2:

1. Locate the Host IP Address
   Run the following command within WSL2 to obtain the Windows host IP address:

   grep -m1 nameserver /etc/resolv.conf | awk '{print $2}'
   

2. Update the Docker Compose File
   Add a host.docker.internal entry under the extra_hosts key of the service to be debugged (e.g., ccc-app):

   services:
     ccc-app:
       extra_hosts:
         - "host.docker.internal:<windows_host_ip>"
   

   Note: Replace <windows_host_ip> with the IP address retrieved in the previous step.

3. Keep in Mind: The WSL2 IP address may change after restarting, so this configuration may require periodic updates.

4. Check for Firewall Issues
   Ensure that PyCharm (and its Java runtime) is allowed through the Windows Firewall for private networks. Add appropriate permissions if needed.

Alternative Solution

Installing Docker Desktop can simplify the setup by providing built-in support for host.docker.internal, eliminating the need to manually configure the host mapping.

Following these steps should enable debugging for Docker Compose-based Django applications in PyCharm. If further assistance is required, contact JetBrains Support.