By Max McCarty / February 9, 2017

Share

Tweet

Share

Share

If you’re using Docker to host your applications development environment, it will be important to know how to debug your applications source code running in the container. This is the first of a three part series where were going to look at how to debug docker containers running an React.js/Node.js/Express.js application. In this first part were going to look at how to use WebStorm, followed by Visual Studio Code and finally hooking up the good Ol’ fashion node.js debugger.

If you haven’t started, but are interested in hosting your applications development environment inside Docker containers, you’re going to want to check out the recently released Docker for Devs tutorial. If you’re coming directly to this tutorial on debugging docker containers, I’ll be assuming you’re familiar with Docker Compose.

As a bonus, we’re also going to look at nodemon for monitoring server side changes and restarting our server without us having to shutdown and restart containers on ever server-side change.

Getting Started

To easily get up and running, you can use this Github repository to get up and running. Its very similar to the tutorial involving Docker Compose but without the nginx reverse proxy.

Debug Docker Containers

The bottom line is, we need our Docker container to be reachable by an external debugger. In our case, we want to configure WebStorm’s Node.js debugging plugin to connect to our running Express.js application’s debugger that is running remotely in our Docker Container. In doing so, we’ll be in a position to debug docker container with WebStorm or other other EDIs which we’ll see in upcoming tutorials.

Therefore, this is a three part series:

1. Prepare Docker Compose
2. Build Images and Run Containers using Docker Compose
3. Configure WebStorm Node.js Remote Debugger plugin
4. Connect WebStorm Node.js Remote Interpreter to our application’s debugger

Step 1. Preparing Images

Step 1a. Create Docker Compose File

No different than how we started using Docker Compose in the Docker tutorial, we’re also going to leverage Docker Compose for creating our network, creating our services and their containers in this debug docker container tutorial.

1. Create a file in the root of the project and name it “docker-compose.yml”
2. Paste in the following:

   version: "2.1"
   
   services:
   node:
   container_name: hackershall-dev-app
   image: hackershall-dev-i
   build:
   context: .
   dockerfile: ./.docker/node.dev.dockerfile
   ports:
   - "7000:7000"
   networks:
   - hackershall-network
   volumes:
   - .:/var/app
   env_file:
   - ./.docker/env/app.dev.env
   working_dir: /var/app
   
   mongo:
   container_name: hackershall-dev-mongodb
   image: mongo:3.4.1
   build:
   context: .
   dockerfile: ./.docker/mongo.dev.dockerfile
   env_file:
   - ./.docker/env/mongo.dev.env
   networks:
   - hackershall-network
   ports:
   - "27017"
   
   networks:
   hackershall-network:
   driver: bridge

    

What Did We Do?

• We created a Docker Compose File
• That created a single network named “hackershall-network”
• Specified two services: node and mongo
• and set the services to use the “hackershall-network” network

Step 1b. Debug Ports

Currently, we only have the port 7000 of the container mapped to our local host post 7000. We are using this port to connect to the running application in our container (e.g. http://localhost:7000).

We want to be able to attach WebStorm to a running node.js debugger in our application’s Docker container. To do this, we need to open up the port that our Express.js application debugger will be listening on.

We could specify any port to use by specifying a port along with the –debug flag, when we start our express.js application.

e.g.

node --debug=<custom_port>

However, to keep it as simple as possible, we’re going to stick with the default port that node.js debugger will listen on which 5858.

In order to make it available through our container do the following:

1. Inside the docker-compose.yml file, locate the “ports” property, under the “node” service
2. add an additional port mapping 5858 to local host port 5858:

   ports:
     - "7000:7000"
     - "5858:5858"
   

    

What Did We Do?

• We have mapped the port 5858 on the container to our local host port 5858
• If the node.js debugger for our application is listening on port 5858, we’ll be able to connect to it from our host machine.

Step 1c: Updating Dockerfile

When setting up port access to a container there are two parts. Exposing the port on the container and mapping the port from the container to the local host. I thought it might be easier in the overall approach to wire up the port mapping first.

We now need to expose port 5858 from our express.js application image which we’ll specify in the application development Dockerfile:

1. Open the file “node.dev.dockerfile” in the .docker directory off the root
2. Lets add a new environment variable and its value, locate the ENV line and update with:

   ENV NODE_ENV=development

3. Update to:

   ENV NODE_ENV=development DEBUG_PORT=5858

4. Before the CMD command, add the following:

   EXPOSE $DEBUG_PORT

   Result:

   FROM maxmccarty/hackershall-prod-i
   
   ENV NODE_ENV=development DEBUG_PORT=5858
   
   EXPOSE $DEBUG_PORT
   
   CMD ["./.docker/node_scripts/initialize.sh"]

    

Step 1d: Updating Our NPM Scripts

We still have one more step to complete to be able to attach WebStorm to a node.js debugger and that is starting our application’s node.js debugger.

1. Open the package.json file in the project root
2. Locate the NPM script:

   "start:server": “babel-node server/server.js,

3. Add the –debug flag after babel REPL

   "start:server": "babel-node --debug server/server.js",

    

What Did We Do?

• On our NPM script to start our application,
• we specify the –debug flag in order to start the node.js debugger to be listening

Step 1e: Enabling nodemon

While we already have everything in place to create our application development environment images, lets add nodemon into the mix.

1. Going back to the same NPM script we edited in Step 1c, lets make the small change of adding nodemon:

   "start:server": "nodemon --debug server/server.js --exec babel-node",

What Did We Do?

• We added the nodemon utility to run our node.js application
• and specified nodemon to execute the babel-node CLI using the —exec option

Step 2: Build Images and Run Containers using Docker Compose

With our dockerfile’s updated to expose the debugger port 5858 from our application container, along with the port mapping to our local host, we’re ready to create the images and generate running containers of our application.

Step 2a: Build Images

1. To build the specified Docker Compose images for application and database run the command:

   docker-compose build

What did we do?

In that single command of BUILD docker-compose:

• pulled any dependent images
• and built specified images in the docker-compose.yml file.

Step 2b. Generate Containers