Tips & Tricks

Quick Tour of WebStorm and Docker

Node.js developers are embracing Docker for repeatable builds, and WebStorm supports Docker-oriented workflows: Quickly bootstrap your Node.js app with a Dockerfile, then run and debug your app in Docker, from the WebStorm IDE.

Let’s take a look.

Note: WebStorm’s Docker support is for server-side Node.js applications. It isn’t aimed at client-side applications, e.g. Angular or React. Nor is it for tools like linters or test runners which need to interact with the editor.


  • Setup your local Docker environment
  • Create, run, and debug a local demo Express application
  • Connect to your Docker servers
  • Setup a remote Node.js interpreter based on Docker
  • Run your Express application in Docker, and connect from WebStorm’s REST client
  • Debug the Express application, in a Docker container


WebStorm manages the running of your code in Node.js, as well as debugging, profiling, testing, and more. Your run configuration specifies a path to your locally-installed Node.js interpreter – e.g. /usr/local/bin/node – and options that go with it.

WebStorm can also, though, manage remote interpreters. Meaning, your code is executed by a Node.js interpreter inside another environment, such as Vagrant or on an SSH-available server.

With WebStorm 2016.3, Docker is added to the list of remote interpreter options. Once configured, WebStorm will create a new container on each run, with the container bound to the project directory, then execute your project code in the Docker-based Node.js environment.

Docker Setup

Docker has become easy to download and install, across multiple platforms, and in multiple ways. For this article, we targeted macOS and used the standard Docker for Mac package, version 1.13.1 at the time of the writing. This version is after Docker’s switch away from Virtualbox, hallelujah to all our souls.

Hello Express

The purpose of this article isn’t to show developing Node.js applications, but rather, to show running a Node.js application in a container, then talking to it from the IDE. Therefore we’ll use a simple Express app saved in a hello_express.js file, with a single REST endpoint at root that returns ‘Hello World’:

Hello Express

With that file saved in our WebStorm project, we’ll run it with the local interpreter:

01 Run

We can connect to it using WebStorm’s built-in REST client:

02 Restful

During development, we can use WebStorm’s debugger:

03 Debug

Hello Docker Server

We want to talk to Docker servers, but first we need to tell WebStorm where they are located. Let’s start by adding a new Docker server. While we can do this in the dialog for editing a run/debug configuration, the line between interpreter/server/container can get kind of blurred. Plus, we need to see where WebStorm manages its list of Docker servers.

Visit Preferences -> Build, Execution, Deployment -> Docker and you’ll see the following screen:

04 Docker Preferences

As you can see, you have no Docker servers defined. As a note, this is an IDE preference, not a project preference, which means this is the list of Docker servers available in all of your WebStorm projects.

Click the  plus button to add a new Docker server. Change its Name: to Local Docker. Then, if you are on macOS or Linux, change the API URL: field to unix:///var/run/docker.sock:

05 Add Docker Server

Click OK to dismiss the preferences.

You will now see a new Docker tool window button has appeared, with the tool window opened to show your Local Docker server that you just configured:

Docker Tool WindowAdd Docker Remote Interpreter

If you have no servers configured, this tool icon disappears.

You can connect to the Docker server by clicking the  play icon. If Docker isn’t running, after a timeout period, you will get a “connection timed out” message saying the server couldn’t be reached at the API URL that you configured. If Docker is running, though, you will see a listing of Containers and Images:

06 Browse Docker

If you are completely new to Docker on your computer, you’ll see a grand total of…nothing. You’ve created no Docker containers and downloaded no Docker images. Good news: WebStorm does this work for you, and as we’ll see later, this tool window makes it easy to manage the basics of your Docker server.

We’re getting closer. We need a container and a Node.js interpreter inside of it. We’ll let WebStorm stitch that together with a Docker-based remote interpreter.

Hello Remote Interpreter

In our first step of this blog post, we wrote an Express application and made a run/debug configuration. That configuration used a local interpreter. Let’s edit that configuration, and have it instead use a remote interpreter – one running in a container on the Docker server we just connected.

First, go to Run -> Edit Configurations and select hello_express. At the far right of the line for Node interpreter: click the  browse icon to bring up the Node.js Interpreters dialog. Then click the plus sign and select Add remote... to add a new Remote interpreter:

07 Add Remote

You will now get a dialog Configure Node.js Remote Interpreter. Click the radio box for Docker and…here we have it, a chance to make a new, Docker-based remote Node.js interpreter:

Add Docker Remote Interpreter

As you can see, WebStorm defaults to Local Docker, the only Docker server that we have defined in the WebStorm IDE-wide preferences. We’ve never gotten any Docker “images” (used to make new containers) so WebStorm helpfully chooses a reasonable default. Click OK to add this new interpreter to the run/debug configuration, then OK again to close the Node.js Interpreters dialog.

And…we’re not there yet. We’ve defined:

  • A Docker server
  • A remote interpreter
  • The Docker image associated with that interpreter

This is enough for WebStorm and the Docker server to create (then destroy) a new container, based on the selected image, whenever you run your code.

