How to use docker desktop stop command to manage Docker Desktop

Introduction

In this lab, you will learn how to effectively manage your Docker containers using the docker stop command. We will cover the basic usage of stopping a running container, explore different options for controlling the stopping process, including how to force stop a container and how to set a timeout for the stop operation. By the end of this lab, you will be proficient in using docker stop to gracefully and forcefully terminate your Docker containers.

Skills Graph

Understand the basic usage of docker desktop stop

In this step, we will learn the basic usage of the docker stop command. The docker stop command is used to stop one or more running containers. By default, the command sends a SIGTERM signal to the container, and after a grace period, sends a SIGKILL signal if the container has not stopped.

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

docker run -d ubuntu sleep infinity

The -d flag runs the container in detached mode, meaning it runs in the background. sleep infinity is a command that will make the container stay running indefinitely.

Now, let's list the running containers to get the container ID.

docker ps

You should see output similar to this, showing your running ubuntu container:

CONTAINER ID   IMAGE          COMMAND           CREATED         STATUS         PORTS     NAMES
<container_id>   ubuntu         "sleep infinity"   X seconds ago   Up X seconds             <container_name>

Replace <container_id> with the actual ID of your running container from the output of docker ps. Now, stop the container using the docker stop command followed by the container ID.

docker stop <container_id>

After running this command, the container should stop. You can verify this by listing the running containers again.

docker ps

This time, the docker ps command should not show the container you just stopped.

To see all containers, including those that are stopped, you can use the -a flag with docker ps.

docker ps -a

This will show you the stopped container with a status of Exited.

Stop Docker Desktop using the detach option

In this step, we will explore stopping a container using the detach option. While docker stop itself doesn't have a detach option in the same way docker run does, the concept of detaching is inherent in how docker stop works when you execute it in your terminal. The command runs and returns control to your terminal once the stop signal is sent, allowing you to continue with other tasks.

Let's start by running another container that we will stop. We'll use the nginx image this time. First, pull the nginx image if you don't have it locally.

docker pull nginx

Now, run the nginx container in detached mode.

docker run -d nginx

Get the container ID of the running nginx container.

docker ps

You will see output similar to this, showing both the previous ubuntu container (if you didn't remove it) and the new nginx container:

CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS         PORTS     NAMES
<nginx_container_id>   nginx          "nginx -g 'daemon off"   X seconds ago   Up X seconds   80/tcp    <nginx_container_name>
<ubuntu_container_id>   ubuntu         "sleep infinity"         Y minutes ago   Exited Y minutes ago             <ubuntu_container_name>

Now, stop the nginx container using its ID.

docker stop <nginx_container_id>

When you execute docker stop, the command sends the stop signal and immediately returns control to your terminal. This is the "detached" behavior from the perspective of your terminal session – you don't have to wait for the container to fully stop before you can type another command.

Verify that the nginx container has stopped.

docker ps

The nginx container should no longer appear in the list of running containers.

Force stop Docker Desktop

In this step, we will learn how to force stop a container using the docker stop command. While docker stop by default sends a graceful stop signal (SIGTERM), sometimes a container might not respond to this signal and needs to be forcefully stopped. This is achieved by the default behavior of docker stop which sends a SIGKILL after a timeout.

Let's run a container that might be difficult to stop gracefully. We'll use a simple ubuntu container again, but this time we'll simulate a process that ignores the SIGTERM signal.

docker run -d ubuntu sh -c 'trap "" SIGTERM; sleep infinity'

In this command:

• trap "" SIGTERM tells the shell to ignore the SIGTERM signal.
• sleep infinity keeps the container running.

Get the container ID of this new ubuntu container.

docker ps

You should see the new ubuntu container running.

CONTAINER ID   IMAGE          COMMAND                        CREATED         STATUS         PORTS     NAMES
<force_stop_container_id>   ubuntu         "sh -c 'trap \"\" SIGT…"   X seconds ago   Up X seconds             <container_name>
<nginx_container_id>   nginx          "nginx -g 'daemon off"   Y minutes ago   Exited Y minutes ago   80/tcp    <nginx_container_name>
<ubuntu_container_id>   ubuntu         "sleep infinity"         Z minutes ago   Exited Z minutes ago             <ubuntu_container_name>

Now, try to stop this container using the standard docker stop command with its ID.

docker stop <force_stop_container_id>

Since the container is ignoring the SIGTERM signal, docker stop will wait for the default grace period (usually 10 seconds) and then send a SIGKILL signal, which cannot be ignored. This will forcefully stop the container. You might notice a slight delay before the command finishes.

Verify that the container has stopped.

docker ps

The container should no longer be listed as running.

You can also explicitly specify a timeout of 0 seconds with the -t flag to immediately send a SIGKILL signal, effectively forcing the stop without waiting for the grace period. We will explore the -t flag in the next step.

Stop Docker Desktop with a timeout

In this step, we will learn how to stop a container with a specific timeout using the -t or --time flag with the docker stop command. This allows you to specify how long Docker should wait for the container to gracefully exit after sending the SIGTERM signal before forcefully stopping it with SIGKILL.

Let's run a container that we will stop with a timeout. We'll use the ubuntu image and a script that waits for a signal before exiting.

docker run -d ubuntu sh -c 'trap "exit 0" SIGTERM; sleep infinity'

This command runs an ubuntu container in detached mode. The trap "exit 0" SIGTERM part sets up a trap that will cause the script to exit gracefully when it receives a SIGTERM signal. sleep infinity keeps the container running until it receives the signal.

Get the container ID of this new ubuntu container.

docker ps

You should see the new ubuntu container running.

CONTAINER ID   IMAGE          COMMAND                        CREATED         STATUS         PORTS     NAMES
<timeout_container_id>   ubuntu         "sh -c 'trap \"exit 0\"…"   X seconds ago   Up X seconds             <container_name>
<force_stop_container_id>   ubuntu         "sh -c 'trap \"\" SIGT…"   Y minutes ago   Exited Y minutes ago             <container_name>
<nginx_container_id>   nginx          "nginx -g 'daemon off"   Z minutes ago   Exited Z minutes ago   80/tcp    <nginx_container_name>
<ubuntu_container_id>   ubuntu         "sleep infinity"         A minutes ago   Exited A minutes ago             <ubuntu_container_name>

Now, stop this container with a timeout of 5 seconds using the -t flag.

docker stop -t 5 <timeout_container_id>

Docker will send the SIGTERM signal and wait for 5 seconds. Since our container is set up to exit gracefully on SIGTERM, it should stop within this timeout period. If it didn't stop within 5 seconds, Docker would then send a SIGKILL.

Verify that the container has stopped.

docker ps

The container should no longer be listed as running.

Using the -t flag is useful when you want to give your container a specific amount of time to perform cleanup operations before being forcefully stopped.

Summary

In this lab, we learned the fundamental usage of the docker stop command to manage running containers. We started by understanding that docker stop sends a SIGTERM signal followed by a SIGKILL after a grace period. We practiced stopping a simple ubuntu container running in detached mode by identifying its container ID using docker ps and then executing docker stop <container_id>. We verified the container's stopped status by listing running containers again and also learned how to view all containers, including stopped ones, using docker ps -a.