Course contentsShow
← Cloud and Infrastructure
Lesson 1016 of 2,98920. Docker in DepthFree lesson

STOPSIGNAL: Graceful Shutdown

Understand STOPSIGNAL instruction for customizing signal sent to container during stop operations.

STOPSIGNAL: Graceful Shutdown

What you'll learn: How to customize the signal Docker sends to your container when it's time to stop, ensuring your application shuts down cleanly.

The Problem with Hard Stops

When you stop a container, Docker needs to tell the main process inside to shut down. By default, Docker sends a SIGTERM signal (signal 15), waits 10 seconds, then forcefully kills the process with SIGKILL if it's still running. But not all applications respond to SIGTERM—some expect different signals to initiate their graceful shutdown routines.

What STOPSIGNAL Does

The STOPSIGNAL instruction lets you override Docker's default stop signal. You specify which signal your application expects, and Docker will send that instead when the container stops.

Syntax:

STOPSIGNAL signal

The signal can be an unsigned number (like 9 or 15) or a signal name (like SIGTERM or SIGQUIT).

When You Need This

  • Legacy applications that listen for signals other than SIGTERM
  • Database containers that require specific shutdown signals to flush data safely
  • Custom daemons with non-standard signal handlers

Example

FROM nginx:latest
STOPSIGNAL SIGQUIT

This tells Docker to send SIGQUIT instead of SIGTERM when stopping the container. NGINX, for instance, handles SIGQUIT for graceful shutdown that waits for active connections to complete.

Why Graceful Shutdown Matters

Think of it like asking someone to leave a room versus yanking them out. A graceful shutdown lets your application finish what it's doing—close database connections, save state, complete requests—before exiting. The wrong signal might cause data corruption or lost work.

Key Takeaway: STOPSIGNAL customizes the shutdown signal Docker sends to your container, ensuring your application can shut down gracefully according to its specific needs.