Lesson 20- Node.js Docker Applications

Graceful Shutdown of Node.js Applications in Docker Containers

A Simple Node.js Application

Let’s start with a simple example. The following Node.js application listens on port 30010 via HTTP and provides a /delay endpoint that responds after a 5-second delay. The process ID is logged for later use in testing process termination.

// app.js
const http = require('http');
const PORT = 30010;
const server = http.createServer((req, res) => {
    if (req.url == '/delay') {
        setTimeout(function() {
            console.log('Delayed output after 5 seconds');
            res.end('Hello Docker delayed by 5 seconds');
        }, 5000)
    }
})

server.listen(PORT, () => {
    console.log('Running on http://localhost:', PORT, ' PID: ', process.pid);
});
// package.json
{ 
    "name": "hello-docker",
    "main": "app.js",   
    "scripts": { 
      "start": "node app.js"
    }
}

Start the Application with npm

npm start

> hello-docker@1.0.0 start /******/hello-docker
> node app.js

Running on http://localhost: 30010  PID:  68971

Inspect npm and Node Process Information

After starting the application, let’s examine the process information. By filtering for npm and node processes, we can see the details. Notice that the Node process (PID: 68971) has a parent process ID (PPID: 68970) corresponding to the npm process. This suggests that npm starts the Node.js service as its child process, which is a correct assumption for now. Let’s proceed.

$ ps -falx | head -1; ps -falx | grep 'npm\|node'
  UID   PID  PPID   C STIME   TTY           TIME CMD                     F PRI NI       SZ    RSS WCHAN     S             ADDR
  502 68970 68016   0  4:29PM ttys003    0:00.35 npm                  4006  31  0  2727120  17304 -      S+                  0
  502 68971 68970   0  4:29PM ttys003    0:00.12 node app.js          4006  31  0  2682628  14608 -      S+                  0

Test with a Request

Let’s test by sending a request to the /delay endpoint using curl http://localhost:30010/delay. Immediately after, in another terminal, execute kill -15 68970 within the 5-second delay window. The request fails with an error response.

kill -15: This sends a SIGTERM signal, which the application can catch, allowing it to perform cleanup before exiting gracefully.

# Send request
$ curl http://localhost:30010/delay

# Kill the process
$ kill -15 68970

# Request fails
curl: (52) Empty reply from server

# The application logs the following error
> hello-docker@1.0.0 start /******/hello-docker
> node index.js

Running on http://localhost: 30010  PID:  68971
zsh: terminated  npm start

This outcome is not ideal. Let’s enhance the application to achieve graceful shutdown.

Implementing Graceful Shutdown in Node.js

Graceful Shutdown: Upon receiving a SIGTERM signal, the program performs cleanup, releases resources, and exits cleanly. For instance, if an HTTP request is being processed, an abrupt termination would prevent the client from receiving a response. Graceful shutdown ensures ongoing connections are handled properly.

By default, Node.js does not handle this automatically. We need to explicitly listen for the signal and call process.exit(0) after resource cleanup.

Modified app.js

const http = require('http');
const PORT = 30010;
const server = http.createServer((req, res) => {
    if (req.url == '/delay') {
        setTimeout(function() {
            console.log('Delayed output after 5 seconds');
            res.end('Hello Docker delayed by 5 seconds');
        }, 5000)
    }
})

/** Modifications for handling process termination signals */
process.on('SIGTERM', close.bind(this, 'SIGTERM'));
process.on('SIGINT', close.bind(this, 'SIGINT'));

function close(signal) {
    console.log(`Received ${signal} signal, starting cleanup`);

    server.close(() => {
        console.log(`Server stopped, ${signal} handling completed`);
        process.exit(0);
    });
}
/** End modifications */

server.listen(PORT, () => {
    console.log('Running on http://localhost:', PORT, ' PID: ', process.pid);
});

Restart and Test the Service