But the Run/Debug configuration needs some extra information about this project: how to mount your project directory into the container, etc. Lots of Docker knobs to fiddle with, and WebStorm gives you a warning at the bottom about this:

Run Configuration Error Message

Click the Auto configure checkbox and WebStorm will make sane choices for configuration:

08 Auto Configure

Once you have checked auto configure, you can now click OK to save the changes to this run/debug configuration.

Finally, we can run it.


When you click play to run your hello_express.js app, it runs in Docker:

09 Running in Docker


  • Docker has never retrieved the node:latest Docker image, so WebStorm tells it to do so.
  • WebStorm creates a new image using node:latest as a base, then installs your project’s packages from package.json into a tmp folder for the image. This speeds up each run: the Docker image doesn’t need to re-fetch npm packages unless package.json changes.
  • With the image ready, WebStorm creates a container and runs your code in the container’s
  • Node.js interpreter, with your project mounted as /opt/project inside the container.
  • After the run is completed, the container is destroyed.

With this optimization, WebStorm can re-run your code quite quickly, despite destroying containers every time.

We now have an Express app running inside the container, listening on port 3000. But we can’t connect to it from the outside. We need to bind the container’s port to a port on the host.

Connecting to the Web Service

Port binding is a bit arcane. WebStorm helps by putting a nice UI on the configuration. Edit your run/debug configuration and click on the browse icon beside Docker container settings: to bring up the Edit Docker Container Settings dialog:

10 Docker Container Settings

Click the triangle to expand the Port bindings section, then click the plus button to add a new port binding, with the following values:

11 Port Bindings

Click OK to dismiss the port binding dialog, then OK to dismiss the container settings dialog, then OK again to dismiss the Run/Debug Configurations dialog.

Re-start your run window by clicking restart…don’t worry, it can’t take a bit to shut down the container when Express has the loop running.

Bring back your REST Client tool window and change the port from 3000 to 3001. Click the play icon to issue a request. You again get Hello World! as the output, but this time, it ran from inside the Docker container:

13 Re-Rest

There we go, WebStorm-managed Docker. Before looking at debugging, let’s cover what’s going on behind the scenes.

What Happens On Each Run

Containers provide isolation. Since your software likely changes between runs, WebStorm provides a newly-minted container on each run. Sounds slow, right? Fortunately, WebStorm takes a number of steps to make this feasible.

First, WebStorm creates a new Dockerfile, keeping your source code up-to-date and installing npm dependencies into the container. This Dockerfile comes from the image that you choose when configuring the remote interpreter. WebStorm makes it convenient to use images from Docker Hub, or your own custom image.

WebStorm then creates a new image and installs the npm modules into the image. To avoid reinstalling the local/global npm modules on every start of the container, package.json is copied to the /tmp/project_modules folder on the image. npm install is then run and the modules will be copied to the project folder in the container. Changing the package.json in the project results in re-building the image.

After this, WebStorm runs the Docker container with the created image and binds your project folder to /opt/project folder in the Docker container to ensure synchronization on update. Additionally, /opt/project/node_modules is mapped to the OS temporary directory.

Here’s an illustration of the configuration created by WebStorm:


If you want custom settings, you can configure Volume mappings for project files and dependencies yourself in “Docker container settings”.


Note: Debugging Node.js apps in Docker is only supported for Node.js version 6.3+.

We’ve now shown running your NodeJS applications in an interpreter in a Docker container. In WebStorm, debugging is just a variation of running: you click a different button, but it uses the same Run/Debug Configuration. Does this mean we can debug NodeJS-Docker apps?

Yes, and it really is that easy. Just set a breakpoint, click the Debug icon in the toolbar, and WebStorm will launch the debug session:

Debug 1

When you issue a request from the REST Client, the debugger stops execution in the Docker container, driven from the IDE:

Debug 2

Like the Run tool, finishing a debugging session deletes the container.

Cleaning Up

When we added a Docker server, WebStorm added a Docker icon tool icon and tool window. When we connected previously, there wasn’t much to look at. Now, however, we see that two images have been downloaded. You can right-click on container and image listings to perform operations such as removal:

14 Final Docker


This covers the basic setup of Docker, as used from WebStorm, with an explanation of what happens behind the scenes. Support for Docker is an ongoing effort, so please keep an eye on our issue tracker for Docker-related tickets.

Comments below can no longer be edited.

