IntelliJ IDEA 2017.2 Help

Debugging a Java app in a container

1. Create a Remote debug configuration

To debug an app in a container, you'll need a Remote debug configuration.

  1. To create such a configuration, click Run | Edit Configurations | /help/img/idea/2017.2/add.png | Remote.
  2. Specify:
    Port. The host port the debugger will use to connect to your app. This may be any unused port on your computer.
    Search sources using module's classpath. Select the module that contains the sources you are going to debug (e.g. set breakpoints within).
  3. Note the command-line option you should use to start Java in your container. Usually, this is
    -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
    What follows address= is the debug port.
    Use /help/img/idea/2017.2/copy.gif to copy the option onto the clipboard. At a later time, you'll be able to paste it into your Dockerfile.
    /help/img/idea/2017.2/88_DockerRemoteDebugConfig.png
  4. As for the rest of the settings, the defaults are all OK, and you shouldn't worry about them. Click OK.

2. Deploy and start the app

You can choose to deploy and then debug your app in the form of compiled classes. You can as well package your app in a JAR, and then deploy and debug that JAR.

2a. Deploy the app as compiled classes

  1. Create a Dockerfile and open it in the editor.
  2. The Dockerfile for deploying and starting a compiled app may look something like this:
    FROM openjdk:8 COPY . /tmp WORKDIR /tmp EXPOSE 5005 ENTRYPOINT ["java","-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005","com.mypackage.MyMainClass"]

    5005 is the debug port in the container. If necessary, specify a different port.

  3. Build the project (e.g. Build | Build Project) and then copy your compiled app into the folder in which your Dockerfile is located. Alternatively, specify the folder with your Dockerfile as your compilation output folder, and then build the project. See the instructions.
  4. Run your Dockerfile: /help/img/idea/2017.2/runTwoGreenArrows.png | Run on 'Docker'.

    Now we are going to map the container debug port onto a host port in the associated run configuration, and then rerun that configuration.

  5. Open the run configuration for editing: /help/img/idea/2017.2/runTwoGreenArrows.png | Edit '<ConfigurationName>'.
  6. Select the Container tab, expand the Port bindings section, click /help/img/idea/2017.2/add.png and specify:
    • Container port: The container debug port you have exposed in your Dockerfile (e.g. 5005).
    • Protocol: tcp
    • Host IP: 0.0.0.0
    • Host port: The host port to which the debugger will connect. This should be the same port as in your Remote debug configuration (e.g. 5005).
    /help/img/idea/2017.2/89_DockerDebugPortBindings.png
  7. Click Run.

Now you are ready to start your debug session.

2b. Deploy the app as a JAR

  1. Create a Dockerfile and open it in the editor.
  2. The Dockerfile for deploying and starting a JAR app may look something like this:
    FROM openjdk:8 RUN mkdir /var/my-app COPY my-app.jar /var/my-app WORKDIR /var/my-app EXPOSE 5005 ENTRYPOINT ["java","-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005","-jar","my-app.jar"]

    5005 is the debug port in the container. If necessary, specify a different port.

  3. Put your app packaged in a JAR into the directory in which your Dockerfile is located. See the instructions.
  4. Run your Dockerfile: /help/img/idea/2017.2/runTwoGreenArrows.png | Run on 'Docker'.

    Now we are going to map the container debug port onto a host port in the associated run configuration, and then rerun that configuration.

  5. Open the run configuration for editing: /help/img/idea/2017.2/runTwoGreenArrows.png | Edit '<ConfigurationName>'.
  6. Select the Container tab, expand the Port bindings section, click /help/img/idea/2017.2/add.png and specify:
    • Container port: The container debug port you have exposed in your Dockerfile (e.g. 5005).
    • Protocol: tcp
    • Host IP: 0.0.0.0
    • Host port: The host port to which the debugger will connect. This should be the same port as in your Remote debug configuration (e.g. 5005).
  7. Click Run.

Now you are ready to start your debug session.

3. Start a debug session

  1. Set a breakpoint or a number of breakpoints in your code. For instructions, see Using Breakpoints.
  2. Run your Remote debug configuration: select it in the run configuration selector and click /help/img/idea/2017.2/debug.png.
    /help/img/idea/2017.2/90_DockerDebuggerConnected.png

4. Hot-swap changed classes

When debugging your app, you can make changes to your code and reload (hot-swap) changed classes. To do that, use Run | Reload Changed Classes.

See Also

Languages, Frameworks and Technologies:

Tutorials and Examples:

Last modified: 18 August 2017