Docker Compose — Debugging with Compose

1 minute read

Configure your Compose stack to support step-through debugging with your IDE.

Node.js Debugging

services:
  api:
    build: ./api
    volumes:
      - ./api:/app
      - /app/node_modules
    command: node --inspect=0.0.0.0:9229 server.js
    ports:
      - "3000:3000"
      - "9229:9229"       # Debug port

VS Code launch.json

{
  "type": "node",
  "request": "attach",
  "name": "Docker: Attach to Node",
  "remoteRoot": "/app",
  "localRoot": "${workspaceFolder}/api",
  "port": 9229,
  "restart": true
}

Python Debugging

services:
  api:
    build: ./api
    volumes:
      - ./api:/app
    command: python -m debugpy --listen 0.0.0.0:5678 --wait-for-client app.py
    ports:
      - "5000:5000"
      - "5678:5678"       # Debug port

VS Code launch.json

{
  "type": "python",
  "request": "attach",
  "name": "Docker: Attach to Python",
  "connect": { "host": "localhost", "port": 5678 },
  "pathMappings": [{
    "localRoot": "${workspaceFolder}/api",
    "remoteRoot": "/app"
  }]
}

Java Debugging

services:
  api:
    build: ./api
    ports:
      - "8080:8080"
      - "5005:5005"       # Debug port
    environment:
      JAVA_TOOL_OPTIONS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"

Debug Profile Pattern

Keep debug config separate using profiles:

services:
  api:
    build: ./api
    ports:
      - "3000:3000"

  api-debug:
    build: ./api
    command: node --inspect=0.0.0.0:9229 server.js
    ports:
      - "3000:3000"
      - "9229:9229"
    volumes:
      - ./api:/app
    profiles: [debug]

docker compose --profile debug up api-debug

Summary

Language Debug Port Command Flag
Node.js 9229 --inspect=0.0.0.0:9229
Python 5678 -m debugpy --listen 0.0.0.0:5678
Java 5005 -agentlib:jdwp=...address=*:5005
Go (Delve) 2345 dlv debug --headless --listen=:2345

Quick Reference

Item Detail
Node.js –inspect=0.0.0.0:9229
Python -m debugpy –listen 0.0.0.0:5678
Java JAVA_TOOL_OPTIONS with jdwp
Pattern Expose debug port + volume mount
Profile Use profiles: [debug] for separation

You may also enjoy