4.2.7.4 ENTRYPOINT Signal Handling

ENTRYPOINT signal handling concerns whether the process Docker considers a container's main process correctly receives termination signals like SIGTERM, which depends heavily on whether ENTRYPOINT is written in exec form or shell form, and whether any wrapper script correctly forwards signals to the actual application.

Exec Form Delivers Signals Directly

When ENTRYPOINT is written in exec form, the specified program becomes the container's actual main process, directly receiving any signal sent to the container.

ENTRYPOINT ["python", "app.py"]

docker stop myapp

This sends SIGTERM directly to the python process, giving an application written to handle that signal the opportunity to shut down gracefully.

Shell Form Can Interfere With Signal Delivery

When ENTRYPOINT is written in shell form, the shell itself becomes the main process, and depending on the shell's own signal handling behavior, the actual application running as its child process may not receive the signal promptly, or at all.

ENTRYPOINT python app.py

docker stop myapp

Depending on the shell in use, this may result in the container only stopping after the full timeout period elapses and Docker sends SIGKILL, rather than the application shutting down gracefully in response to SIGTERM.

Entrypoint Scripts Must Forward Signals Correctly

When the entrypoint is a custom script, using exec to launch the actual application replaces the script's own process with the application, ensuring the application receives signals directly rather than relying on the script to forward them.

#!/bin/sh
exec "$@"

#!/bin/sh
"$@"

The first correctly hands off process identity (and signal reception) to the application; the second leaves the script process running as a parent, potentially delaying signal delivery to the actual application underneath it.

Verifying Correct Signal Handling

Testing that a container shuts down promptly and gracefully, rather than waiting for the full stop timeout, is a direct way to confirm signal handling is configured correctly.

time docker stop myapp

Why This Matters

Correct signal handling directly affects how quickly and gracefully containers shut down during deployments, scaling operations, or routine restarts — getting this wrong can mean unnecessarily slow or abrupt shutdowns that risk incomplete cleanup or dropped in-flight work.