How to use docker container stop command to gracefully stop containers

Introduction

In this lab, you will learn how to gracefully stop Docker containers using the docker container stop command. We will begin by creating and running a simple container. Then, you will explore how to stop containers using the default signal and timeout, and subsequently learn how to customize the timeout and the signal used for stopping containers. This hands-on experience will provide you with practical skills for managing the lifecycle of your Docker containers effectively.

Skills Graph

Create and run a simple container

In this step, you will learn how to create and run a simple Docker container. A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another.

First, let's pull a simple image from Docker Hub. We will use the hello-world image, which is a very small image that simply prints a message and exits.

docker pull hello-world

You should see output indicating that the image is being pulled and downloaded.

Using default tag: latest
latest: Pulling from library/hello-world
...
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest

Now that we have the image, we can run a container based on this image. Use the docker run command:

docker run hello-world

When you run this command, Docker will create a new container from the hello-world image. The container will execute the command defined in the image, which in this case is to print a message to the console.

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

This output confirms that your Docker installation is working and you have successfully run your first container. The container ran the hello-world program and then exited.

To see the containers that have run, including those that have exited, you can use the docker ps -a command:

docker ps -a

You should see the hello-world container listed with a status of Exited.

CONTAINER ID   IMAGE         COMMAND    CREATED         STATUS                      PORTS     NAMES
<container_id>   hello-world   "/hello"   About a minute ago   Exited (0) About a minute ago             <container_name>

The output shows the container ID, the image it was based on, the command it ran, when it was created, its current status, and its assigned name.

Stop the container using the default signal and timeout

In this step, you will learn how to stop a running Docker container using the default signal and timeout. When you stop a container, Docker sends a signal to the main process running inside the container. By default, Docker sends the SIGTERM signal, which tells the process to shut down gracefully. If the process does not exit within a default timeout period (usually 10 seconds), Docker sends a SIGKILL signal to force the process to terminate.

First, let's run a container that will stay running. We will use the ubuntu image and run a simple command that keeps the container alive.

docker pull ubuntu

You should see output indicating that the ubuntu image is being pulled.

Using default tag: latest
latest: Pulling from library/ubuntu
...
Status: Downloaded newer image for ubuntu:latest
docker.io/library/ubuntu:latest

Now, run the ubuntu container in detached mode (-d) so it runs in the background, and execute a command that will keep it running indefinitely (e.g., tail -f /dev/null).

docker run -d ubuntu tail -f /dev/null

This command will output the container ID.

<container_id>

You can verify that the container is running using the docker ps command:

docker ps

You should see the ubuntu container listed with a status of Up.

CONTAINER ID   IMAGE     COMMAND               CREATED         STATUS         PORTS     NAMES
<container_id>   ubuntu    "tail -f /dev/null"   About a minute ago   Up About a minute ago             <container_name>

Now, let's stop this running container using the docker stop command. You can use either the container ID or the container name. Replace <container_id> with the actual ID of your running container.

docker stop <container_id>

The command will output the container ID that was stopped.

<container_id>

After running the docker stop command, the container will receive the SIGTERM signal. Docker will wait for the default timeout (10 seconds) for the container to stop gracefully. If it doesn't stop within that time, it will send SIGKILL.

You can verify that the container has stopped by running docker ps again.

docker ps

The ubuntu container should no longer be listed in the output of docker ps (which only shows running containers). To see all containers, including stopped ones, use docker ps -a.

docker ps -a

You should see the ubuntu container listed with a status of Exited.

CONTAINER ID   IMAGE     COMMAND               CREATED         STATUS                      PORTS     NAMES
<container_id>   ubuntu    "tail -f /dev/null"   About a minute ago   Exited (0) About a minute ago             <container_name>

This confirms that the container was successfully stopped using the default signal and timeout.

Stop the container with a custom timeout

In this step, you will learn how to stop a running Docker container and specify a custom timeout for the graceful shutdown period. This is useful when you need to give your application more or less time to shut down cleanly before Docker forcefully terminates it.

We will use the same ubuntu image and command as in the previous step to run a container that stays alive.

First, run the ubuntu container in detached mode (-d) with the tail -f /dev/null command:

docker run -d ubuntu tail -f /dev/null

This command will output the container ID.

<container_id>

Verify that the container is running using docker ps:

docker ps

You should see the ubuntu container listed with a status of Up.

CONTAINER ID   IMAGE     COMMAND               CREATED         STATUS         PORTS     NAMES
<container_id>   ubuntu    "tail -f /dev/null"   About a minute ago   Up About a minute ago             <container_name>

Now, stop the container using the docker stop command, but this time, specify a timeout using the -t or --time flag. Let's set the timeout to 5 seconds. Replace <container_id> with the actual ID of your running container.

docker stop -t 5 <container_id>

The command will output the container ID that was stopped.

<container_id>

When you use docker stop -t 5, Docker sends the SIGTERM signal and waits for 5 seconds for the container to stop. If the container is still running after 5 seconds, Docker will send the SIGKILL signal.

Verify that the container has stopped by running docker ps -a:

docker ps -a

You should see the ubuntu container listed with a status of Exited.

CONTAINER ID   IMAGE     COMMAND               CREATED         STATUS                      PORTS     NAMES
<container_id>   ubuntu    "tail -f /dev/null"   About a minute ago   Exited (0) About a minute ago             <container_name>

You have successfully stopped the container with a custom timeout of 5 seconds.

Stop the container with a custom signal

In this step, you will learn how to stop a running Docker container by sending a specific signal other than the default SIGTERM. This can be useful for applications that are configured to respond to different signals for graceful shutdown or other actions.

We will again use the ubuntu image and the tail -f /dev/null command to keep a container running.

Run the ubuntu container in detached mode (-d):

docker run -d ubuntu tail -f /dev/null

This command will output the container ID.

<container_id>

Verify that the container is running using docker ps:

docker ps

You should see the ubuntu container listed with a status of Up.

CONTAINER ID   IMAGE     COMMAND               CREATED         STATUS         PORTS     NAMES
<container_id>   ubuntu    "tail -f /dev/null"   About a minute ago   Up About a minute ago             <container_name>

Now, stop the container using the docker stop command, and specify a custom signal using the --signal flag. For example, let's send the SIGKILL signal directly. Replace <container_id> with the actual ID of your running container.

docker stop --signal SIGKILL <container_id>

The command will output the container ID that was stopped.

<container_id>

When you use docker stop --signal SIGKILL, Docker sends the SIGKILL signal immediately to the main process in the container. This signal cannot be caught or ignored by the process, so it will terminate forcefully without any graceful shutdown period.

Verify that the container has stopped by running docker ps -a:

docker ps -a

You should see the ubuntu container listed with a status of Exited.

CONTAINER ID   IMAGE     COMMAND               CREATED         STATUS                      PORTS     NAMES
<container_id>   ubuntu    "tail -f /dev/null"   About a minute ago   Exited (137) About a minute ago             <container_name>

Note that the exit code might be different (e.g., 137) when a container is stopped with SIGKILL, as this indicates a non-graceful termination.

You have successfully stopped the container by sending a custom signal.

Summary

In this lab, you learned the fundamental steps of working with Docker containers. You began by pulling a simple image (hello-world) from Docker Hub and then running a container based on that image. This demonstrated the basic process of creating and executing a container, and you verified its successful completion by checking the container status using docker ps -a.

The subsequent steps, although not fully detailed in the provided content, would have guided you through the process of stopping running containers using the docker container stop command. This would have included understanding the default signal and timeout used for stopping, and then exploring how to customize both the timeout duration and the signal sent to the container to achieve a graceful shutdown.