How to use docker container wait command to block until containers stop

Introduction

In this lab, you will learn how to effectively use the docker container wait command. This command is a powerful tool for scripting and automation, allowing you to pause execution until a specified container has stopped.

You will begin by starting a Docker container in the background using the detached mode (-d). Then, you will use docker container wait to block your terminal until this background container finishes its execution. To demonstrate the blocking behavior, you will stop the container from a separate terminal. Finally, you will observe the exit code returned by the docker container wait command, understanding how it signals the container's termination status.

Skills Graph

Start a container in the background

In this step, you will learn how to start a Docker container in the background. Running a container in the background allows it to operate without occupying your terminal, which is useful for long-running services or applications.

First, let's pull the alpine image. This is a very small Linux distribution image that is useful for testing.

docker pull alpine

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

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

Now, we will start an alpine container in the background using the -d flag. The -d flag stands for "detached mode". We will also run a simple command inside the container, sleep 30, which will make the container run for 30 seconds before exiting.

docker run -d alpine sleep 30

After running this command, Docker will print the full container ID.

<container_id>

To verify that the container is running in the background, you can use the docker ps command. This command lists all currently running containers.

docker ps

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

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

The STATUS column should show Up followed by the duration the container has been running. This confirms that the container is running in detached mode.

Use docker container wait to block until the container stops

In this step, you will learn how to use the docker container wait command. This command blocks until one or more containers stop, and then prints their exit codes. This is useful when you need to wait for a background process in a container to complete before proceeding with other tasks.

First, let's get the ID of the container we started in the previous step. We can use docker ps -q to get only the container ID of the running container.

docker ps -q

This command will output the container ID. Copy this ID as you will need it for the next command.

<container_id>

Now, use the docker container wait command followed by the container ID you just obtained.

docker container wait <container_id>

When you run this command, your terminal will appear to hang. This is expected behavior. The docker container wait command is blocking, meaning it will pause execution until the specified container stops. Since the container is currently running the sleep 30 command, this command will wait for up to 30 seconds for the container to finish.

Once the container stops (either by completing its sleep 30 command or being stopped manually), the docker container wait command will unblock and print the exit code of the container.

For example, if the container stops successfully after 30 seconds, you will see:

0

An exit code of 0 typically indicates that the command inside the container completed successfully.

Keep this terminal window open, as we will interact with this waiting command in the next step.

Stop the container in another terminal

In this step, you will open a new terminal and stop the running container. This will demonstrate how docker container wait in the first terminal reacts when the container is stopped externally.

Open a new terminal window in the LabEx environment. You can usually do this by clicking the "+" icon or selecting "New Terminal" from a menu.

In this new terminal, we need to identify the running container again. Use docker ps to list running containers and find the container ID.

docker ps

You will see output similar to the previous step, showing the container ID, image, command, etc.

CONTAINER ID   IMAGE     COMMAND       CREATED         STATUS         PORTS     NAMES
<container_id>   alpine    "sleep 30"    X minutes ago   Up X minutes             <container_name>

Now, use the docker stop command followed by the container ID to stop the container.

docker stop <container_id>

You should see the container ID printed back to the terminal, indicating that the stop command was successful.

<container_id>

Switch back to the first terminal window where you ran docker container wait. You should observe that the docker container wait command has now finished and printed an exit code. We will examine this exit code in the next step.

Observe the exit code from docker container wait

In this final step, we will examine the exit code that was printed by the docker container wait command in the first terminal.

Switch back to the first terminal window where you ran the docker container wait <container_id> command.

You should see a number printed on the line after the command. This number is the exit code of the container.

137

In the previous step, you stopped the container using docker stop. When a container is stopped using docker stop, Docker sends a SIGTERM signal to the main process in the container, and after a grace period, a SIGKILL signal if the process hasn't exited. An exit code of 137 is a common indicator that a process was terminated by a SIGKILL signal (128 + 9, where 9 is the signal number for SIGKILL).

This demonstrates that docker container wait not only waits for the container to stop but also provides the exit code, which can give you information about how the container stopped. If the container had finished its sleep 30 command naturally, the exit code would have been 0.

You can verify the container is stopped by running docker ps -a in either terminal. The -a flag shows all containers, including stopped ones.

docker ps -a

You should see your alpine container listed, and its status should be Exited (<exit_code>).

CONTAINER ID   IMAGE     COMMAND       CREATED          STATUS                      PORTS     NAMES
<container_id>   alpine    "sleep 30"    X minutes ago    Exited (137) X seconds ago             <container_name>

This concludes the lab on using docker container wait. You have learned how to start a container in the background, wait for it to stop using docker container wait, stop it from another terminal, and observe the resulting exit code.

Summary

In this lab, you learned how to start a Docker container in the background using the -d flag and the docker run command, verifying its status with docker ps. You also began to explore the docker container wait command, understanding its purpose in blocking execution until a specified container stops and then returning its exit code.