$ npm start
$ ps -falx | head -1; ps -falx | grep 'npm\|node'
  UID   PID  PPID   C STIME   TTY           TIME CMD                     F PRI NI       SZ    RSS WCHAN     S             ADDR
  502 70990 68016   0  6:51PM ttys003    0:00.48 npm                  4006  31  0  2727604  38136 -      S+                  0
  502 70991 70990   0  6:51PM ttys003    0:00.13 node app.js          4006  31  0  2682628  23196 -      S+                  0

Request Test

$ curl http://localhost:30010/delay
$ kill -15 70990 # Interrupt the process

The service doesn’t exit immediately. It logs the following, waiting for the connection to complete before exiting:

Running on http://localhost: 30010  PID:  70991
Received SIGTERM signal, starting cleanup
Delayed output after 5 seconds
Server stopped, SIGTERM handling completed

Testing in a Docker Environment

This assumes familiarity with Docker basics and its use with Node.js. If needed, refer to A Zero-to-Practical Guide to Docker and Node.js Service Dockerization Practice.

Start the Container

$ docker run -d -p 30010:30010 hello-docker
$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                      NAMES
c73389c8340f        hello-docker        "npm start"         6 minutes ago       Up 6 minutes        0.0.0.0:30010->30010/tcp   crazy_archimedes

View Logs

$ docker logs -f c73389c8340f

> hello-docker@1.0.0 start /usr/src/nodejs
> node app.js

Running on http://localhost: 30010  PID:  16

Request Test

$ curl http://localhost:30010/delay
$ docker stop c73389c8340f

After requesting http://localhost:30010/delay and immediately stopping the container, the response fails with curl: (52) Empty reply from server. The Node.js application didn’t receive the exit signal and was forcibly terminated with the container. Let’s analyze why.

$ curl http://localhost:30010/delay
curl: (52) Empty reply from server

Why Node.js Fails to Receive Exit Signals in Docker

Let’s analyze this from the perspectives of container process lifecycles, npm startup mechanisms, and signal propagation.

Container Process Lifecycle

The Node.js example worked for graceful shutdown outside a container but failed in Docker. Let’s examine the container’s process lifecycle.

Docker containers isolate processes between containers. For example, Container1 may have an init process with PID=1, and Container2 has its own. Containers are isolated from each other and the host, with independent process spaces and network configurations.

When a Docker container starts, it creates an init process (PID=1) via the ENTRYPOINT or CMD instruction. This process spawns child processes, forming a process tree. When the container exits, it sends a signal to PID=1, which propagates to child processes. The parent process waits for children to exit and collects their status. When PID=1 exits, the container is destroyed, sending a SIGKILL to any remaining processes, forcing termination.

This seems fine, so is there an issue with npm starting the Node process?

npm Startup Mechanism in Containers

Let’s compare npm’s behavior in non-container and container environments. Typically, Node.js applications are started via npm scripts defined in package.json.

npm Starting Node.js in a Non-Container Environment

In a non-container environment, npm directly spawns the Node process, as seen below, where the Node process (PID: 70991) has npm as its parent (PPID: 70990).

$ npm start
$ ps -falx | head -1; ps -falx | grep 'npm\|node'
  UID   PID  PPID   C STIME   TTY           TIME CMD                     F PRI NI       SZ    RSS WCHAN     S             ADDR
  502 70990 68016   0  6:51PM ttys003    0:00.48 npm                  4006  31  0  2727604  38136 -      S+                  0
  502 70991 70990   0  6:51PM ttys003    0:00.13 node app.js          4006  31  0  2682628  23196 -      S+                  0

npm Starting Node.js in a Container

In a Docker container, the CMD ["npm", "start"] instruction is used. Below, the process list and hierarchy (pstree -p) show that npm (PID=1) doesn’t directly spawn the Node process. Instead, it starts a sh process, which then starts the Node process. This differs from the non-container environment.

When docker stop is executed, npm receives the SIGTERM signal and forwards it to sh. However, sh exits upon receiving SIGTERM, and the signal isn’t propagated to the Node process, which waits for container destruction and is forcibly terminated.

$ ps flex
PID   USER     TIME   COMMAND
    1 root       0:00 npm
   15 root       0:00 sh -c node app.js
   16 root       0:00 node app.js

