How to Configure WebStorm for Debugging Directus Extensions in a Dockerized Environment?

I'm attempting to set up run/debug configurations in WebStorm to debug Directus extensions. Directus is running inside a Docker container, which is managed by docker-compose.yml. Despite following the WebStorm documentation, I'm encountering errors when starting the debugger.

WebStorm Configuration for Directus Container:

Docker Image Configuration for Directus:

FROM directus/directus:10.13
USER root
RUN corepack enable \
  && corepack prepare pnpm@8.1.1 --activate \
  # Currently required, we'll probably address this in the base image in future release
  && chown node:node /directus 

RUN mkdir -p /directus/directus-config
RUN chown -R node:node /directus/directus-config

ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN pnpm install -g tsx

USER node
RUN pnpm install directus-extension-sync
RUN pnpm install directus-sync

Docker Compose Configuration for Directus:

  jp_backend:
    container_name: ${COMPOSE_PROJECT_NAME}_jp_backend
    user: ${UID}:${GID}
    build:
      context: ./
      dockerfile: docker/backend/Dockerfile
    env_file:
      - .env
    ports:
      - '${DOCKER_BACKEND_PORT}:8055'
    volumes:
      - ./directus/extensions:/directus/extensions
      - ./directus/directus-config:/directus/directus-config
      - ./directus/start.ts:/directus/start.ts
      - ./directus/start.js:/directus/start.js
      - './.env:/directus/.env:ro'
      - ./docker/backend/.bash_history:/home/node/.ash_history
    networks:
      - backend_network
      - traefik_network
    depends_on:
      - jp_database
    labels:
      - 'traefik.enable=true'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-backend.entrypoints=http'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-backend.rule=Host(`${COMPOSE_PROJECT_NAME}.backend.${DOMAIN}`)'
      - 'traefik.http.middlewares.${COMPOSE_PROJECT_NAME}-backend-https-redirect.redirectscheme.scheme=https'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-backend.middlewares=${COMPOSE_PROJECT_NAME}-backend-https-redirect'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-backend-secure.entrypoints=https'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-backend-secure.rule=Host(`${COMPOSE_PROJECT_NAME}.backend.${DOMAIN}`)'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-backend-secure.tls=true'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-backend-secure.tls.certresolver=http'
      - 'traefik.http.routers.${COMPOSE_PROJECT_NAME}-backend-secure.service=${COMPOSE_PROJECT_NAME}-backend'
      - 'traefik.http.services.${COMPOSE_PROJECT_NAME}-backend.loadbalancer.server.port=8055'
      - 'traefik.docker.network=traefik_network'

When I start debugging, I receive the following error:

tsx /directus/start.ts
WARN[0000] /home/happyhevia/JP/jobs-paragon-backend/docker-compose.yml: `version` is obsolete 
WARN[0000] /home/happyhevia/.cache/JetBrains/WebStorm2024.1/tmp/docker_compose/docker-compose.override.881.yml: `version` is obsolete 
[+] Running 2/0
 ✔ Container dev_jp_database  Running                                                                              0.0s 
 ✔ Container dev_jp_backend   Recreated                                                                            0.0s 
Attaching to dev_jp_backend
dev_jp_backend  | Debugger listening on ws://127.0.0.1:38727/ddbd5270-8cfe-4cd1-b203-8505e794968c
dev_jp_backend  | For help, see: https://nodejs.org/en/docs/inspector
dev_jp_backend  | [debugConnectionForwarder] Error connecting to inspector {"port":38727} Error: connect ECONNREFUSED ::1:38727
dev_jp_backend  |     at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1555:16) {
dev_jp_backend  |   errno: -111,
dev_jp_backend  |   code: 'ECONNREFUSED',
dev_jp_backend  |   syscall: 'connect',
dev_jp_backend  |   address: '::1',
dev_jp_backend  |   port: 38727
dev_jp_backend  | }

When running the same configuration without attempting to debug, everything functions correctly, and I can access the Directus dashboard as expected. This indicates that the setup is correct for running, but something is misconfigured or incompatible for debugging.

Attempts to Resolve the Issue:

Initiated a Node.js Inspection: I tried to start a Node.js inspection inside the container to identify the problem but didn't receive any clear insights.
Switched to Node.js from tsx: Using Node.js instead of tsx to run the start script did not resolve the issue.
Testing with a Different Node.js Image: I configured a similar run/debug setup using a Node.js Alpine v20 image, where the debug feature worked without issues. This suggests that there may be a specific issue with the Directus image or its configuration.
Reviewing Directus Image: I suspect there might be something in the Directus image preventing the debugger from connecting properly, but I'm not sure what specifically could be causing this issue.

I have spent the entire weekend trying to figure this out and would be extremely grateful for any insights or solutions. This is particularly frustrating as the setup appears correct and functions for regular operation, but fails during debugging.

Solution

The issue was with the port settings. WebStorm uses the JETBRAINS_NODE_BIND_HOST environment variable, which defaults to 127.0.0.1. Changing it to ::1 fixed the problem.

Here’s what to do:

Go to Run > Edit Configurations in WebStorm.
Select your configuration.
Add an environment variable: JETBRAINS_NODE_BIND_HOST with the value ::1.

Thanks to @LazyOne for the tip that led to this solution!