Any process executed by docker run must handle a signal itself to receive that signal.

Alternatively use the --init flag to run the tini init as PID 1 which will handle and forward signals for you.

The sh shell can also be injected as the PID 1 process in the container, depending on how the command (CMD) is specified.

Detail

A SIGTERM is propagated by the docker run command to the Docker daemon by default but it will not take effect unless the signal is specifically handled in main process being run by Docker.

The first process you run in a container will have PID 1 in that containers PID namespace. This process is treated as a special process by the linux kernel. It will not be sent a signal unless the process has a handler installed for that signal. It is also PID 1's job to forward signals onto other child processes.

docker run and other commands are API clients for the Docker Remote API hosted by the docker daemon. The docker daemon runs as a seperate process and is the parent for the commands you run inside a container context. This means that there is no direct sending of signals between docker run and the daemon, in the standard unix manner.

The docker run and docker attach commands have a --sig-proxy flag that defaults signal proxying to true. You can turn this off if you want.

docker exec does not proxy signals.

In a Dockerfile, be careful to use the "exec form" when specifying CMD and ENTRYPOINT defaults, if you don't want sh to become the PID 1 process (Kevin Burke):

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

Signal Handling Go Example

Using the sample Go code here: https://gobyexample.com/signals

Run a regular process that doesn't handle signals in the background. Then the example Go daemon that traps signals also in the background. I'm using sleep for the process that doesn't install "daemon" signal handlers.

$ docker run busybox sleep 6000 &
$ docker run gosignal &

With a ps tool that has a "tree" view, you can see the two distinct process trees. One for the docker run process under sshd. The other for the actual container processes, under docker daemon.

$ pstree -p
init(1)-+-VBoxService(1287)
        |-docker(1356)---docker-containe(1369)-+-docker-containe(1511)---gitlab-ci-multi(1520)
        |                                      |-docker-containe(4069)---sleep(4078)
        |                                      `-docker-containe(4638)---main(4649)
        `-sshd(1307)---sshd(1565)---sshd(1567)---sh(1568)-+-docker(4060)
                                                          |-docker(4632)
                                                          `-pstree(4671)

The details of docker hosts processes:

$ ps -ef | grep "docker r\|sleep\|main"
docker    4060  1568  0 02:57 pts/0    00:00:00 docker run busybox sleep 6000
root      4078  4069  0 02:58 ?        00:00:00 sleep 6000
docker    4632  1568  0 03:10 pts/0    00:00:00 docker run gosignal
root      4649  4638  0 03:10 ?        00:00:00 /main

Killing

I can't kill the docker run busybox sleep command:

$ kill 4060
$ ps -ef | grep 4060
docker    4060  1568  0 02:57 pts/0    00:00:00 docker run busybox sleep 6000

I can kill the docker run gosignal command, that has launched the go process with the signal handlers:

$ kill 4632
$ 
terminated
exiting

[2]+  Done                       docker run gosignal

Signals via docker exec

If I docker exec a new sleep process in the already running sleep container, I can send an ctrl-c and interrupt the docker exec itself, but that doesn't forward to the actual process:

$ docker exec 30b6652cfc04 sleep 600
^C
$ docker exec 30b6652cfc04 ps -ef
PID   USER     TIME   COMMAND
    1 root       0:00 sleep 6000   <- original
   97 root       0:00 sleep 600    <- execed still running
  102 root       0:00 ps -ef

Because Docker containers have no init process, the Python process is running at PID 1. According to man 2 kill,

The only signals that can be sent to process ID 1, the init process, are those for which init has explicitly installed signal handlers. This is done to assure the system is not brought down accidentally.

The reason why SIGINT works is because Python registers a handler for that signal. So, you can do something similar:

#!/usr/bin/env python3

import signal

def handler(signum, frame):
    print('Exiting')
    exit(0)

if __name__ == '__main__':
    signal.signal(signal.SIGTERM, handler)
    while True:
        pass

Alternatively, you can tell Docker to run the container with an init process:

docker run -it --init my_image

You need to make sure the main container process is your actual application, and not a shell wrapper.

As you have the CMD currently, a shell invokes it. The argument list $@ will always be empty. The shell parses /repo/run_api.sh and sees that it's followed by a semicolon, so it might need to do something else. So even though your script correctly ends with exec gunicorn ... to hand off control directly to the other process, it's still running underneath a shell, and when you docker stop the container, it goes to the shell wrapper.

The easiest way to avoid this shell is to use an exec form CMD:

CMD ["/repo/run_api.sh"]

This will cause your script to run directly, without having a /bin/sh -c wrapper invoking it, and when the script eventually exec another process, that process becomes the main process and will receive the docker stop signal.

Actually, your Dockerfile and start.sh entrypoint script work as is for me with Ctrl+C, provided you run the container with one of the following commands:

• docker run --name tmp -it tmp
• docker run --rm -it tmp

Documentation details

As specified in docker run --help:

• the --interactive = -i CLI flag asks to keep STDIN open even if not attached
  (typically useful for an interactive shell, or when also passing the --detach = -d CLI flag)
• the --tty = -t CLI flag asks to allocate a pseudo-TTY
  (which notably forwards signals to the shell entrypoint, especially useful for your use case)

Related remarks

For completeness, note that there are several related issues that can make docker stop take too much time and "fall back" to docker kill, which can arise when the shell entrypoint starts some other process(es):

• First, when the last line of the shell entrypoint runs another, main program, don't forget to prepend this line with the exec builtin:
  exec prog arg1 arg2 ...
• But when the shell entrypoint is intended to run for a long time, trapping signals (at least INT / TERM, but not KILL) is very important;
  {see also this SO question: Docker Run Script to catch interruption signal}
• Otherwise, if the signals are not forwarded to the children processes, we run the risk of hitting the "PID 1 zombie reaping problem", for instance
  {see also this SO question for details: Speed up docker-compose shutdown}

I can reproduce the issue you raise, while it does not show up when I replace the base image with debian:10, for example.

It happens the issue is not due to alpine but to the gitlab/gitlab-runner:alpine image itself, namely this Dockerfile contains the following line:

STOPSIGNAL SIGQUIT

To be more precise, the line above means docker stop will send a SIGQUIT signal to the running containers (and wait for a "graceful termination time" before killing the containers, as if a docker kill were issued in the end).

If this Dockerfile directive is not used, the default signal sent by docker stop is SIGTERM.

Beware that SIGKILL would be a very poor choice for STOPSIGNAL, given that the KILL signal cannot be trapped.

So, your first example should work if you use the following line:

trap deregister_runner SIGINT SIGQUIT SIGTERM

This way, your cleanup function deregister_runner will be triggered anytime you issue a docker stop, or use the Ctrl-C keybinding (thanks to SIGINT).

Finally, two additional notes related to this question of Docker, bash and signals:

• The "graceful termination time" (between stop and kill) can be customized, and there are some pitfalls when using a Bash entrypoint (regarding the "signal propagation"). I explained both issues in more detail in this SO answer: Speed up docker-compose shutdown.

• Beware that in many alpine images, bash is not pre-installed, e.g.:

  $ sudo docker run --rm -it alpine /bin/bash
    /usr/bin/docker: Error response from daemon: OCI runtime create failed:
    container_linux.go:346: starting container process caused
    "exec: \"/bin/bash\": stat /bin/bash: no such file or directory": unknown.
  

  (fortunately, this was not the case of gitlab/gitlab-runner:alpine, which indeed contains the bash package :)