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.

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)

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

3. Examples

3.1 Simple Go Signal Handler

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")
}

Dockerfile (exec form):

FROM busybox
COPY signals /signals
CMD ["/signals"]

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:

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

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.