Break/Fix 6: Container takes 10 seconds to stop (SIGTERM-ignoring PID 1)

Reported symptoms

●`docker stop CONTAINER` blocks for 10 seconds before the container exits.
●Rolling deploys are slow; the previous container hangs in Stopping state.
●In-flight requests are hard-killed mid-flight.

Evidence

· `docker inspect CONTAINER --format "{{.Path}}"` shows a shell or unhandled entrypoint.
· No SIGTERM handler is installed (or `exec` was not used).

Diagnosis and resolutionclick to reveal

Root cause

The container's PID 1 ignores SIGTERM. The Linux kernel exempts PID 1 from default-signal termination; without an installed handler, SIGTERM is dropped. After `--stop-timeout` (10 s default), the daemon sends SIGKILL.

Remediation

Use `--init` (Docker injects tini as PID 1) or bake tini into the image's ENTRYPOINT. For shell-based entrypoints, replace with `exec` so the application receives PID 1 directly.

Verification

`docker stop CONTAINER` returns in <1 second. `docker inspect` shows the container exited cleanly. The previous container finishes its graceful shutdown before the new one starts.

Prevention

Author Dockerfiles so PID 1 is the application process (use `CMD ["app", ...]`, not shell wrappers). For shell scripts, `exec` the application. For interpreted languages, ensure the entrypoint installs SIGTERM handlers.

Diagnosis

Time the stop:

time docker stop my-container

10 seconds confirms the symptom.

Inspect the entrypoint:

docker inspect my-container --format '{{.Path}}'
docker inspect my-container --format '{{json .Config.Cmd}}'

A shell (/bin/sh) or a script that doesn’t exec is the most common cause.

Fix

docker run --init --name my-container -d myorg/app:1.0.0

Or rebuild the image with tini baked in:

COPY --from=ghcr.io/krallin/tini:latest /usr/local/bin/tini /sbin/tini
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["python3", "/app/server.py"]

Verify

time docker stop my-container
# real    0m0.532s