This container doesn't shut down gracefully and loses in-flight requests. Fix it.

Understanding the Shutdown Sequence

1. docker stop <container>
2. Docker sends SIGTERM to PID 1 in container
3. Container has 10 seconds (default) to exit gracefully
4. If still running, Docker sends SIGKILL (immediate termination)

Common Problem: If your app runs via a shell script, the shell (PID 1) receives SIGTERM but doesn’t forward it to your app!

Step 1: Fix the Dockerfile

# WRONG: Shell form - runs through /bin/sh
CMD npm start

# WRONG: Shell wrapper traps signals
CMD ["./start.sh"]

# RIGHT: Exec form - app is PID 1, receives signals directly
CMD ["node", "server.js"]

Step 2: Use a Proper Init System

FROM node:18-alpine

# Install tini (included in Alpine)
RUN apk add --no-cache tini

WORKDIR /app
COPY . .
RUN npm ci --only=production

# Tini handles signal forwarding and zombie reaping
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "server.js"]

Why tini?

• Forwards signals to child processes
• Reaps zombie processes
• Lightweight (< 1MB)
• Handles edge cases your app shouldn’t worry about

Step 3: Implement Signal Handler in Application

// server.js
const express = require('express');
const app = express();

let isShuttingDown = false;
let server;

// Middleware to reject requests during shutdown
app.use((req, res, next) => {
  if (isShuttingDown) {
    res.status(503).json({ error: 'Server is shutting down' });
    return;
  }
  next();
});

// Your routes
app.post('/orders', async (req, res) => {
  // Long-running request simulation
  await processOrder(req.body);
  res.json({ status: 'completed' });
});

// Start server
server = app.listen(3000, () => {
  console.log('Server started on port 3000');
});

// Graceful shutdown handler
function gracefulShutdown(signal) {
  console.log(`Received ${signal}. Starting graceful shutdown...`);
  isShuttingDown = true;

  // Stop accepting new connections
  server.close((err) => {
    if (err) {
      console.error('Error during shutdown:', err);
      process.exit(1);
    }

    console.log('All connections closed. Exiting.');
    process.exit(0);
  });

  // Force exit after timeout (safety net)
  setTimeout(() => {
    console.error('Shutdown timeout. Forcing exit.');
    process.exit(1);
  }, 25000); // Leave buffer before Docker's SIGKILL
}

// Handle shutdown signals
process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT', () => gracefulShutdown('SIGINT'));

Step 4: Configure Docker Stop Timeout

# docker-compose.yml
services:
  api:
    image: api:v2.0
    stop_grace_period: 30s  # Give app 30 seconds to shutdown

# Command line
docker stop --time 30 api-service

Step 5: Handle Database Connections

const pool = require('./db');

async function gracefulShutdown(signal) {
  console.log(`Received ${signal}. Starting graceful shutdown...`);
  isShuttingDown = true;

  // 1. Stop accepting new requests
  server.close(async () => {
    try {
      // 2. Close database connections
      await pool.end();
      console.log('Database pool closed');

      // 3. Close other resources (Redis, MQ, etc.)
      await redis.quit();
      await mqConnection.close();

      console.log('All resources closed. Exiting.');
      process.exit(0);
    } catch (err) {
      console.error('Error during cleanup:', err);
      process.exit(1);
    }
  });
}