What does the STOPSIGNAL instruction in a Dockerfile control, and when would you set it to something other than SIGTERM?

## What it sets `STOPSIGNAL <signal>` accepts a signal name (SIGQUIT) or number (3) and stores it in the image configuration. On a stop request the runtime sends that signal to the container's main process - PID 1 in the container's PID namespace - instead of the default SIGTERM. It can be overridden per container with `docker run --stop-signal`. ## The stop sequence `docker stop` sends the configured signal, then waits the stop timeout (default 10 seconds; `docker stop -t 30`, or bake a default with `--stop-timeout` at create time), then sends SIGKILL, which no process can catch or ignore. A container killed that way exits with code 137 (128 + 9). So the graceful window is entirely determined by the timeout, and any drain that takes longer than it will be cut short regardless of how well the application handles the signal. ## Why a different signal Applications are free to assign their own meanings. nginx: SIGTERM means fast shutdown - workers stop immediately and in-flight connections die - while SIGQUIT means graceful shutdown, finishing current requests before exiting. Apache httpd uses SIGWINCH for graceful stop. Some daemons reserve SIGTERM for an abrupt exit path. If you ship such a program, `STOPSIGNAL SIGQUIT` in the image makes every operator's `docker stop` do the graceful thing, without them having to remember a flag. ## The PID 1 trap Inside the container the main process is PID 1, and the kernel gives PID 1 special treatment: signals whose default action would terminate the process are *not* delivered unless the process has explicitly installed a handler for them. A plain program that never registers a SIGTERM handler will therefore ignore the stop signal completely, sit there until the timeout expires, and die by SIGKILL - no draining, no clean flush, and a ten-second delay on every deploy. The fix is either to install a handler in the application or to run a minimal init (tini, dumb-init, or `docker run --init`) as PID 1 that handles signals and forwards them. ## The shell-form trap If the entrypoint or command is written in shell form, the container's PID 1 is `/bin/sh -c "..."` and your application is a child. Most shells do not forward received signals to children, so the stop signal lands on the shell, your app never sees it, and again the container waits for SIGKILL. Exec form - a JSON array - makes your process PID 1 directly. If a wrapper script is unavoidable, end it with `exec "$@"` so the script is replaced by the real process. ## Diagnosing Symptoms of a mis-set or unhandled stop signal are consistent: every `docker stop` takes exactly the timeout, containers exit 137 rather than 0, and load balancers see dropped connections at deploy time. Check the configured value with `docker inspect --format '{{.Config.StopSignal}}' image`, then test: `time docker stop <c>` should return well under the timeout for a well-behaved container. Watch the application logs for its own shutdown messages to confirm the handler ran. ## Portability STOPSIGNAL is honored by Docker and Compose. Other platforms differ: Kubernetes has historically sent SIGTERM to containers regardless of the image setting, with per-container stop-signal configuration arriving only in recent versions and gated behind a feature stage. Treat the instruction as a good default for Docker-run workloads, and confirm the behavior on whatever runtime actually operates the container rather than assuming it carries over.