Docker containers on Linux default to a 10-second wait period after sending a SIGTERM signal to the main process. If the process does not terminate within this timeframe, Docker issues a SIGKILL signal, which cannot be intercepted, often resulting in an exit code of 137.
The issue often arises when a shell script is used as the entry point, making the shell the PID 1 process. Because the shell does not forward signals to its child processes, the application remains unaware of the termination request. Using the exec command in shell scripts or avoiding shell-form CMD instructions ensures the application becomes PID 1.
Even when the application is PID 1, it may ignore SIGTERM by default, as Python does not register a handler for this signal. Developers can use the init: true configuration in Docker Compose to forward signals, but this does not guarantee graceful shutdown, as the process may still exit abruptly without completing pending database transactions.
To ensure data integrity, developers should implement a signal handler that sets a flag, allowing the worker to finish the current batch of work before exiting. Additionally, adjusting the stop_grace_period in Docker Compose is recommended for tasks that exceed the default 10-second limit, ensuring the container has sufficient time to complete operations.
