Automatically attach remote debugger to Docker instance

Question

How can I automatically attach a remote debugger to a running Java application in a Docker instance?

Answer

To automate the process of attaching your debugger to the JVM running within a Dockerized environment, you can configure IntelliJ IDEA with specific settings:

1. Check the remote debugging documentation provided by IntelliJ IDEA at Debugging in Docker containers to set up an efficient environment for debugging Dockerized Java applications.

2. Adjust your Docker configuration to expose the debug port (for example, 5005) and start the JVM with the JDWP agent options (see Remote debug tutorial):

   -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
   

   Use suspend=n so the JVM starts immediately without waiting for the debugger; set suspend=y if you need to debug application startup.

3. Pass those options automatically using one of the following approaches:

   Dockerfile — add the agent to your ENTRYPOINT or CMD:

   ENTRYPOINT ["java", "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005", "-jar", "app.jar"]
   EXPOSE 5005
   

   Or use the JAVA_TOOL_OPTIONS environment variable, which is picked up by any JVM process regardless of how it is launched:

   ENV JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
   EXPOSE 5005
   

   Docker Compose — set JAVA_TOOL_OPTIONS in the service definition:

   services:
     app:
       environment:
         - JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
       ports:
         - "5005:5005"
   

   Once the container is running, create a Remote JVM Debug run configuration in IntelliJ IDEA (host: localhost, port: 5005) and start it — the IDE will attach to the JVM automatically.

You may also choose Docker Compose, check this link: https://www.jetbrains.com/help/idea/run-and-debug-a-spring-boot-application-using-docker-compose.html#debug_app