Q: You run a shell script as the ENTRYPOINT that spawns multiple background worker processes. When you `docker stop` the container, it always takes exactly 10 seconds (the timeout) before stopping, and the workers don't clean up properly. What is the root cause?
When Docker sends SIGTERM via docker stop, it delivers the signal to PID 1 inside the container. If PID 1 is a shell script (/bin/sh or /bin/bash), the shell does NOT forward signals to its child processes by default.
exec in entrypoint scripts.. I structure my answer around systematic triage first, root cause analysis second, and permanent remediation third.""
Want to master this scenario in a live sandbox? KodeKloud's Docker Certified Associate (DCA) Hands-On Lab Course covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: "In an interview, I explain how we diagnosed container runtime failures without guessing. The interviewer is testing: Signal handling, PID 1 behavior, exec in entrypoint scripts.. I structure my answer around systematic triage first, root cause analysis second, and permanent remediation third."
Initial Diagnostics & Root Cause Analysis
When Docker sends SIGTERM via docker stop, it delivers the signal to PID 1 inside the container. If PID 1 is a shell script (/bin/sh or /bin/bash), the shell does NOT forward signals to its child processes by default. The shell itself ignores SIGTERM, so nothing happens for 10 seconds until Docker sends SIGKILL.
- Use
execto replace the shell with the main process: the last line of your entrypoint script should beexec ./my-workerinstead of./my-worker. This makes the worker PID 1 and it receivesSIGTERMdirectly. - Trap signals in the shell script if you must manage multiple processes:
- Use
--initflag (docker run --init) to injecttinias PID 1, which properly forwards signals and reaps zombie processes.
Remediation & Permanent Safeguards
*Fixes:*
#!/bin/bash
trap 'kill $(jobs -p); wait' SIGTERM SIGINT
./worker1 &
./worker2 &
wait
- Use exec to replace the shell with the main process: the last line of your entrypoint script shou...
- Trap signals in the shell script if you must manage multiple processes:
- Use --init flag (docker run --init) to inject tini as PID 1, which properly forwards signals and ...
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
-
Structuring Dockerfile instructions inefficiently by copying app source before package manifests when configuring shell script ENTRYPOINT
Copying code before package manifests (
package.json,go.mod,requirements.txt) invalidates the build cache on every commit, forcing slow full reinstalls. -
Neglecting the PID 1 process reap problem and omitting proper SIGTERM signal forwarding when configuring shell script ENTRYPOINT
If an application runs as PID 1 without an init system (like
tini), it fails to reap zombie child processes and ignoresSIGTERMsignals, causing unclean 10s timeouts. - Assembling single-stage images containing compilers, build SDKs, and header files in production when configuring shell script ENTRYPOINT Single-stage builds bloat image size by gigabytes and expose extensive package vulnerabilities; multi-stage builds isolate artifacts into minimal distroless images.
- Confusing container port forwarding on bridge networks with unisolated host networking mode when configuring shell script ENTRYPOINT Bridge networking utilizes iptables NAT translations which add latency overhead, whereas host networking bypasses the network namespace entirely.