Debug NodeJS applications with Docker

You covered your codebase with unit tests but you’re still facing some weird bugs from time to time and don’t know how to find the issues in your web application, serverless endpoint or cron job script? This post will guide you through the pain of setting up debuggers in your IDE and describes how a debugger works in detail.

All the code used in this post can be found here:

What is debugging?

Debugging means to find a bug/anomaly in your code/program. Normally you can use a debugger to start your program in a monitoring mode to see what happens by stepping through the code line by line(Interactive debugging).

Which methods are common to find bugs:

  • print debugging (console API -> console.log(‘Hello’);)
  • Interactive debugging(step through debugging)
  • Remote debugging / Debug a remote application with a local debugger tool

In this post we will checkout the interactive debugger and actually its some kind of remote debugging, because we run apps in a container.

Debug Node scripts with the help of Google Chrome

Let’s start to debug a simple script file with the following content(test.js):

const fib = n => {
if (n > 1) {
return fib(n - 1) + fib(n - 2)
} else {
return n;

const result = fib(3);

const log = `my result is ${result}`;

To enable a debugging process listening on port 9229 waiting for a client at a breakpoint(start of debugging in the program), we run this script in the terminal with Docker:

docker run --rm -it -v $PWD/script:/app -w /app -p 9229:9229 node:12-alpine node --inspect-brk= test.js
execute test.js file in the script folder

Now open Google Chrome and browse chrome:://inspect and you will find the following target:

Browse chrome://inspect

After clicking on inspect and F10 you should see the following output in an appearing popup:

Google Chrome popup to debug your script

Yes! The further execution of the program stops and we are able to debug node.js scripts with Google Chrome!

Debug a Node script with IntelliJ(Jetbrains) based IDEs

Intellij based IDEs like PhpStorm or Webstorm offer a really simple node debugging support. Before running your script set a breakpoint like this:

Set a breakpoint on the line number your debugger should start

When you run your script with docker you get the followin output in the IDEs terminal output:

Now simply click the link “debugger listening on” and the following window shows up:

Debugger in PHPStorm(IntelliJ)

Now you can step over with F8 or step into a function call with F7 and check the variable content in the Variables window.

Debug a Node script with Visual Studio Code

In Visual Studio Code you need to open the Terminal and run the docker based node script again:

docker run --rm -it -v $PWD/script:/app -w /app -p 9229:9229 node:12-alpine node --inspect-brk= test.js

Now with F1 open the command and search for Debug: Attach to Node Process and click it:

Search with F1 for debug and click on Debug: Attach to Node Process

Once the debugger is attached to the process you can click on the bug icon in the left navigation panel and start debugging:

Debug Node web applications

Until now we debugged basic node scripts but what about real web applications? To debug a express NodeJS web application we start up the app with debug mode enabled like this in your terminal:

docker run --rm -it -v $PWD/web_app:/app -w /app -p 8080:3000 -p 9229:9229 node:12-alpine node --inspect-brk= index.js

Now use your favorite IDE or Google Chrome to attach the debugger(as shown before) and browse http://localhost:8080(or curl http://localhost:8080) to trigger a request and get the following output(Intellij IDE):

Debug request headers in the variable section in PHPStorm

As you can see the debugging process is not really different compared to basic NodeJS scripts.

Debug AWS Lambda function

A lot of developers work with cloud platforms like AWS, which offers serverless lambda functions that can be invoked in many different ways. How to debug these kind of applications?

Let’s use the industry standard serverless framework and try to debug it locally. To install serverless and the ability to run it locally you need to install the following packages:

docker run --rm -it -v $PWD/web_app:/app -w /app node:12-alpine npm install serverless serverless-offline --save-dev
Both packages should be added to the devDependencies section in your package.json file

The first thing for the serverless lambda function is to create a serverless.yml configuration file like this:

service: serverless-simple-http-endpoint

name: aws
runtime: nodejs12.x

handler: handler.endpoint
- http:
path: ping
method: get

- serverless-offline

This tells the framework that we use NodeJS 12 with an endpoint like http://host:3000/dev/ping. We use the serverless offline plugin to run the lambda function locally.

The code for the configured handler.js file looks like this:

'use strict';

module.exports.endpoint = (event, context, callback) => {
const response = {
statusCode: 200,
body: JSON.stringify({
message: `Hello, the current time is ${new Date().toTimeString()}.`,

callback(null, response);

To run this serverless lambda function with Docker and make it accessible via http://localhost:8080/dev/ping, use this command:

docker run --rm -it -v $PWD/aws_lambda:/app -w /app -p 8080:3000 -p 9229:9229 node:12-alpine node --inspect-brk= node_modules/.bin/serverless offline --host --httpPort 3000

After attaching your debugger this output appears on your console when serverless offline is ready to handle requests:

Serverless offline is ready to handle requests

No you can browse or curl http://localhost:8080/dev/ping and start debugging:

Debugging serverless lamdba function


After this guide using different IDEs and Google Chrome to debug your NodeJS applications, you are able to find bugs in your software pretty quick without much need to configure your IDE. A debugging session should be possible to start within seconds to remove a bug!

Software Architect

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store