WebStorm Docker Integration: Complete Guide

Introduction to WebStorm Docker Integration

WebStorm, JetBrains' powerful IDE for JavaScript and TypeScript development, ships with first-class Docker integration that lets you build, run, debug, and manage containers without ever leaving your editor. Instead of juggling terminal windows, SSH sessions, and configuration files scattered across your system, you can orchestrate your entire containerized workflow from a single, unified interface.

This integration is particularly valuable for modern web development, where applications routinely depend on databases, caches, message brokers, and other services that are tedious to install locally. With Docker support in WebStorm, you can spin up a complete development environment in seconds, share it with your team, and ensure that "it works on my machine" is no longer an excuse.

Why Docker Integration Matters in WebStorm

Before diving into configuration, it's worth understanding what problems this integration solves and why it has become a staple in professional development workflows.

Consistency Across Environments

By defining your environment as code, you eliminate the subtle differences between development, staging, and production. The same Dockerfile and docker-compose configuration that runs on your laptop can be deployed to a CI server or cloud provider with minimal modification.

Simplified Onboarding

New team members no longer need to spend hours installing Node.js versions, database drivers, and system dependencies. A single command — or a click in WebStorm — brings up the entire stack.

Isolation and Reproducibility

Each project gets its own isolated environment. You can run Node 18 for one project and Node 20 for another without version managers like nvm. Database versions, environment variables, and port mappings are all explicitly declared.

Seamless Debugging

WebStorm's Docker integration goes beyond running containers. You can attach the built-in debugger to a Node.js process running inside a container, set breakpoints, inspect variables, and step through code exactly as you would with a local process.

Prerequisites and Setup

Before configuring Docker in WebStorm, ensure you have the following installed and running on your system:

• WebStorm 2023.1 or later (earlier versions work but may have different UI)
• Docker Desktop on macOS or Windows, or Docker Engine on Linux
• A project with a Dockerfile or docker-compose.yml file

Connecting Docker to WebStorm

WebStorm needs to establish a connection to your Docker daemon. The process differs slightly depending on your operating system.

On macOS and Windows with Docker Desktop, the connection is automatic once Docker is running. On Linux, you may need to configure a TCP socket or Unix socket connection manually.

To add a Docker connection in WebStorm:

• Open Settings/Preferences (Cmd+, on macOS, Ctrl+Alt+S on Windows/Linux)
• Navigate to Build, Execution, Deployment → Docker
• Click the + button to add a new connection
• Select the appropriate connection type (Docker for Mac, Docker for Windows, TCP socket, or Unix socket)
• Verify the connection shows "Connected" in the status column

Once connected, a Docker tool window appears in the bottom panel, giving you a visual overview of all containers, images, networks, and volumes on your system.

Creating Your First Dockerfile

Let's start with a practical example. Suppose you have a Node.js Express application. Here's a production-ready Dockerfile that follows multi-stage build best practices:

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

COPY --from=builder /app/dist ./dist

ENV NODE_ENV=production
ENV PORT=3000

EXPOSE 3000

CMD ["node", "dist/index.js"]

This multi-stage build keeps your final image small by excluding devDependencies and source files. The builder stage compiles your TypeScript, and the production stage copies only the compiled output.

Running the Container from WebStorm

WebStorm lets you create reusable run configurations for Docker. Here's how to set one up:

• Right-click your Dockerfile in the project tree
• Select "Modify Run Configuration"
• Configure the image tag, container name, port bindings, and volume mappings
• Set environment variables if needed
• Click Run to build and start the container

Alternatively, you can define the run configuration in JSON format. WebStorm stores these in the .idea/runConfigurations/ directory, making them shareable via version control:

{
  "name": "Docker: Express App",
  "type": "docker-deploy",
  "serverName": "Docker",
  "dockerfile": {
    "dockerfilePath": "Dockerfile",
    "imageTag": "my-express-app:latest",
    "containerName": "express-app",
    "portBindings": [
      { "hostPort": "3000", "containerPort": "3000" }
    ],
    "volumeBindings": [
      { "hostPath": "./src", "containerPath": "/app/src" }
    ],
    "envVars": [
      { "name": "NODE_ENV", "value": "development" }
    ]
  }
}

Working with Docker Compose

For applications with multiple services — a web server, database, cache, etc. — Docker Compose is the standard tool. WebStorm provides excellent Compose support, including per-service run configurations and log aggregation.

Here's a typical docker-compose.yml for a full-stack application:

version: "3.9"

services:
  app:
    build:
      context: .
      target: development
    ports:
      - "3000:3000"
      - "9229:9229"
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://user:pass@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: myapp
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:

Running Compose Services in WebStorm

To run this Compose file from WebStorm, create a Docker Compose run configuration:

• Go to Run → Edit Configurations
• Click + and select "Docker Compose"
• Point the configuration file to your docker-compose.yml
• Optionally specify which services to start (e.g., just app and db)
• Click Run to bring up the entire stack