$ pstree -p
npm(1)---sh(15)---node(16)

Solutions for Graceful Shutdown in Docker Containers

Having identified why Node.js fails to shut down gracefully in Docker, here are several solutions.

Run Node as the Container’s Main Process

Modify the Dockerfile to run node app.js directly instead of using npm.

CMD [ "node", "app.js" ]

Rebuild the image and run the container. The init process is now the Node process.

$ docker image build -t hello-docker .
$ docker container run -d -p 30010:30010 hello-docker

# Inspect processes inside the container
$ ps flax
PID   USER     TIME   COMMAND
    1 root       0:00 node app

$ pstree -p
node(1)

Test by sending a request and stopping the container. The response is successful, and logs confirm the process received the exit signal.

$ curl http://localhost:30012/delay
$ docker stop e816ef6290a0
Hello Docker delayed by 5 seconds

# Container logs
$ docker logs -f e816ef6290a0
Running on http://localhost: 30010  PID:  1
Received SIGTERM signal, starting cleanup
Delayed output after 5 seconds
Server stopped, SIGTERM handling completed

Summary of Running Node as Main Process: This is simple but lacks npm script flexibility for complex startup configurations.

Eliminate the Intermediate sh Process

This approach eliminates the sh process between npm and Node by using exec node app.js, which replaces the sh process with the Node process.

Modify package.json

// package.json
{ 
    "name": "hello-docker",
    "main": "app.js",   
    "scripts": { 
      "start": "exec node app.js"
    }
}

Modify Dockerfile

Keep the npm script startup.

CMD ["npm", "start"]

Inspect Container Processes

The process tree (pstree -p) shows npm(1)---node(15), with no sh process.

# Enter the container
$ docker exec -it d5f16c6ffa91 /bin/sh 

$ ps flax
PID   USER     TIME   COMMAND
    1 root       0:00 npm
   15 root       0:00 node app.js

$ pstree -p
npm(1)---node(15)

Other Solutions

The community offers additional solutions, such as:

Egg.js Framework

Testing with the Egg.js framework showed no such issues. The process tree shows npm (PID=1) directly spawning the Node process, likely due to framework-specific handling. Curious readers can explore its implementation.

