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 | | 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).
   

   If you don't have reasons to do otherwise, use the same port number (e.g. 5005) everywhere: in your Remote debug configuration, in your Dockerfile, and in the container debug port - host port mapping.

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  to copy the option onto the clipboard. At a later time, you'll be able to paste it into your Dockerfile.

   

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.

   In this Dockerfile, you expose port 5005 in the container. You also instruct java to listen on that port waiting for debug requests.

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:  | 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:  | Edit '<ConfigurationName>'.
6. Select the Container tab, expand the Port bindings section, click  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.

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.

   In this Dockerfile, you expose port 5005 in the container. You also instruct java to listen on that port waiting for debug requests.

3. Put your app packaged in a JAR into the directory in which your Dockerfile is located. See the instructions.
4. Run your Dockerfile:  | 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:  | Edit '<ConfigurationName>'.
6. Select the Container tab, expand the Port bindings section, click  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 .

   

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.