Prepare an image for debugging

Prepare the image for VS Code debugging

The complete rebuild-based workflow changes package.json and the Dockerfile, then adds .vscode/launch.json for VS Code. Node Inspector is the debugging interface built into Node.js; it permits a debugger to pause execution, inspect variables, and control stepping.

Add the debug command to package.json

Current configuration:

{
  "scripts": {
    "start": "node <ENTRYPOINT>"
  }
}

Updated configuration with a separate Node Inspector command:

{
  "scripts": {
    "start": "node <ENTRYPOINT>",
    "debug": "node --inspect=0.0.0.0:9229 <ENTRYPOINT>"
  }
}

Start the debug command from the Dockerfile

Current configuration containing the CMD line to replace:

EXPOSE <CONTAINER_APP_PORT>
CMD ["npm", "start"]

Updated configuration with EXPOSE 9229 added and the existing CMD ["npm", "start"] line replaced by CMD ["npm", "run", "debug"]:

EXPOSE <CONTAINER_APP_PORT>
EXPOSE 9229
CMD ["npm", "run", "debug"]

Only the new CMD line remains in the Dockerfile. EXPOSE 9229 records the intended inspector port as image metadata; it does not publish that port on the host. npm run debug starts the application with --inspect=0.0.0.0:9229, which makes Node Inspector listen on every container network interface whenever the rebuilt image runs.

Add the VS Code attachment configuration

The documented Dockerfile uses /app as its working directory and keeps src/ as a subdirectory:

WORKDIR /app
COPY ./src ./src

For this source layout, .vscode/launch.json is added exactly as shown. No values require replacement:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to containerized Node.js",
      "type": "node",
      "request": "attach",
      "address": "127.0.0.1",
      "port": 9229,
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/app",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

localRoot identifies the source tree opened on the host. ${workspaceFolder} is replaced by the current VS Code workspace directory. remoteRoot identifies the same source tree inside the container. VS Code joins the remainder of each file path to these two roots, producing this mapping:

${workspaceFolder}/src/index.js -> /app/src/index.js

The modified image is rebuilt and started through the regular Container Tools flow. Docker: Attach to Node under Run and Debug then connects VS Code to the inspector at 127.0.0.1:9229.

A hollow breakpoint marked as unbound means that the debugger has not matched the local file and line to a script loaded by the Node.js process. For the documented layout, ${workspaceFolder}/src/index.js must refer to the same file as /app/src/index.js. A different WORKDIR, COPY destination, or workspace root requires corresponding localRoot and remoteRoot values.

_{Find by: rebuild debug image, package json debug script, dockerfile inspect, node inspector, inspect 9229, launch json, expose port}