WebStorm aggregates logs from all services in a single tab, color-coded by service name. You can also click on individual services in the Docker tool window to see their isolated logs, inspect their state, or open a shell session inside the container.

Debugging Node.js Inside Containers

One of the most powerful features of WebStorm's Docker integration is the ability to debug applications running inside containers. This requires exposing the Node.js inspector port and configuring WebStorm to attach to it.

Enabling the Debugger in Your Container

Modify your development command to start Node.js with the inspector enabled. In your package.json:

{
  "scripts": {
    "dev": "nodemon --inspect=0.0.0.0:9229 src/index.ts",
    "dev:break": "nodemon --inspect-brk=0.0.0.0:9229 src/index.ts"
  }
}

The 0.0.0.0 binding is critical — by default, the inspector only listens on localhost, which is inaccessible from outside the container. Port 9229 is mapped to the host in the Compose file we defined earlier.

Creating an Attach Configuration in WebStorm

Once your container is running with the inspector exposed, create a debug configuration to attach to it:

• Go to Run → Edit Configurations
• Click + and select "Attach to Node.js/Chrome"
• Set the host to localhost and port to 9229
• Optionally configure remote root mapping so WebStorm knows which local files correspond to container paths
• Click Debug to attach

For automatic path mapping, add a folder mapping in the configuration: local path /Users/you/projects/myapp maps to remote path /app. This ensures breakpoints set in your local source files are correctly translated to the container's file system.

Using the Built-in Docker Compose Debug Configuration

WebStorm also offers a streamlined workflow that combines building, running, and debugging in one step. Create a "Docker Compose" run configuration, select your app service, and click the Debug icon instead of Run. WebStorm automatically modifies the Compose command to include the inspector flags and attaches the debugger when the container starts.

Managing Databases and Services

When you run a database container via Docker Compose, WebStorm's Database tool can connect to it directly. This eliminates the need for separate database client applications.

To connect to the PostgreSQL container from our earlier example:

• Open the Database tool window (View → Tool Windows → Database)
• Click + → Data Source → PostgreSQL
• Set Host to localhost, Port to 5432, Database to myapp, User to user, Password to pass
• Click Test Connection, then OK

You can now browse tables, write queries, and manage schemas directly in WebStorm. Any changes you make are reflected in the container immediately, making it ideal for iterative schema development.

Best Practices for Docker Development in WebStorm

Use .dockerignore Consistently

A .dockerignore file prevents unnecessary files from entering your build context, which speeds up builds and reduces image size. Here's a comprehensive example:

node_modules
npm-debug.log
.git
.gitignore
.env
.env.local
dist
coverage
.idea
.vscode
*.md
Dockerfile
docker-compose.yml
.dockerignore

Leverage Volume Caching for node_modules

The anonymous volume /app/node_modules in the Compose file above prevents your host's node_modules from overwriting the container's installed packages. This is a common pitfall that causes mysterious "module not found" errors when bind-mounting source code.

Use Multi-Stage Builds

Always separate your build and runtime stages. This keeps production images lean and reduces the attack surface. Alpine-based images are typically a good choice for Node.js applications, often resulting in images under 150MB.

Pin Image Versions Explicitly

Avoid using latest tags in production. Pin to specific versions like node:20.11-alpine to ensure reproducible builds. WebStorm will even warn you when newer versions are available, helping you stay current without breaking changes.

Share Run Configurations with Your Team

Store Docker run configurations in version control by keeping the .idea/runConfigurations/ directory in your repository. This ensures every developer on your team can run the project with identical settings. Use .idea/workspace.xml in .gitignore to avoid sharing personal preferences while keeping shared configurations.

Take Advantage of Hot Reloading

When bind-mounting source code in development, use a tool like nodemon or ts-node-dev for automatic restarts on file changes. Combined with WebStorm's live file watching, this creates a tight feedback loop where code changes are reflected almost instantly in the running container.

Use Health Checks for Dependency Ordering

The depends_on directive in Compose only waits for a container to start, not for the service inside it to be ready. Always define health checks for databases and other services that need time to initialize. WebStorm displays health status in the Docker tool window, making it easy to spot services that are stuck in an unhealthy state.

Conclusion

WebStorm's Docker integration transforms containerized development from a command-line chore into a seamless, visual experience. By combining intelligent run configurations, integrated debugging, database management, and log aggregation in a single IDE, it removes the friction that often accompanies Docker workflows. Whether you're building a simple Express API or a complex microservices architecture, the patterns and practices covered in this guide will help you develop faster, debug deeper, and collaborate more effectively with your team. Start with a basic Dockerfile, graduate to Compose for multi-service stacks, and leverage the debugger for production-quality insights — your future self will thank you for the investment in a reproducible, containerized development environment.