Lorixen.
EN

Docker containers slow to stop? Fix PID 1 signal handling

Short answer: If docker stop always pauses for several seconds before the container exits, and your app never gets a chance to finish requests or close connections cleanly, the main process isn't receiving the stop signal. Docker sends SIGTERM to the container's main process (PID 1) and, after a grace period, SIGKILL. A shell-form CMD or ENTRYPOINT makes /bin/sh PID 1, and it doesn't pass signals on. Use the exec form, add an init process with docker run --init or tini, and handle SIGTERM in your app.

What docker stop actually does

Docker's documentation for docker stop explains the sequence: the main process inside the container receives SIGTERM, and after a grace period, SIGKILL. The first signal can be changed with the STOPSIGNAL instruction in the Dockerfile or the --stop-signal option, and the wait can be changed with --timeout.

SIGTERM is the polite request: "please shut down". A well-behaved app stops accepting new work, finishes what it's doing, closes database connections and exits. SIGKILL can't be caught; the process is killed instantly, mid-request if necessary.

If the app never sees SIGTERM, every stop waits out the full grace period and ends with SIGKILL. Deploys are slower, and in-flight requests, uploads or background jobs are cut off.

Why the signal goes missing

Shell form commands. In a Dockerfile, CMD node server.js (shell form) runs your command through /bin/sh -c. Docker's Dockerfile reference warns about the same thing for ENTRYPOINT: in shell form the executable runs as a subcommand of /bin/sh -c, which doesn't pass signals, so it isn't PID 1 and doesn't receive the SIGTERM from docker stop.

Wrapper scripts. An entrypoint script that sets things up and then runs your app as a child process has the same problem unless it hands over control properly.

PID 1 is special. On Linux, the first process in a namespace gets special treatment: signals it hasn't set handlers for aren't acted on by default. An app that would exit on SIGTERM as a normal process may ignore it as PID 1 unless it registers a handler.

Zombie processes. PID 1 is also responsible for reaping exited child processes. Apps that spawn children, such as image tools, PDF generators or shell commands, can leave zombies piling up if PID 1 doesn't collect them.

Fix 1: use the exec form

Write commands as JSON arrays so your app runs directly as PID 1:

  • CMD ["node", "server.js"] rather than CMD node server.js
  • ENTRYPOINT ["/app/start"] rather than ENTRYPOINT /app/start

If you need an entrypoint script for setup, end it with exec, for example exec node server.js, so the shell replaces itself with your app instead of staying as its parent.

Fix 2: add a tiny init process

An init process runs as PID 1, forwards signals to your app and reaps zombies. Docker's run reference describes the --init flag as running an init inside the container that forwards signals and reaps processes, and notes that the default init binary is backed by tini.

  • With the CLI: docker run --init ...
  • With Compose: init: true on the service.
  • In the image itself: install tini and set it as the entrypoint, for example ENTRYPOINT ["/sbin/tini", "--"], with your app as CMD.

Tini's own documentation lists the benefits: protection from software that accidentally creates zombie processes, and correct signal forwarding. It notes that tini needs to run as PID 1 to reap zombies, unless you register it as a subreaper.

Fix 3: handle SIGTERM in your app

Signals reaching the app is half the job; the app must also act on them:

  • Node.js: listen for SIGTERM, stop the HTTP server from accepting new connections, wait for open requests, close database pools, then exit.
  • Python: register a handler with the signal module, or use your server's built-in graceful shutdown (many application servers handle SIGTERM already).
  • Workers and queues: finish or release the current job, then exit, so it can be retried elsewhere.

Keep shutdown shorter than the grace period. If your app genuinely needs longer, for example to finish long uploads, raise the timeout for that service rather than letting SIGKILL cut it off.

Check your stop behaviour

  1. Start the container and note how long docker stop takes.
  2. Watch the app's logs for a "shutting down" message when you stop it.
  3. Run docker top <container> or ps inside the container to see what PID 1 is. If it's sh or bash, signals probably aren't reaching your app.
  4. Look for zombie processes (<defunct> in ps output) after the app has run for a while.

A fixed container should stop within a second or two, with clean shutdown messages in the log.

Health checks and load balancers

A clean shutdown works best when traffic stops arriving first. If a load balancer or orchestrator sends requests to the container, make the app report itself as unhealthy, or deregister it, as soon as SIGTERM arrives, then finish in-flight work. Otherwise new requests may still land on a container that's halfway through closing, and customers see errors even though the app itself shut down politely.

A worked example

Consider a hypothetical Glasgow ticket-reseller platform whose deploys took noticeably longer than expected, and whose logs showed customers' checkout requests cut off during each release. The Dockerfile used CMD npm start, so a shell and npm sat between Docker and the Node process. The developer changed it to CMD ["node", "server.js"], enabled init: true in Compose, and added a SIGTERM handler that closed the HTTP server and database pool. Containers now stop in moments, and checkouts in progress complete before shutdown.

FAQ

Is npm start a problem as PID 1?

Running through npm adds a parent process that may not forward signals as you expect. Running node directly is more predictable.

Does Kubernetes behave the same way?

Kubernetes also sends SIGTERM and later kills the container after a grace period, so the same fixes apply.

Do I need tini if I use the exec form?

Not always, but it's a cheap safety net, especially if your app spawns child processes.

Can I just lower the stop timeout?

That makes stops faster but still kills the app abruptly. Fix signal handling instead.

If your containers stop slowly or drop requests during deploys, tell us how they're built and we'll help fix shutdown.

Sources

WhatsAppBook a call