Huny's Dev Blog
huny.dev

Fix Docker SIGTERM Delivery with an Exec-Form ENTRYPOINT and Shell exec

Reproduce how shell exec changes PID identity and SIGTERM delivery, preserve arguments in startup scripts, and distinguish local tests from container shutdown verification.

Hun Jang
Hun Jang Nov 21, 2026

If a server in a Docker container never receives its shutdown signal, check both the Dockerfile's JSON form and the final exec "$@" in its startup script. In a Linux container that initializes once and then runs one server, replacing the shell with the server lets the signal reach the server directly. This article reproduces the PID and SIGTERM behavior in Bash and identifies the shutdown conditions that still need verification in a real container.

A conceptual illustration of a translucent shell peeling away from a server so a signal reaches the server directly. This is not an exact process diagram.

Written and documentation checked on 2026-11-21. The reproduction environment was Linux x86_64, GNU Bash 5.2.37, and Python 3.12.14. Docker daemon builds, container stops, and PID 1 behavior were outside this verification.

Check the signal target before the shutdown handler

If a server has a SIGTERM handler but produces no shutdown log, first distinguish whether the signal actually reaches it. According to the Docker stop documentation, stopping sends the configured signal to the container's main process and forcibly terminates it with SIGKILL if it does not exit within the timeout. SIGTERM is the initial signal when no alternative is configured.

Even with ENTRYPOINT ["/app/entrypoint.sh"], the shell can remain the parent if the script runs the server as an ordinary command. Docker's JSONArgsRecommended explanation covers signal delivery problems with shell form and the reason to prefer exec form. Check the Dockerfile syntax and the script's execution method separately.

Execution method
Process relationship to inspect
What to check
Run the server with shell form
A shell may remain the server's parent
Is there an implicit shell?
Run a script with JSON form, then run an ordinary command inside
The server may sit beneath the script's interpreter shell
What is the script's final command?
Run a script with JSON form and finish with exec
A successful exec replaces the shell with the server
Does the replacement program handle shutdown signals?

exec is not a signal-forwarding proxy. As specified in the Bash exec documentation, it replaces the current shell with the specified program without creating a new process. The PID stays the same while the running program changes.

Replace the final server launch with exec

The following startup script is intended for integration into an existing image. Perform any required initialization before the last line. The script must receive at least one argument specifying the command to run.

Use a Dockerfile configuration such as the following. Replace /app/server and its options with a server command that actually exists in the image, and ensure the script is executable. These two lines are an integration snippet, not a complete image build example.

"$@" preserves each argument it receives. Do not substitute $* or unquoted $@. The script was checked locally with /bin/sh for syntax, exit code 64 when the command is missing, and preservation of the argument a b and a literal *.

Shell cleanup placed after exec will not run after a successful replacement. If the design relies on a shell EXIT trap to clean up after the server, first decide whether to move that responsibility into the application or an explicit supervisor.

Reproduce the PID and SIGTERM difference without Docker

Save the following as exec_signal_demo.py and run python3 exec_signal_demo.py. It uses Linux, Bash, and the Python standard library. The worker prints its PID only after installing its handler. After receiving that readiness signal, the driver sends SIGTERM to the single PID launched by Popen. Sending it to the entire process group would conceal this difference.

The path without exec includes commands that handle the exit status afterward, keeping the shell present. Shells can optimize a final command depending on the shell and command form, so do not assume that every shell always builds the same tree.

The actual output was as follows. PID equality is printed instead of numeric PIDs to remove values that vary between runs.

In the first path, worker received SIGTERM does not mean the signal sent to the wrapper was forwarded. It comes from the cleanup signal sent directly to the worker PID after the driver checks that the worker is still alive. The wrapper's -15 is Python Popen's representation of termination by SIGTERM; do not confuse it with a shell's $? notation. In the second path, the worker already occupies the same PID, receives the initial signal, and exits with code 0.

This reproduction uses ordinary host processes. It does not reproduce container PID 1 default signal behavior or cleanup of an entire container. For the separate issue of processes producing large amounts of output, see the existing article on Python subprocess pipe deadlocks and communicate.

What still needs checking in a real deployment

The following is a verification procedure for an actual image, not a result of the experiment above.

  1. Inspect the final image's ENTRYPOINT and CMD and the running process tree. Host PIDs and container-internal PIDs differ, so do not assume they have the same number.
  1. Confirm that the server explicitly handles SIGTERM and emits shutdown logs. Adding exec does not implement request draining or persistence completion.
  1. Check the environment's stop signal and timeout before stopping it. Verify both signal receipt and the intended behavior for in-flight requests, queued work, and file writes.
  1. Record forced termination and the application's exit code together. Slow shutdown can also result from ongoing work or blocked I/O, rather than a missing signal.

A final exec fits a design that initializes once and then runs one server. If several long-running processes are started in the background, design signal forwarding, child reaping, and failure propagation together. The process management examples in the Dockerfile ENTRYPOINT documentation are also useful. Account for PID 1 responsibilities such as reaping children.

The verified scope here covers PID relationships, SIGTERM receipt and exit codes for two Bash execution paths, plus argument preservation in the startup script. Graceful shutdown in Docker, Kubernetes, or a real HTTP server, and performance figures, were not tested.

한국어 버전: Docker 종료 신호가 서버에 닿지 않을 때: ENTRYPOINT와 exec로 SIGTERM 전달하기Docker 종료 신호가 서버에 닿지 않을 때: ENTRYPOINT와 exec로 SIGTERM 전달하기

추천 글