Build and Debug Dockerized Java from IntelliJ IDEA Without Leaving the IDE

Problem: verifying Java behavior in a container without breaking IDE flow

Java services often behave differently once packaged into a container. Switching to a terminal to run docker build, docker compose up, and tailing logs splits attention and makes it easy to drift from the project source. The useful takeaway is to keep the build, run and debug loop inside IntelliJ IDEA so source navigation and code assistance stay available.

Thesis: IntelliJ IDEA’s built-in Docker integration lets you build images, start Compose stacks and attach a remote debugger from the IDE while the Docker CLI runs under the hood.

Prerequisites and connection check

The Docker plugin ships with IntelliJ IDEA 2023.2 or later. It requires a locally running Docker Engine 19.03 or newer and user access to the Docker socket. On Linux this usually means membership in the docker group or access to /var/run/docker.sock. On macOS and Windows Docker Desktop must be running.

Verify the setup in the IDE:

• Open Settings → Plugins and confirm Docker is enabled.
• Open the Services tool window at the bottom. A Docker node should appear. A connection error means the Engine is not reachable or permissions are missing.

Build an image from a Dockerfile in the editor

Place a Dockerfile in the project root. A minimal example for an executable jar is:

FROM eclipse-temurin:17-jdk
WORKDIR /app
COPY target/my-app.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java","-jar","app.jar"]

With the file open, use the editor context menu:

• Build Image. The IDE invokes docker build under the hood and streams output to the Build tool window.
• When the build finishes, the image appears under Docker → Images in Services.

Run as Container from the same menu creates a container from that image. Logs stream in the Services tool window and the container can be stopped from there. This keeps the run control in the IDE instead of a separate terminal.

Start a multi-service stack with Docker Compose

The integration supports docker-compose.yml. Opening the file adds a Compose node in Services.

From the gutter or context menu you can Start, Stop or Restart the whole stack with one click. Each service shows its logs in the same tool window, which reduces context switching when a Java app depends on Postgres or Redis.

Meaningful placeholders to check: image name and tag in the Compose file, port mappings, and volume mounts for local source. Incorrect mounts are a common risk when the container cannot find expected files.

Debug Java inside a container with remote debug

Remote debugging maps local source to container paths and forwards the debugger port.

Add a debug agent to the container environment. One option is to set JAVA_TOOL_OPTIONS in the Dockerfile or Compose file:

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

After the container is running, create a Run → Edit Configurations → Remote JVM Debug configuration in IntelliJ. Set the port to 5005 and map the project root to the container path, e.g., /app. Start the debug session and set breakpoints in local code. The IDE will suspend execution inside the container while source stays local.

Risk: exposing the debug port widens the attack surface. Use it only on local development engines and avoid publishing the port externally.

Trade-offs and limitations

Performance can degrade when the IDE streams large log volumes in real time. Limiting log size or using an external log viewer helps.

Advanced Docker features such as Swarm mode and Kubernetes integration are not covered by the built-in plugin and require third-party plugins or external tooling.

Connection errors are common when Docker Desktop is paused or the user lacks socket permissions. Checking Services → Docker → Connection settings is a practical way to verify.

Actionable closing

1. Confirm Docker Engine is running and the Docker plugin is enabled.
2. Add a Dockerfile and build the image from the editor context menu. Verify the image appears under Docker → Images.
3. Run the container and check logs appear in Services. Stop the container from the same window.
4. For Compose projects, start the stack from Services and confirm each service log is visible.
5. For debugging, add the JDWP agent, rebuild, create a Remote Debug configuration, and verify breakpoints are hit without leaving the IDE.

Keeping build, run and debug inside IntelliJ reduces command memorization and keeps source context intact while still using the standard Docker Engine.