6.1.3.1 Graceful Stop Signal

The graceful stop signal is SIGTERM, the signal Docker sends to a container's main process when docker stop is invoked, giving that process an opportunity to shut down cleanly — closing connections, finishing in-flight work, releasing resources — before being forcibly terminated if it doesn't respond in time.

How the Graceful Stop Signal Is Sent

docker stop sends SIGTERM to the container's main process (PID 1 within its namespace), expecting that process to begin a clean shutdown in response.

docker stop myapp

Internally, this sends SIGTERM and then waits a configurable grace period before resorting to a forceful SIGKILL if the process hasn't exited.

Why an Application Should Handle SIGTERM Explicitly

An application that does not explicitly handle SIGTERM may not perform any graceful shutdown logic at all, potentially leaving in-flight requests interrupted or resources improperly released when the process is eventually force-killed.

process.on('SIGTERM', () => {
  server.close(() => {
    process.exit(0);
  });
});

This example explicitly listens for SIGTERM, stops accepting new connections, and exits cleanly once existing connections have finished, rather than being abruptly terminated.

Why Signal Handling Can Be Tricky With Shell Wrappers

If a container's main process is actually a shell script wrapping the real application, SIGTERM sent to the shell may not automatically propagate to the application process it started, unless the script explicitly forwards the signal.

#!/bin/sh
exec myapp

Using exec here replaces the shell process with the application entirely, rather than running it as a child process, ensuring SIGTERM reaches the application directly.

Why the Graceful Stop Signal Matters

Properly handling SIGTERM is essential for an application to shut down cleanly when its container is stopped, directly affecting whether in-flight work completes successfully or is abruptly and potentially harmfully interrupted.