17 Responses to Quick Tour of WebStorm and Docker

  1. Avatar

    ManfredLange says:

    August 18, 2018

    Where can I find a git repository with a working example for WebStorm 2018.2?

    It’s plain madness to find the different pieces of information. Many are for old versions of WebStorm, old versions of node, old versions of …..

    Do you have a current example, i.e. in git repository, actually works?

  2. Avatar

    Chris Kovacs says:

    October 13, 2018

    Great tutorial. Illustrates the process well and helps me understand the methods.

    There’s an error that you should really fix. In the step for configuring the Node interpreter, the docker image name in the screenshot is “docker:latest” when it’s supposed to be “node:latest”.

    I had to double-take when I saw that, proceeded to use “docker:latest” without success and then I retraced steps and changed it to “node:latest”.

    • Avatar

      Paul Everitt says:

      October 14, 2018

      You’re certainly right that this topic (Docker and our Docker support) gets out of date quickly.

  3. Avatar

    Peter Kellner says:

    November 11, 2018

    Kind of a newby to docker and saw this. Couple questions:

    1) is there a place I can see what docker commands are generated? that is, when I run from command prompt I do: docker run -p 1080:3000 svccps:latest. When I say start container, I don’t see this command generated for me, but it seems to have run

    2) where is the terminal log of my docker output? That is, my node.js is running inside the container and I want to see the output.

    • Avatar

      Paul Everitt says:

      November 15, 2018

      Yikes, sorry Peter, I haven’t replied yet. Working on a deadline that’s in two hours. I’ll look at this later today.

    • Avatar

      Darryl says:

      January 28, 2019

      Hi @Peter Kellner,

      I’m trying to help to answer.
      Point no one, you can take a look the command generated on `Run/Debug Configurations` -> Docker container settings.

      For point no 2, when you run the application, you will see `Run` tab docked at the bottom of webstorm window, this will show the docker output. Other way is by using docker command, since we are connecting to the docker server, you can run `docker ps` on your terminal and then `docker logs [container]`.

      Hope this help!

  4. Avatar

    Darryl says:

    February 1, 2019

    Hi Paul Everitt,

    This is a great post and it works smoothly with the example application.
    I have a question regarding private `npm registry`, how do we set private npm registry in run/debug configuration?

    Usually we did `npm config set registry=[private repo]`, but I can’t find a way to change this in the configuration.

    Thank you

    • Avatar

      Darryl says:

      February 1, 2019

      I just found the workaround of my issue, so currently it works but another problem appear.

      After it finish build the docker image, nothing happened. Seems webstorm doesn’t execute the initial javascript file we have defined in the configuration (on my host machine).

      Is there any way to trace the logs during build the image? because webstorm just showing loading popup `Building Project Image` without any output. The error also doesn’t show up in the error Event Log like previous issue.

      Really appreciate any help! Thanks

      • Ekaterina Prigara

        Ekaterina Prigara says:

        February 1, 2019

        Hello Darryl,
        To be honest, I haven’t tried using Docker in WebStorm with the private npm registry, but I think you should be able to modify the dockerfile that IDE created automatically in the project root and change the npm command in it to the one you need.
        Regarding the troubleshooting, can you please send the IDE log (menu Help – Compress logs) to our tech support with a brief description of the problem (or a link to this thread). My colleagues will then advise on the next steps. Thanks!

  5. Avatar

    Rafael says:

    February 4, 2019

    I have problem with running nodejs from docker on webstorm. I got such error and i don’t know what to do next. I set docker and i added this docker as a node interpreter with auto configure enabled.

    Appreciate for any help.

    • Ekaterina Prigara

      Ekaterina Prigara says:

      February 5, 2019

      Can you run npm install for this project locally? Do you have the same node version on your Docker image?

      • Avatar

        Rafael says:

        February 5, 2019

        Hi Ekaterina,
        Yes, i can run npm install locally and inside docker. On docker i have node v8.11.2 and locally v11.8.0. Does it make any difference ?

  6. Avatar

    Matt G says:

    February 13, 2019

    Hey! I’ve got this working well, but would really like to be able to run my tests too (mocha etc). With the remote node installed, I’m only able to run mocha tests using local node interpreters (rather than the one in my container).

    Any ideas? If this could be supported in a future release, that would be great!

    • Ekaterina Prigara

      Ekaterina Prigara says:

      February 14, 2019

      Hello Matt,
      Right now it’s not possible to run tests in the IDE using the Mocha run/debug configuration with the remote Node.js. Please vote for this feature request: Unfortunately, we can’t provide any estimate when this feature is going to be implemented.

  7. Avatar

    Andy says:

    September 5, 2019

    I’m still a little confused as to how node_modules is handled. I run on windows so I really want npm install to be ran within the container to ensure everything is compiled for linux. Based on this article it suggests Webstorm is handling this behind the scenes? But if I delete the node_modules folder prior to running the interpreter the app fails to run.

    • Avatar

      lena_spb says:

      September 6, 2019


      What Node.js interpreter type have you configured?

      If it’s Docker compose, then just run the created Node.js run/debug configuration. Please note that specifying JavaScript file in Node.js run/debug configuration leads to overwriting command from docker-compose.yml. Keep JavaScript file field empty to not overwrite it. If command contains npm install, it will be executed, just like in a regular console when running docker-compose up.

      If it’s Docker, there are two possibilities: with Auto configure enabled and disabled. When it’s ON, IDE will create its own Dockerfile and create two additional volume bindings (/opt/project -> /your/project/root and /opt/project/node_modules -> /local/tmp/empty-folder). Then, /tmp/project_modules/node_modules is copied to /opt/project/node_modules and the app starts in /opt/project. With Auto configure disabled, make sure that your Dockerfile lays out your application at /opt/project, and create any volume binding to pass IDE check. In both cases, local node_modules shouldn’t be used. If it still doesn’t work, please file an issue in the youtrack.