Catalog My learning Blog
Docker and Kubernetes Tutorial: Containers to Production · Phase 1 · Lesson 5 · 3 min read

Docker Container Lifecycle Explained

On this page
  1. Why docker stop takes ten seconds: exit code 137
  2. Docker container lifecycle states
  3. What docker stop does: SIGTERM, then SIGKILL
  4. Why a container ignores SIGTERM
  5. Fix: make the app PID 1 and handle SIGTERM
  6. Docker exit codes: 0, 1, 125-127, 137 and 143
  7. Docker restart policies compared
  8. Check yourself

Why docker stop takes ten seconds: exit code 137

docker stop api hangs for ten seconds, every time, then the container exits with code 137. Logs show the app never ran its shutdown code. Requests in flight were cut off. The cause is a detail of how Linux treats PID 1, and it's common in hand-written Dockerfiles.

Docker container lifecycle states

StateHow you get thereNotes
Createddocker createConfigured, not started
Runningdocker start / docker runMain process alive
Pauseddocker pauseProcesses frozen via cgroups
ExitedMain process ended, or docker stop/killFilesystem kept; docker ps -a shows it
Removeddocker rmWritable layer deleted

A container lives exactly as long as its main process (PID 1 inside it). When that process exits, the container exits.

A container moves from created to running, can be paused, exits when its main process ends, and is deleted when removed.
A container moves from created to running, can be paused, exits when its main process ends, and is deleted when removed.

What docker stop does: SIGTERM, then SIGKILL

  1. Sends SIGTERM to PID 1: "please shut down".
  2. Waits for a grace period: 10 seconds by default (docker stop -t 30 to change it).
  3. If the process is still running, sends SIGKILL, which can't be caught.

A well-behaved app catches SIGTERM, stops accepting new work, finishes in-flight requests, closes connections and exits.

Why a container ignores SIGTERM

Two usual causes:

1. A shell is PID 1. With shell-form CMD node server.js or a wrapper script, /bin/sh is PID 1 and your app is its child. Many shells don't forward SIGTERM to children, so your app never hears it.

2. PID 1 has no default signal handling. The kernel doesn't apply default actions to signals sent to PID 1 in a namespace. If your app doesn't install a SIGTERM handler, the signal is simply ignored.

Shell
docker inspect -f '{{.State.ExitCode}}' api       # 137 = 128 + 9: killed by SIGKILL
docker exec api ps                                # is PID 1 "sh -c ..." instead of your app?

Fix: make the app PID 1 and handle SIGTERM

  • Use exec-form CMD ["node", "server.js"], or exec in wrapper scripts (exec node server.js), so the app becomes PID 1.
  • Handle SIGTERM in the app. Most frameworks do it: ASP.NET Core's host stops gracefully on SIGTERM; in Node, process.on('SIGTERM', ...) to close the server.
  • If the app can't be PID 1 safely, run a tiny init process: docker run --init adds tini, which forwards signals and reaps zombie processes.

Then docker stop returns in under a second with exit code 0 or 143 (128 + 15, terminated by SIGTERM).

Docker exit codes: 0, 1, 125-127, 137 and 143

CodeMeaning
0Clean exit
1 (or other small numbers)Application error
125 / 126 / 127Docker couldn't run it / command not executable / command not found
137Killed by SIGKILL: grace period expired, or out of memory (check OOMKilled in docker inspect)
143Terminated by SIGTERM

Docker restart policies compared

PolicyAfter a crashAfter `docker stop`After the daemon or host restarts
no (default)NoNoNo
on-failure[:N]Yes, up to N timesNoYes, if it was running
unless-stoppedYesNoYes, unless you stopped it
alwaysYesStays stopped until the daemon restartsYes

For services on a single host, unless-stopped is a sensible default. In Kubernetes, the platform handles restarts instead (Day 17).

Check yourself

It was killed with SIGKILL, either because it ignored SIGTERM until the grace period ran out, or because it exceeded its memory limit.

A shell is PID 1 and doesn't forward the signal, or the app runs as PID 1 without a SIGTERM handler, so the kernel ignores the signal.

unless-stopped. It restarts the container whenever it exits and after the Docker daemon starts on boot, but not if you stopped it yourself with docker stop. always would also restart a manually stopped container after a daemon restart, and on-failure only restarts after non-zero exits.

128 + 15: the process was terminated by SIGTERM and exited because of it, which is the normal result of docker stop for an app that doesn't handle the signal itself. An app that shuts down cleanly on SIGTERM usually exits with 0 instead.

It runs a tiny init process (tini) as PID 1, which forwards signals to your app and reaps zombie processes. That fixes apps that don't handle SIGTERM as PID 1, without changing the app.