Node.js with Docker

You can quickly bootstrap your Node.js application with Docker to run, debug, and profile it from WebStorm. The IDE will take care of the initial configuration by automatically creating a new Dockerfile, building and running an image, syncing your source code, and installing npm dependencies in the container.

You can find some examples at Quick Tour of WebStorm and Docker.

Before you start

Make sure the Node.js, Node.js Remote Interpreter, and Docker plugins are enabled on the Settings/Preferences | Plugins page, tab Installed, see Managing plugins for details.
Download, install, and configure Docker as described in Docker

Create a Node.js run/debug configuration

From the main menu, choose Run | Edit Configuration, then in the Edit Configurations dialog, click on the toolbar and select Node.js from the list. The Run/Debug Configuration: Node.js dialog opens.
In the JavaScript File field, specify the path to the main file of the application that starts it (for example, bin/www for Express applications).
If necessary, specify some optional settings as described in Running and debugging Node.js applications.

Specify a Node.js interpreter

Select one of the configured Node.js interpreters of the type Remote Interpreter - Docker from the Node interpreter list or configure a new one.

In the Run/Debug Configuration: Node.js dialog, click next to the Node interpreter field.
In the Node.js Interpreters dialog that opens with a list of all the currently configured interpreters, click on the toolbar. In the dialog that opens, choose Add Remote from the context menu.
In the Configure Node.js Remote Interpreter dialog that opens, select the Docker option.
1. In the Server field, specify the Docker configuration to use, see Configure the Docker daemon connection settings for details. Select a configuration from the list or click New... and create a new configuration on the Docker page that opens.
2. In the Image name field, specify the base Docker image to use. Choose one of the previously downloaded or your custom images from the list or type the image name manually, for example, node:argon or mhart/alpine-node. When you later launch the run configuration, Docker will search for the specified image on your machine. If the search fails, the image will be downloaded from the repository on the Docker Registry page. It is recommended that you use the Official Node.js Docker images.
3. The Node.js interpreter path field shows the location of the default Node.js interpreter from the specified image.
4. When you click OK, WebStorm closes the Configure Node.js Remote Interpreter dialog and brings you to the Node.js Interpreters dialog where the new interpreter configuration is added to the list. Click OK to return to the run configuration.

Specify the Docker container settings

Click next to the Edit Docker Container Settings field and specify the settings in the Edit Docker Container Settings dialog that opens.
Alternatively, select the Auto configure checkbox to do it automatically. Learn more about the Auto configure mode at Quick Tour of WebStorm and Docker: What Happens On Each Run.

Even with automatic configuration, you still need to bind the port on which your application is running with the port of the container. Those exposed ports are available on the Docker host’s IP address (by default 192.168.99.100). Such binding is required when you debug the client side of a Express application. In this case, you need to open the browser from your computer and access the application at the container host through the port specified in the application.

Configure port bindings

Click in the Docker Container Settings field and expand the Port bindings area in the Edit Docker Container Settings dialog that opens.
Click and in the Port bindings dialog that opens, map the ports as follows:
- In the Container port field, type the port specified in your application.
- In the Host port field, type the port through which you want to open the application in the browser from your computer.
- In the Host IP field, type the IP address of the Docker's host, the default IP is 192.168.99.100. The host is specified in the API URL field on the Docker page of the Settings / Preferences dialog.
- Click OK to return to the Edit Docker Container Settings dialog where the new port mapping is added to the list.
Click OK to return to the Run/Debug Configuration: Node.js dialog.

Run your application

Create a Node.js configuration as described above.
From the Select run/debug configuration list on the toolbar, select the newly created Node.js configuration.
Click to the Select run/debug configuration list.

Start debugging

Set the breakpoints in the Node.js code as necessary.
Create a Node.js configuration as described above, select it from the Select run/debug configuration list on the toolbar, and click next to the list.
Proceed as when starting the debugger together with a Node.js application.

Using a remote Node.js interpreter in a Docker container with a Docker Compose definition

With Docker Compose, you can run a Node.js server and your application code as separate services. Each service can be scaled by adding more containers if necessary. This enables you to perform efficient development and testing in a dynamic environment that is similar to production one.

Configuring mappings

When you debug an application with a remote Node.js interpreter, the debugger tells WebStorm the name of the currently processed file and the number of the line to be processed. WebStorm opens the local copy of this file and indicates the line with the provided number. This behaviour is enabled by specifying correspondence between files and folders on the server and their local copies. This correspondence is called mapping, it is set in the debug configuration.

From the main menu, choose Run | Edit Configurations. In the Edit Configuration dialog that opens, click on the toolbar and choose Node.js from the context menu.
In the Run/Debug Configuration: Node.js dialog that opens, choose the required remote interpreter from the Node interpreter list.
Click next to the Path Mappings field. The Edit Project Path Mappings Dialog that opens shows the path mappings retrieved from the deployment configuration. These mappings are read-only.
- To add a custom mapping, click and specify the path in the project and the corresponding path on the remote runtime environment in the Local Path and Remote Path fields respectively. Type the paths manually or click and select the relevant files or folders in the dialog that opens.
- To remove a custom mapping, select it in the list and click .

Last modified: 20 July 2021