Docker stop signals are part of the container’s controlled shutdown path. A stop request normally sends the configured signal to the container’s main process and later forces termination if it does not exit within the allowed grace period. The application must participate in that lifecycle; an image alone cannot make arbitrary work stop safely.
A reliable shutdown design explains which process receives the signal, how it handles unfinished work, and what happens if the deadline expires. This guide covers startup form, PID 1 behavior, forwarding, and recovery without assuming every process responds like an interactive shell command.
Identify the actual main process
Inspect the image configuration and runtime process tree. The process running as PID 1 is the main signal target in the container. It may be the application, a shell wrapper, or a small init process depending on startup design.
Do not infer the process tree from the Dockerfile’s intended command alone. An entrypoint script can launch another process without replacing itself. Runtime overrides can also change the observed behavior.
Record the command and arguments for the deployed image. A local test using a different entrypoint does not validate production shutdown. The relevant evidence is the process that actually owns the container’s lifetime.
Prefer explicit startup and forwarding behavior
Exec-form instructions avoid an unnecessary shell layer for supported direct execution. When a wrapper is required, use its supported approach to replace itself with the application or deliberately forward signals and manage children.
A shell-form entrypoint can leave the application as a child rather than the direct PID 1 target. Do not assume every wrapper forwards the stop signal correctly. Test the complete image rather than only the application’s signal handler.
Keep argument handling safe. Startup refactoring should not replace a structured argument list with uncontrolled shell interpolation. Correct signal behavior and safe command construction are separate requirements that must both survive the change.
Review PID 1 responsibilities
Linux treats PID 1 specially in relevant signal and child-process behavior. An application may need explicit signal handling, and orphaned child processes need appropriate reaping. These responsibilities matter when the workload launches subprocesses.
Docker’s supported init option can help with signal forwarding and reaping in suitable cases. It does not implement the application’s business shutdown policy or guarantee that every child completes its work.
Avoid adding a large process supervisor by default when a simple direct process or small init mechanism meets the need. Choose the smallest supported design that correctly owns the process tree and lifecycle.
Choose the signal from application documentation
STOPSIGNAL can specify the signal Docker should use for the image’s stop path. A different signal is useful only if the application documents its meaning and behavior. Do not select a signal because another service uses it.
Review runtime or orchestration overrides and platform differences. The effective stop behavior can come from more than one layer. Confirm the deployed configuration and supported defaults for the actual environment.
Test what the application does on that signal. Some signals mean reload, immediate termination, or another action rather than graceful shutdown. A correct name in configuration is not proof that the process interprets it as intended.
Make the grace period a real work budget
The stop timeout gives the process time before forced termination. Choose it from realistic shutdown work, connection draining, and the platform’s overall termination budget. An arbitrarily long timeout can delay recovery and maintenance.
The application should stop accepting new work, finish or relinquish existing work according to policy, and release resources. Define the order so a shutdown does not keep extending itself by taking new requests indefinitely.
Test the longest supported in-flight operation. A quiet process exiting in milliseconds tells little about a busy worker committing a transaction or uploading a result. Bound the work and its external calls deliberately.
Keep unfinished work recoverable
A graceful signal does not guarantee every task completes before the deadline. Persist required progress and make repeated processing safe where the workflow needs it. Forced termination should not erase the only record of a required job.
Review the boundary between an external side effect and recording completion. A process can be terminated after the external action succeeds but before local status is updated. Recovery needs a reconciliation or idempotency strategy for that case.
Use appropriate database transactions and resource cleanup, but do not claim finally blocks always run. Forced termination and machine failure can bypass normal cleanup. Durable state is the recovery authority.
Test forwarding, children, and deadlines
Run a representative container in an approved environment, start realistic work, and request normal stop. Record which process receives the signal, how children behave, and the final exit status and job state.
Repeat with a deliberately slow or unresponsive task to observe the forced-termination path. Verify that another worker can recover unfinished work safely. Keep these failure tests scoped to nonproduction or explicitly approved workloads.
Check for orphaned or zombie processes where the application launches children. A successful main-process exit does not validate long-running process management during normal operation. Inspect the lifecycle rather than only one terminal message.
Observe shutdown without exposing private work
Log nonsecret lifecycle events such as draining started, owned work remaining, and cleanup completed. Avoid dumping complete requests or credentials when diagnosing termination. Useful timestamps and controlled job identifiers are usually enough.
Monitor forced kills, long shutdowns, duplicate recovery attempts, and lost-work indicators. A container’s stopped state is an infrastructure result, not a business-completion metric. Keep those outcomes separate.
For an export worker, stop claiming jobs on the signal, allow a bounded current export to finish, and leave durable unfinished state if the deadline expires. Test both paths before using faster deployments as evidence of safe shutdown.
Frequently asked questions
Does exec form guarantee graceful shutdown?
No. It helps process targeting, while the application still needs supported signal and work-handling behavior.
Will cleanup always run before a forced kill?
No. Recovery must account for termination that bypasses ordinary cleanup.
Where are image signal settings documented?
Read the Dockerfile reference for ENTRYPOINT, CMD, and STOPSIGNAL behavior in your supported environment.
For a complementary workflow, read Python Subprocess Safety: Arguments and Authority.