$ pstree -p
npm(1)---node(24)---node(39)-+-node(46)
                             |-node(73)
                             `-node(74)

Docker stop 10-Second Issue

Let’s modify app.js to increase the delay to 15 seconds and test again.

const server = http.createServer((req, res) => {
    if (req.url == '/delay') {
        setTimeout(function() {
            console.log('Delayed output after 15 seconds');
            res.end('Hello Docker delayed by 15 seconds');
        }, 15000)
    }
})

After sending a request and immediately running docker stop f2206f06472e, the same error reappears:

$ curl http://localhost:30010/delay
curl: (52) Empty reply from server

The previous solutions were correct, but this exposes another issue: the default 10-second timeout for docker stop. Per the Docker documentation, the main process receives a SIGTERM signal, followed by a SIGKILL after a 10-second grace period if it doesn’t exit.

https://docs.docker.com/engine/reference/commandline/stop/#options

The main process inside the container will receive SIGTERM, and after a grace period, SIGKILL

To address this, use the -t option to extend the timeout:

$ docker stop -t=15 d90bab781031

Node.js Service Dockerization Practice

Dockerizing a Node.js Application

Let’s create a simple Node.js application, build a Docker image for it, and run it.

Create a Node.js Project

Create an app.js file to start an HTTP server.

const http = require('http');
const PORT = 30010;

const server = http.createServer((req, res) => {
    res.end('Hello Docker');
})

server.listen(PORT, () => {
    console.log('Running on http://localhost:', PORT, 'NODE_ENV', process.env.NODE_ENV);
});

Create a package.json file to describe the application and its dependencies. I’ve added npm run dev and npm run pro scripts to demonstrate dynamically setting environment variables during the build.

{ 
    "name": "hello-docker", 
    "version": "1.0.2",
    "description": "", 
    "author": "May",
    "main": "app.js",   
    "scripts": {
      "dev": "NODE_ENV=dev node app.js",
      "pro": "NODE_ENV=pro node app.js"
    }
}

Dockerfile

Here’s the Dockerfile with instructions explained in [Docker Basics and Practice]().

FROM node:10.0-alpine

RUN apk --update add tzdata \
    && cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
    && echo "Asia/Shanghai" > /etc/timezone \
    && apk del tzdata

RUN mkdir -p /usr/src/nodejs/

WORKDIR /usr/src/nodejs/

# Add npm package
COPY package.json /usr/src/nodejs/package.json
RUN cd /usr/src/nodejs/
RUN npm i

# Copy code
COPY . /usr/src/nodejs/

EXPOSE 30010

CMD npm run dev

Create a .dockerignore file to exclude local debug files, node_modules, etc., from the Docker container.

.git
node_modules
npm-debug.log

Build the Docker image:

$ docker image build -t mayjun/hello-docker .

Run the container:

$ docker run -d -p 30010:30010 mayjun/hello-docker

However, hardcoding CMD npm run dev limits the image to one environment. Let’s address this.

Dynamically Set Environment Variables

To support multiple environments, modify the Dockerfile to accept build-time arguments.

EXPOSE 30010

ARG node_env # New
ENV NODE_ENV=$node_env  # New
CMD npm run ${NODE_ENV} # Modified

Explanation:

  • ARG node_env: Defines a build-time variable, passed via --build-arg <varname>=<value>.
  • ENV NODE_ENV=$node_env: Sets the environment variable using the build argument.
  • CMD npm run ${NODE_ENV}: Dynamically runs the corresponding npm script.

Build with Dynamic Parameters

$ docker image build --build-arg node_env=dev -t mayjun/hello-docker:1.0.2 . # Dev environment
$ docker image build --build-arg node_env=pro -t mayjun/hello-docker:1.0.2 . # Prod environment

Run the Container

$ docker run -d -p 30010:30010 mayjun/hello-docker:1.0.2
$ docker ps
CONTAINER ID        IMAGE                       COMMAND                  CREATED             STATUS              PORTS                      NAMES
2bc6e62cd0e8        mayjun/hello-docker:1.0.2   "/bin/sh -c 'npm run…"   3 minutes ago       Up 3 minutes        0.0.0.0:30010->30010/tcp   elastic_bouman

View Container Logs

$ docker logs -f 2bc6e62cd0e8

> hello-docker@1.0.0 dev /usr/src/nodejs
> NODE_ENV=dev node app.js

Running on http://localhost: 30010 NODE_ENV dev

The image is available at mayjun/hello-docker:1.0.2 (docker pull mayjun/hello-docker:1.0.2).

Docker and Private npm Packages

If your project uses private npm packages, you may encounter 404 errors during Docker builds. Outside containers, npm login resolves this, but this isn’t feasible in Docker.

Create an Authentication Token

To install private packages, create an authentication token for use in CI environments or Docker containers. See https://docs.npmjs.com/creating-and-viewing-authentication-tokens.

Implementation

Add these lines to the Dockerfile:

# 528das62-e03e-4dc2-ba67-********** is the authentication token
RUN echo "//registry.npmjs.org/:_authToken=528das62-e03e-4dc2-ba67-**********" > /root/.npmrc
RUN cat /root/.npmrc

Egg.js Framework Dockerization

For Egg.js projects using egg-scripts start --daemon, remove --daemon to ensure the container starts correctly.

package.json

{
  "scripts": {
    "start": "egg-scripts start" // Remove --daemon
  }
}

The Dockerfile remains similar to the earlier Node.js example. See Egg.js issue https://github.com/eggjs/egg/issues/1543 for more details.

Optimizing Docker Image Size and Build Time

Unoptimized Docker images can be large. Here are some optimization techniques from practice.

RUN/COPY Layering

Each Dockerfile instruction creates an image layer. Unchanged instructions or files are cached. In the mayjun/hello-docker:latest image, copying all files before npm install forces reinstallation even if package.json is unchanged.

# ...

WORKDIR /usr/src/nodejs/hello-docker
COPY . /usr/src/nodejs/hello-docker

RUN npm install

# ...

Improved version:

# ...

WORKDIR /usr/src/nodejs/

# Add npm package
COPY package.json /usr/src/app/package.json
RUN cd /usr/src/app/
RUN npm i

# Copy code
COPY . /usr/src/app/

# ...

This ensures npm install is skipped if package.json is unchanged, reducing build time.

Node.js Alpine Image Optimization

The mayjun/hello-docker:1.0.0 image was 688MB before optimization.

$ docker images
REPOSITORY            TAG                 IMAGE ID            CREATED             SIZE
mayjun/hello-docker   1.0.0               7217fb3e9daa        5 seconds ago       688MB

Use Alpine

Alpine is a lightweight Linux distribution. Using node:10.0-alpine significantly reduces image size. Configure the timezone, as Alpine defaults to a non-China timezone.

FROM node:10.0-alpine

RUN apk --update add tzdata \
    && cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
    && echo "Asia/Shanghai" > /etc/timezone \
    && apk del tzdata

RUN echo "Asia/Shanghai" > /etc/timezone

RUN mkdir -p /usr/src/nodejs/

WORKDIR /usr/src/nodejs/

# Add npm package
COPY package.json /usr/src/app/package.json
RUN cd /usr/src/app/
RUN npm i

# Copy code
COPY . /usr/src/app/

EXPOSE 30010
CMD npm start

The optimized mayjun/hello-docker:1.1.0 image is 85.3MB.

$ docker images
REPOSITORY            TAG                 IMAGE ID            CREATED             SIZE
mayjun/hello-docker   1.1.0               169e05b8197d        3 minutes ago       85.3MB

Exclude devDependencies in Production

Avoid including devDependencies in production images by using the --production flag with npm install.

FROM node:10.0-alpine

# ...

# Add npm package
COPY package.json /usr/src/app/package.json
RUN cd /usr/src/app/
RUN npm i --production # Modified

# ...

The mayjun/hello-docker:1.2.0 image is further reduced to 72.3MB.

$ docker images
REPOSITORY            TAG                 IMAGE ID            CREATED             SIZE
mayjun/hello-docker   1.2.0               f018aa578711        3 seconds ago       72.3MB

Common Issues

Question 1

Deleting an image fails:

$ docker rmi 6b1c2775591e
Error response from daemon: conflict: unable to delete 6b1c2775591e (must be forced) - image is referenced in multiple repositories

The image ID 6b1c2775591e is used by both hello-docker and mayjun/hello-docker.

$ docker images
REPOSITORY            TAG                 IMAGE ID            CREATED             SIZE
mysql                 5.7                 383867b75fd2        6 days ago          373MB
hello-docker          latest              6b1c2775591e        7 days ago          675MB
mayjun/hello-docker   latest              6b1c2775591e        7 days ago          675MB

Delete by specifying the repository and tag:

$ docker rmi mayjun/hello-docker
$ docker images                 
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
mysql               5.7                 383867b75fd2        6 days ago          373MB
hello-docker        latest              6b1c2775591e        7 days ago          675MB

Question 2

Deleting an image fails due to a running container:

$ docker rmi 9be467fd1285
Error response from daemon: conflict: unable to delete 9be467fd1285 (cannot be forced) - image is being used by running container 1febfb05b850

Stop and remove the container first:

$ docker container kill 1febfb05b850 # Stop container
$ docker rm 1febfb05b850 # Remove container
$ docker rmi 9be467fd1285 # Remove image

Question 3

Inconsistent WORKDIR and COPY paths cause errors:

...
WORKDIR /usr/src/nodejs/

# Add npm package
COPY package.json /usr/src/node/package.json # Inconsistent path
RUN cd /usr/src/node/ # Inconsistent path
RUN npm i
...

Fix by ensuring consistency:

WORKDIR /usr/src/nodejs/

# Add npm package
COPY package.json /usr/src/nodejs/package.json # Consistent
RUN cd /usr/src/nodejs/ # Consistent
RUN npm i

Share your love