IntelliJ IDEA Docker Integration: Complete Guide

What is IntelliJ IDEA Docker Integration?

IntelliJ IDEA Docker integration is a built‑in feature that connects your IDE directly to a Docker daemon, enabling you to manage containers, images, networks, and volumes without leaving the editor. It turns Docker into a seamless part of your development workflow by providing visual editors, code completion, run/debug configurations, and remote container access—all within the same tool you use for coding.

Why It Matters

Modern applications rely heavily on containerization for consistent development, testing, and deployment environments. The integration eliminates context switching between the IDE and the terminal or a separate Docker GUI. You gain:

• Faster feedback loops – run, debug, and rebuild containers directly from the IDE.
• Simplified debugging – attach the debugger to a process running inside a container as easily as a local application.
• Docker Compose support – orchestrate multi‑service architectures with the same IntelliJ run configurations.
• Context‑aware assistance – Dockerfile syntax highlighting, inspections, and completions help you write correct images faster.

How to Use It

Below you’ll find a step‑by‑step walkthrough covering setup, Dockerfile editing, run configurations, Docker Compose, debugging, and container management.

Prerequisites

• IntelliJ IDEA Ultimate 2023.2 or newer (Docker integration is available in Ultimate edition).
• Docker Engine running locally or a remote Docker daemon accessible via TCP.
• The Docker plugin enabled (it ships bundled, but verify it’s active under Settings > Plugins).

Configuring Docker Connection

Open Settings (Ctrl+Alt+S) → Build, Execution, Deployment > Docker. Click the + button to add a new Docker configuration. Choose the connection type:

• Local socket – for Docker running on your machine (default Unix socket /var/run/docker.sock on Linux/macOS, or tcp://127.0.0.1:2375 on Windows with exposed daemon).
• TCP socket – connect to a remote Docker Engine, for example inside a VM or a cloud instance.
• Docker for Mac/Windows – automatically detected when the desktop app is installed.

Once added, IntelliJ verifies the connection and displays the Docker tool window (View > Tool Windows > Docker). You’ll see all images, containers, volumes, and networks.

Working with Dockerfiles

Create a new file named Dockerfile in your project. IntelliJ provides full language support: syntax highlighting, inspections, and Ctrl+Space completion for Docker instructions. For example:

FROM eclipse-temurin:17-jre-alpine
LABEL maintainer="team@example.com"
COPY target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

You can use the Run gutter icon next to FROM to build the image and run a container immediately. Right‑click inside the file and select Create Dockerfile Run Configuration to save a reusable configuration.

Running Containers via Run Configurations

IntelliJ allows you to define Docker run configurations that build an image, create a container, and optionally start it. This is similar to a regular application run configuration but operates entirely through Docker.

To create one:

• Go to Run > Edit Configurations.
• Click + and select Docker > Dockerfile.
• Give it a name, select the Docker connection, and specify the Dockerfile path and Image tag.
• Under Container, you can set port bindings, environment variables, volume mounts, and entrypoint overrides.

Example configuration for a Spring Boot application:

# Run Configuration settings (visual editor fields):
Name: WebApp Docker
Dockerfile: ./Dockerfile
Image tag: myapp:latest
Container:
  Ports: 8080:8080
  Environment variables: SPRING_PROFILES_ACTIVE=docker
  Volume mounts: ./logs:/app/logs

Now you can run and stop this configuration like any other—Shift+F10 (or ⌃R on macOS) to run, Shift+F9 to debug.

Using Docker Compose

For multi‑container applications, IntelliJ reads docker-compose.yml files natively. Place a Compose file in the project root and the IDE will display a Docker Compose section in the Docker tool window. You can:

• Start all services with a single click.
• View logs of each container in dedicated tabs.
• Open a terminal into any running container.
• Attach a debugger to a service defined in Compose.

Sample docker-compose.yml:

version: '3.8'
services:
  api:
    build: .
    ports:
      - "8080:8080"
    environment:
      DB_URL: jdbc:postgresql://db:5432/appdb
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

To run, open the Services tool window (usually nested in Docker), select the Compose project, and press the play button. IntelliJ automatically builds images that need building, brings up the stack, and shows container status.

Debugging Applications Inside Containers

Debugging a containerized Java application works transparently with the Docker run configuration. When you use Run > Debug (Shift+F9), IntelliJ performs these steps automatically:

• Builds the image (if configured).
• Creates a container with the Java debug agent enabled, exposing the debug port.
• Connects the IDE debugger to that port once the container starts.

There’s no need to manually add -agentlib:jdwp arguments—the integration handles it. However, if you’re using a custom entrypoint, you can pass the agent options explicitly:

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

Then set the container’s port mapping to include 5005:5005. In the run configuration, under Container → Debug, specify the debug port. IntelliJ will attach automatically when you choose Debug.

Remote Debugging of Already Running Containers

Sometimes you need to debug a container that was started outside IntelliJ (e.g., via docker‑compose from the terminal). In the Docker tool window, right‑click on any running container and choose Attach Debugger. IntelliJ will scan for Java debug ports and propose a connection. You can also manually specify the host and port if the container exposes a JDWP port.

Container Management

The Docker tool window provides full lifecycle management:

• Images – pull, delete, tag, inspect layers.
• Containers – start, stop, pause, delete, view logs, open terminal, commit changes to a new image.
• Volumes & Networks – prune, inspect, remove.

You can also drag‑and‑drop a running container’s log into the editor for analysis, or use the integrated terminal to execute shell commands inside the container.

Best Practices

• Keep Docker configurations version‑controlled – store Dockerfile, docker-compose.yml, and .idea/runConfigurations/*.xml (the latter is shareable via VCS) so the whole team benefits from reproducible run setups.
• Use profiles in Docker Compose – define a docker-compose.dev.yml override that binds source volumes for hot‑reload, while the production Compose stays lean.
• Prefer Docker run configurations over terminal commands – they integrate with the build process, provide environment consistency, and enable one‑click debugging.
• Tag images meaningfully – use tags like app:dev-<git-branch> to avoid confusion when multiple versions exist locally.
• Clean up regularly – use the Docker tool window’s prune actions to remove dangling images and unused volumes, preventing disk bloat.
• Combine with Kubernetes when needed – IntelliJ Ultimate also supports Kubernetes; you can transition seamlessly from Docker Compose to Minikube or a cloud cluster, using similar run configurations.

Conclusion

IntelliJ IDEA Docker integration transforms containerized development from a separate command‑line chore into an integral part of the coding experience. By centralizing Docker operations inside the IDE, it accelerates the edit‑build‑debug cycle, simplifies multi‑service orchestration, and makes debugging containers feel native. Whether you’re building microservices, deploying a database‑backed web app, or experimenting with new technologies, the Docker integration reduces friction and helps you stay in flow. Start by connecting your Docker daemon, authoring a Dockerfile, and creating your first run configuration—you’ll quickly see how much smoother container development can be.