Skip to main contentClaim $5 in free credit — one-time, per account. Claim $5 free
Krova CloudKrova Cloud
CI/CD & DevOps

Docker Stop Timeout: Check the Signal Path Before Adding Seconds

A longer Docker stop timeout won’t fix a signal that never reaches the worker. Inspect the launch path, observe shutdown and verify what happens to in-flight jobs.

RB
Rohit Bhadani6 min read
Share
CI/CD & DevOps cover: Docker Stop Timeout, Check the Signal Path, with a shutdown-delay subtitle and frosted-glass application, signal tile and clock.

Imagine a worker that processes reports without complaint all afternoon. Every deployment is different: the release waits, the old container eventually disappears, and one report needs investigating. You’re about to increase Docker’s stop timeout. Before adding seconds, find out what the application does with the seconds it already has.

Check whether the stop signal reaches the application and starts a bounded shutdown. Extend the grace period only when observed, legitimate cleanup needs more time. Docker’s stop command signals the container’s main process, using SIGTERM unless another stop signal is configured. If it doesn’t exit before the timeout, Docker sends SIGKILL.

That creates three different jobs for the operator: establish the signal receiver, inspect the application’s shutdown path, and verify what happens to work in flight. The report worker here is hypothetical. This walkthrough covers Docker Engine on a self-managed Linux instance, including Docker you operate inside a Krova Cube; it does not describe Kubernetes or Swarm rollout guarantees.

Follow the process, not just the Dockerfile

Start with the exact running container and the artifact that created it. Runtime entrypoint overrides can make the image’s Dockerfile an incomplete description. Use an account already authorized to access the intended Docker daemon, and replace the example container name below.

target=report-worker

docker inspect --type container --format \
'id={{.Id}} image={{.Image}} path={{.Path}} args={{json .Args}} stop_signal={{json .Config.StopSignal}}' "$target"

docker top "$target"

docker inspect supports selecting fields with a format template; docker top lists the running processes. Retain the container ID, image identity and deployment version together. Command arguments can contain secrets, so keep the output restricted and redact it before sharing. The default process listing may use host-side PIDs; don’t label the first numeric PID “PID 1 inside the container” without checking its namespace.

Read the launched path, arguments and process tree together. Is the main process your worker, a shell wrapper, or a supervisor that is supposed to forward signals? A supervisor can be intentional. The question is whether the documented stop signal reaches the process that owns the report.

Docker’s Dockerfile reference warns that shell-form ENTRYPOINT starts the executable beneath /bin/sh -c, which does not pass the stop signal to that executable in the documented case. The worker can keep running while Docker waits for a different process to exit.

Make a single-process launch explicit

If the image starts one foreground executable and doesn’t need a wrapper, an exec-form entrypoint makes the intended launch clear. This fragment assumes that /app/bin/report-worker already exists in your image:

ENTRYPOINT ["/app/bin/report-worker"]

If a wrapper performs required setup first, the final launch can replace the shell with that executable. For example, after the wrapper’s existing setup succeeds:

exec /app/bin/report-worker "$@"

The exec pattern follows the upstream entrypoint guidance. It changes the process arrangement; it does not implement the worker’s signal handler, drain a queue or commit a report. Don’t paste it into a script that intentionally manages several processes, a background job or a pipeline without reviewing who must receive signals and reap children.

For our hypothetical worker, an entrypoint repair is justified only if the evidence shows that a wrapper prevented the intended signal delivery. If the worker already logs that shutdown started, investigate the work after that point instead of rebuilding the image merely to change syntax.

Turn shutdown into an observable application operation

Use the application’s documented shutdown interface. For a report worker, define what should happen when shutdown begins: stop acquiring new jobs, finish the current bounded operation or durably hand it off, close resources, then exit. These are design recommendations, not promises Docker supplies.

Add narrow operational records around the transitions you need to verify: shutdown requested, acquisition stopped, active job completed or handed off, and shutdown finished. Keep the container or instance identity and a non-secret job identifier with those records. A missing record remains an evidence gap: a handler may not have run, or logging may have failed. Correlate it with the process arrangement and durable job state.

There is no universal safe grace period. A worker that is closing a connection differs from one waiting for an external request that has no deadline. Measure the shutdown interval under representative work and check whether its dependency waits are bounded. A longer wait can be reasonable when useful cleanup progresses; it only delays the same outcome when cleanup can hang indefinitely.

Observation during a controlled stopNext decision
No shutdown-start evidence; shell or supervisor sits above the workerVerify forwarding and the application’s expected signal before changing the timeout.
Shutdown starts and finite cleanup completes just beyond the current allowanceEvaluate a longer allowance against the release’s own deadline.
Shutdown starts but an external operation never finishesBound or recover that operation; more waiting alone doesn’t establish safety.
Container exits promptly but the report is missing or duplicatedInspect commit, acknowledgement and retry behavior; fast exit is not proof of correct work.

Rehearse an idle stop and a busy stop

Use a disposable instance with a separate queue or test input, credentials and output destination. Confirm it cannot consume production jobs. Keep the old artifact and configuration available for rollback. The following command deliberately stops a container; run it only against that verified rehearsal target.

target=report-worker-rehearsal
TZ=Asia/Kolkata date -Is
docker stop --timeout 30 "$target"
TZ=Asia/Kolkata date -Is

docker inspect --type container --format \
'id={{.Id}} status={{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}} finished={{.State.FinishedAt}}' "$target"
docker logs --tail 100 "$target"

Thirty seconds is an illustrative test allowance, not a recommended production setting. Docker documents --timeout as the wait before forcible termination. The timestamps bracket the command, including client and daemon work; use application records to distinguish that elapsed time from the worker’s cleanup duration. Preserve logs and state before removing or replacing the container.

  1. Stop an idle rehearsal worker. Check that it begins shutdown and exits without accepting more work.
  2. Stop it during a disposable representative report. Verify the final report or the documented durable handoff, not just the container status.
  3. In a separate disposable test, exercise the application’s documented interrupted-work recovery path. Verify that a replacement worker produces the intended result without an unintended duplicate side effect.

The third check matters because graceful shutdown can be interrupted by a host failure or an exhausted timeout. Retrying a report is safe only if the application’s state and side effects make it safe. Docker stopping a process does not establish exactly-once processing.

If the rehearsal ends with exit code 137, don’t call it an out-of-memory failure from the number alone. Krova’s exit-137 diagnostic covers the separate task of correlating state, events and memory evidence. Likewise, a health-check failure and a process exit are different events; see the running-but-unhealthy guide.

Close the deployment check with a short record: the container and artifact, intended stop signal, evidence that shutdown began, measured cleanup, chosen allowance, and the verified report or recovery outcome. That gives you a reason for the timeout and a useful comparison when the worker changes.

Rehearse the worker’s shutdown on a Cube

Run your own Docker workload in a self-managed Linux environment. Keep test work separate and verify the signal path and job outcome before changing production.

Creation context: This AI-assisted article uses a hypothetical worker and linked primary documentation checked on 22 November 2026. The code and rehearsal are illustrative and were not executed for this article. No personal testing or human approval by the bylined author is claimed. The cover is an AI-generated conceptual illustration.

For AI agents:llms.txtsitemap

Related posts