Mastering Graceful Docker Container Shutdown with Signals and ENTRYPOINT

1. Signals

Signals are a notification mechanism for processes in Linux, sometimes called software interrupts. Standard signals are numbered 1–31 and can be listed with

kill -l

. Common signals include:

SIGHUP

– sent when a terminal disconnects; often used to reload configuration in daemons.

SIGINT

– generated by Ctrl‑C ; default action terminates the process.

SIGQUIT

– generated by Ctrl‑\ ; terminates the process and creates a core dump.

SIGKILL

– cannot be caught or ignored; forces termination.

SIGTERM

– the default signal sent by

kill

,

killall

, or

pkill

; applications should handle it to clean up resources before exiting.

SIGTSTP

– sent by Ctrl‑Z to stop a job.

Note that Ctrl‑D does not send a signal; it signals EOF on stdin.

Processes can catch signals and run handler functions.

2. ENTRYPOINT and CMD

Both instructions specify the program that runs when a container starts. They each support two formats:

CMD ["executable","param1","param2"]

– exec form (recommended).

CMD command param1 param2

– shell form (runs via

/bin/sh -c

).

Similarly,

ENTRYPOINT

can be written in exec form or shell form. Using the shell form prevents signals from reaching the program because the command runs under

/bin/sh -c

, which does not forward signals. Consequently,

docker stop

(which sends SIGTERM) cannot be handled gracefully.

When the exec form is used,

docker stop

sends SIGTERM (default 10 s timeout) and then SIGKILL if the process does not exit.

<code>docker stop --help
Usage:  docker stop [OPTIONS] CONTAINER [CONTAINER...]
Options:
  --help       Print usage
  -t, --time int   Seconds to wait for stop before killing it (default 10)</code>

<code>docker kill --help
Usage:  docker kill [OPTIONS] CONTAINER [CONTAINER...]
Options:
  --help       Print usage
  -s, --signal string   Signal to send to the container (default "KILL")</code>

3. Examples

3.1 Simple Go Signal Handler

<code>package main
import (
    "fmt"
    "os"
    "os/signal"
    "syscall"
)
func main() {
    sigs := make(chan os.Signal, 1)
    done := make(chan bool, 1)
    signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
    go func() {
        sig := <-sigs
        fmt.Println()
        fmt.Println(sig)
        done <- true
    }()
    fmt.Println("awaiting signal")
    <-done
    fmt.Println("exiting")
}
</code>

Dockerfile (exec form):

<code>FROM busybox
COPY signals /signals
CMD ["/signals"]
</code>

Running the container and stopping it with

docker stop

yields a graceful shutdown (~0.73 s).

Changing

CMD

to shell form (

CMD /signals

) prevents signal delivery, causing a forced stop after the default 10 s timeout.

3.2 Shell Script Wrapper

Even with exec‑form

CMD

, using a shell script as the entrypoint blocks signal propagation unless the script itself uses

exec

:

<code># start.sh
#!/bin/sh
exec /signals   # replace shell with the Go binary
</code>

After rebuilding the image with this script,

docker stop

again shuts down gracefully (~0.74 s).

Conclusion: To achieve graceful container termination, always use the exec form for

ENTRYPOINT

and

CMD

, and ensure any wrapper scripts also invoke

exec

so that signals reach the actual process.