How to Gracefully Shut Down Docker Containers Using Signals, ENTRYPOINT, and CMD

1 Signals

Signal is a notification mechanism for processes, sometimes called a software interrupt.

Linux defines standard signals numbered 1‑31, which can be listed with kill -l. Commonly used signals include: SIGHUP – sent when a terminal disconnects; often used to tell daemons to reload configuration. SIGINT – generated by Ctrl‑C ; default action terminates the process. SIGQUIT – generated by Ctrl‑\ ; terminates the process and produces a core dump. SIGKILL – uncatchable, unignorable kill signal that always terminates a process. SIGTERM – the default termination signal used by kill, killall and pkill; well‑behaved programs should handle it to clean up resources before exiting. SIGTSTP – sent by Ctrl‑Z to stop a foreground job.

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

2 ENTRYPOINT, CMD

Both instructions specify the program that runs when a container starts. Each has two syntaxes: exec form (recommended) and shell form.

Exec form runs the program directly, preserving the process ID and allowing signals to be delivered: CMD ["executable","param1","param2"] Shell form runs the command via /bin/sh -c, which creates an intermediate shell that does not forward signals to the actual program: CMD command param1 param2 The same applies to ENTRYPOINT:

ENTRYPOINT ["executable","param1","param2"]

ENTRYPOINT command param1 param2

When a container is stopped with docker stop, Docker sends SIGTERM (and after a timeout, SIGKILL). If the program is started via the shell form, it never receives the signal, resulting in a forced termination.

3 Examples

3.1 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 using 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) because the Go program receives SIGTERM and exits cleanly.

Changing CMD to the shell form ( CMD /signals) prevents signal delivery; docker stop then waits the full timeout (≈10.7 s) before forcing termination with SIGKILL.

3.2 Shell script wrapper

If the container starts a shell script, the script must use exec to replace the shell with the actual program, otherwise signals are still lost.

# start.sh
#!/bin/sh
exec /signals   # forward signals

Dockerfile:

FROM busybox
COPY signals /signals
COPY start.sh /start.sh
CMD ["/start.sh"]

With the exec added inside the script, docker stop again shuts down the container in under a second.

These examples demonstrate that using the exec form for ENTRYPOINT or CMD, and ensuring any wrapper scripts also use exec, are essential for graceful container shutdown.