Processes, PID 1, and Signals

The single most surprising thing about your first real container is that docker stop seems to hang for ten seconds and then your app dies hard — no clean shutdown, no flushed connections, no closed transactions. The cause is almost always that your app is running as a child of a shell, the shell is PID 1, and the shell does not forward SIGTERM. Inside a container your process is PID 1, the kernel gives PID 1 special signal handling, and getting this wrong means every restart is effectively a kill -9.

This is the chapter's footgun, and it is silent. There is no error, no warning, no failed health check — just an app that takes ten seconds to stop and loses whatever it was holding when it does. The fix is one line in a Dockerfile or one flag on docker run, but only once you understand why PID 1 behaves the way it does.

Your Process Is PID 1

Inside the container, the main process runs as PID 1 — the role the init system (systemd, init) holds on a normal host. The kernel treats PID 1 specially: it ignores any signal that has no explicit handler installed. A SIGTERM sent to a PID 1 that never registered a SIGTERM handler is simply dropped, and the process keeps running as if nothing happened. On a normal host you never see this because PID 1 is an init system written precisely to handle signals; in a container, PID 1 is your app, which usually was not.

Shell-Form vs Exec-Form, the Footgun

How you write CMD or ENTRYPOINT decides what becomes PID 1. The exec form, CMD ["gunicorn", "app:app"], runs the binary directly, so gunicorn is PID 1 and receives signals straight from docker stop. The shell form, CMD gunicorn app:app written as a bare string, runs /bin/sh -c "gunicorn app:app" — now sh is PID 1, gunicorn is its child, and sh does not forward SIGTERM to its children. docker stop sends SIGTERM, sh ignores it, the 10-second timer expires, and the daemon SIGKILLs the whole process tree. This one distinction is why the Driftwood web container must use exec form.

Why docker stop Waits 10 Seconds Then SIGKILLs

docker stop sends SIGTERM and starts a 10-second timer, tunable with --timeout (or --stop-timeout at run time). If the process is still alive when the timer expires, the daemon sends SIGKILL, which the kernel cannot be told to ignore — no process, PID 1 or not, can catch or block signal 9. So the 10-second pause is the grace window your app gets only if PID 1 actually receives and acts on SIGTERM. If PID 1 ignores it, the 10 seconds are pure dead time before a forced kill.

# Exec form: gunicorn is PID 1, handles SIGTERM, exits in ~1s
$ time docker stop driftwood-web
driftwood-web
real    0m1.143s

# Shell form: sh is PID 1, drops SIGTERM, daemon waits the full 10s then SIGKILLs
$ time docker stop driftwood-web
driftwood-web
real    0m10.402s          # the tell-tale ~10s hang on every stop

Zombie Reaping

A real init system reaps dead children — it calls wait() on processes that have exited so the kernel can release their entries from the process table. A typical app running as PID 1 does not, because it was never written to. So if the container spawns children that exit — a process pool that recycles workers, a shell wrapper that forks — their dead entries accumulate as zombies, because no one reaps them. Over a long-lived container this slowly exhausts the process table until new workers cannot spawn.

The --init Flag

docker run --init injects a tiny init process — tini — as PID 1, which forwards signals to your app and reaps zombies on its behalf. You get correct SIGTERM delivery and reaping without making the app itself init-aware. The decision is simple: if the app can be PID 1 and handle its own signals, use exec form and let it be PID 1; if it genuinely cannot — it spawns children it does not reap, or it cannot handle signals — add --init (or init: true in Compose) and let tini do the init job.