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: 68971Inspect 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+ 0Test 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 startThis 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+ 0Request Test
$ curl http://localhost:30010/delay
$ kill -15 70990 # Interrupt the processThe 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 completedTesting 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_archimedesView Logs
$ docker logs -f c73389c8340f
> hello-docker@1.0.0 start /usr/src/nodejs
> node app.js
Running on http://localhost: 30010 PID: 16Request Test
$ curl http://localhost:30010/delay
$ docker stop c73389c8340fAfter 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 serverWhy 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+ 0npm 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 completedSummary 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:
- https://github.com/Yelp/dumb-init
- https://github.com/ohjames/smell-baron
- https://github.com/krallin/tini
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 serverThe 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, SIGKILLTo address this, use the -t option to extend the timeout:
$ docker stop -t=15 d90bab781031Node.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 devCreate a .dockerignore file to exclude local debug files, node_modules, etc., from the Docker container.
.git
node_modules
npm-debug.logBuild the Docker image:
$ docker image build -t mayjun/hello-docker .Run the container:
$ docker run -d -p 30010:30010 mayjun/hello-dockerHowever, 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} # ModifiedExplanation:
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 environmentRun 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_boumanView 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 devThe 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/.npmrcEgg.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 688MBUse 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 startThe 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.3MBExclude 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.3MBCommon 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 repositoriesThe 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 675MBDelete 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 675MBQuestion 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 1febfb05b850Stop and remove the container first:
$ docker container kill 1febfb05b850 # Stop container
$ docker rm 1febfb05b850 # Remove container
$ docker rmi 9be467fd1285 # Remove imageQuestion 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



