My deploy script does docker compose down, then docker compose up -d. One afternoon I actually watched it instead of alt-tabbing away, and the down half sat there for about 20 seconds doing nothing visible. So I timed every container one at a time. docker stop takes 10 seconds on 5 of my 6 containers. Not roughly 10. Ten point something, every run, like a timer.
That number is the giveaway. It's not your app being slow to shut down. It's Docker giving up on your app and killing it.
TL;DR
-
docker stopsends SIGTERM, waits 10 seconds by default, then sends SIGKILL. A stop that always lands at ~10s means your process never reacted to SIGTERM. - Inside a container your process is usually PID 1, and Linux does not apply the default "terminate" action to PID 1. If PID 1 has no SIGTERM handler, the signal is simply dropped.
-
Shell-form
CMD node server.jsruns as/bin/sh -c "node server.js". Depending on the shell,shcan end up as PID 1 and your app never sees the signal. - Fix it with exec-form
CMD ["node", "server.js"], a real SIGTERM handler in your app,exec "$@"in entrypoint scripts, ordocker run --init/init: truein Compose. - Check with
docker inspect -f '{{.State.ExitCode}}' <name>after a stop: 137 means it was SIGKILLed.
Why does docker stop take exactly 10 seconds?
Because 10 seconds is Docker's default grace period. docker stop sends the container's stop signal (SIGTERM unless the image says otherwise), starts a timer, and if the main process is still alive when the timer runs out, sends SIGKILL, which cannot be caught or ignored.
You can see the two endings in the exit code:
docker stop api
docker inspect -f '{{.State.ExitCode}}' api
# 137 -> 128 + 9 (SIGKILL: Docker gave up)
# 143 -> 128 + 15 (SIGTERM, default action)
# 0 -> your app caught SIGTERM and exited cleanly
All five of my slow containers exited 137. Every single deploy, five processes were being killed mid-whatever-they-were-doing. Nobody noticed because "the deploy worked."
docker compose down uses the same 10-second default per container, and it stops services in dependency order, so a couple of layers of ignored signals stack up into the 20 seconds I was staring at.
Why does PID 1 ignore SIGTERM?
PID 1 is special in Linux. On a normal process, a signal with no handler gets its default action, and for SIGTERM the default is "die." For PID 1 of a PID namespace, the kernel skips that default. If the process hasn't explicitly installed a handler, SIGTERM does nothing.
On your laptop, PID 1 is systemd or launchd, which handle signals on purpose. In a container, PID 1 is whatever your CMD or ENTRYPOINT started. Your Flask app. Your Node worker. A bash script someone wrote in 2019.
Two concrete cases from my six:
-
Python worker. CPython installs a handler for SIGINT (that's your
KeyboardInterrupt), but not for SIGTERM. As PID 1, a plain Python script ignores SIGTERM completely. -
Node API. The official Node Docker guidance says it outright: Node wasn't designed to run as PID 1. My API had no
process.on('SIGTERM')handler, and it sat there for the full 10 seconds every time.
Run the same programs outside Docker and kill <pid> stops them instantly. That's why this one hides so well.
What is the difference between shell form and exec form CMD?
Shell form is the string version, and Docker wraps it in a shell. Exec form is the JSON array version, and Docker runs it directly.
# Shell form: Docker actually runs ["/bin/sh", "-c", "node server.js"]
CMD node server.js
# Exec form: Docker runs node directly as PID 1
CMD ["node", "server.js"]
You don't have to guess which one an image uses:
docker inspect -f '{{json .Config.Cmd}}' api
# ["/bin/sh","-c","node server.js"] <- shell form
With shell form, whether sh stays around as PID 1 depends on the shell. Some shells replace themselves with the last simple command (an exec optimization), some don't, and the moment you write CMD cd /app && node server.js you've given most of them a reason to stick around. When sh is PID 1, it receives SIGTERM, has no handler, ignores it, and doesn't forward it to node. Your app never even hears about the shutdown.
Don't reason about it. Look:
docker exec api ps -o pid,comm
# PID COMMAND
# 1 sh
# 7 node
If PID 1 isn't your actual program, that's your 10 seconds. (On minimal images without ps, docker exec api cat /proc/1/cmdline works.)
Does npm start forward SIGTERM to my Node app?
Don't bet your shutdown on it. CMD ["npm", "start"] makes npm PID 1, and npm runs your script through yet another sh -c. That's two layers between Docker and the process that holds your open connections, and how well signals pass through them has varied over the years.
The fix is boring: call node directly.
CMD ["node", "server.js"]
Same rule for yarn start, poetry run, pipenv run, and any other launcher. Package managers are for installing things, not for being PID 1.
How do I fix docker stop taking 10 seconds?
Use exec form, give PID 1 a SIGTERM handler, and if you can't control the process, put a tiny init in front of it. Here's what I changed, one container at a time.
1. Exec form everywhere. Three of my five slow containers were plain shell-form CMD lines. Switching to the JSON array was the whole fix for two of them.
2. A real SIGTERM handler. Exec form only gets the signal to your process. Your process still has to do something with it. For the Node API:
const server = app.listen(3000);
process.on('SIGTERM', () => {
server.close(() => process.exit(0)); // stop accepting, finish in-flight
setTimeout(() => process.exit(1), 8000).unref(); // don't outlive the grace period
});
For the Python worker:
import signal, sys
def shutdown(signum, frame):
# finish the current job, close connections
sys.exit(0)
signal.signal(signal.SIGTERM, shutdown)
3. exec "$@" in entrypoint scripts. One container had an entrypoint.sh that ran migrations and then started the server. The last line was python worker.py. Bash stayed as PID 1 and swallowed the signal. One word fixed it:
#!/bin/sh
set -e
python manage.py migrate
exec "$@"
exec replaces the shell with your program, so your program becomes PID 1 and receives signals directly.
4. --init for things you don't own. For a third-party image I didn't want to rebuild, Docker can inject a minimal init (tini) as PID 1. It forwards signals to your process and reaps zombie child processes as a bonus.
docker run --init some/image
services:
worker:
image: some/image
init: true
5. Change the signal or the timeout only when you mean it. Some programs want a different shutdown signal. The official nginx image sets STOPSIGNAL SIGQUIT because that's nginx's graceful shutdown. If your app genuinely needs longer than 10 seconds to drain, raise it with stop_grace_period: 30s in Compose or docker stop -t 30. Raising the timeout on a process that ignores SIGTERM just makes you wait longer for the same SIGKILL.
Why does this matter if the container stops anyway?
Because SIGKILL is not a shutdown, it's a power cut. No in-flight requests finish. No database transaction gets cleanly closed. No queue message gets acked or handed back. No log buffer gets flushed.
Kubernetes plays by the same rules, just with a 30-second default terminationGracePeriodSeconds. A pod whose PID 1 ignores SIGTERM burns the full 30 seconds on every rollout and then gets killed. Multiply that by replicas and rolling-update batches and your "slow deploys" might be nothing but ignored signals.
What happened to my six containers?
After the changes, all six stop in under a second and exit 0. My compose down went from about 20 seconds to about 2. The one container that was fast from the start was Postgres, whose official image ends its entrypoint with exec and whose server treats SIGTERM as a proper shutdown request. The database was the only thing in my stack that was already doing it right.
The full audit takes five minutes:
for c in $(docker ps --format '{{.Names}}'); do
echo "$c: $(docker exec "$c" cat /proc/1/cmdline 2>/dev/null | tr '\0' ' ')"
done
Anything that prints sh -c, npm, or a script name instead of your real binary deserves a look.
So why does docker stop take 10 seconds?
docker stop takes 10 seconds because Docker sends SIGTERM, your container's PID 1 ignores it, and Docker waits out its default 10-second grace period before sending SIGKILL (exit code 137). PID 1 ignores SIGTERM when it has no handler installed, because Linux skips the default terminate action for a namespace's init process, and shell-form CMD, npm start, or an entrypoint script without exec can put a shell in that seat so your app never receives the signal. Switch to exec-form CMD ["your", "binary"], end entrypoint scripts with exec "$@", add a SIGTERM handler that drains and exits, or run with --init, and the stop drops from 10 seconds to almost nothing.
Written by the developer behind Preterview, an interview prep platform.
Top comments (8)
Replying to softverseadmin below rather than starting a separate thread: the CMD-form diagnosis is the right one, and it reframes the whole budget. If the signal never arrives, the grace period is not measuring your shutdown path at all - it is measuring how long the kernel waits before SIGKILL. That is why the number lands on a clean 10.000s instead of scattering.
Two consequences worth adding. The "one container that exited cleanly" test is cheap and diagnostic: exec form or not. And once the form is fixed, the exit time becomes a real measurement, so log signal-to-exit - a value that still equals the grace period afterwards means a handler that blocks, not a signal that was dropped.
In Kubernetes the default terminationGracePeriodSeconds of 30 makes the same arithmetic worse: six replicas rolling with a 30s grace is minutes of degraded capacity, not seconds.
The 10.000s landing exactly is the part I keep coming back to — a real shutdown path scatters, a kernel timer doesn't. Your signal-to-exit logging is the right instrument, and I'd log at handler entry as well as exit. That splits it into three signatures: no entry line means the signal never arrived (form/PID 1), entry but no exit means the handler itself blocks, entry plus a fast exit is healthy. One metric, and it tells you which of the three problems you actually have.
And yes — the clean-container test held in your six: the fast one was Postgres, whose entrypoint ends in exec. The database was the only one doing it right from the start, which is slightly embarrassing for the rest of us.
After you fixed the form, did your signal-to-exit drop to near zero — or did a blocking handler show up once the signal could finally arrive?
Both, and in that order. Once the signal could actually arrive, the fixed 10s disappeared; what surfaced next was a handler that blocked draining a connection pool, so the process kept living past the deadline - but now it exited on its own instead of being killed.
The useful framing: the fix converts an invisible timeout into a visible one. That is progress, but it moves the failure from "we cannot shut down" to "our shutdown budget is shorter than our slowest handler". The budget is the number worth writing down, and then asserting on it, so a handler that exceeds it fails a test instead of a deploy.
Both in that order is the cleanest answer you could've given — makes sense now. The signal arriving didn't fix the shutdown, it just moved the failure somewhere you could actually see it.
What I'd do with that handler is give the drain its own budget inside the grace period. Stop taking new work, drain with a hard deadline — say half the grace, the rest is exit time — and log how long each connection takes to drain, so the slow one has a name instead of the whole pool getting blamed. Then assert the whole shutdown finishes inside the budget in a test. A handler that runs long fails CI, not a deploy.
That's the bit I'd write down first — the drain budget, not the grace period. The grace is the kernel's number. The drain budget is yours.
The drain budget line is the one to keep: the grace period is the kernel's number, the drain is yours. I would push the derivation one step further, though - half the grace is a convention, and it can be half of the wrong number.
Derive the drain budget from the connection lifetime distribution instead: p99 connection lifetime, plus the time to finish one in-flight request. That is your budget. If it exceeds half the grace period, the finding is not "we need a bigger grace" - it is "some connections outlive a restart", which is a capacity or a timeout problem upstream, and a longer grace would only hide it.
The assertion worth writing is not just "shutdown finishes" but "no connection exceeds the drain budget", with one deliberately slow fixture that must fail loudly and name the handler. Without that fixture the test passes by inertia, which is how most shutdown tests end up passing.
Fair push — half the grace was a rule of thumb I threw out, and you're right that it can be half of the wrong number. Deriving it from the actual lifetimes is the honest version.
What I'd actually write down now: budget = p99 connection lifetime + one in-flight request, measured from the pool, not guessed. And the check that makes it real is the one you named — a deliberately slow connection in the test that has to fail loudly and name the handler. Without that fixture the test just passes quietly forever, which is the same failure in a nicer suit.
The part I like most is what the overrun turns into. If the budget comes out bigger than half the grace, that's not a reason to raise the grace — it's the pool telling you some connections outlive a restart. Shorten the lifetimes upstream, don't stretch the shutdown to cover them.
Did your p99 actually fit inside half the grace when you measured it, or was that the bit that surprised you?
The 10 seconds is Docker's default SIGKILL grace, so what you measured is really "how long does my app take to die after being asked nicely". Worth turning it into a budget: six containers means a full restart can cost up to 6 x grace in unavailable time, and if the orchestrator's health-check timeout is shorter than that, it declares the service dead mid-restart and starts the cycle again.
Two habits that help. Set stop_grace_period per service to just above its measured drain time - a queue consumer and a stateless API should not share one number. And add the sum to your deploy budget next to startup time, because that is the number your rollback actually spends.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.