How to use docker compose wait command to block until services stop

Introduction

In this lab, you will learn how to effectively use the docker compose wait command to manage the lifecycle of your Docker Compose services. We will begin by setting up a basic docker-compose.yml file with multiple services and observing their initial state after starting them.

Subsequently, you will explore the core functionality of docker compose wait to block execution until all services within your project have stopped. We will then demonstrate how to use this command to wait for specific services to stop and finally, how to combine docker compose wait with the --down-project option for a complete project shutdown and wait operation.

Skills Graph

Create a simple docker-compose.yml with multiple services

In this step, we will create a simple docker-compose.yml file that defines two services. Before we start, we need to install Docker Compose as it is not pre-installed in this environment.

First, let's download the Docker Compose binary. We will download version v2.20.2 which is compatible with the installed Docker version.

sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

This command downloads the Docker Compose binary from the official GitHub releases page and saves it to /usr/local/bin/docker-compose. The $(uname -s) and $(uname -m) parts automatically detect your operating system and architecture.

Next, we need to give the downloaded binary executable permissions.

sudo chmod +x /usr/local/bin/docker-compose

Now, let's verify that Docker Compose is installed correctly by checking its version.

docker-compose version

You should see output indicating the version of Docker Compose that was installed.

Now that Docker Compose is installed, we can create our docker-compose.yml file. This file uses YAML format to define the services, networks, and volumes for your application. We will create a simple file with two services: a web server and a database.

Navigate to your project directory.

cd ~/project

Now, create a file named docker-compose.yml using the nano editor.

nano docker-compose.yml

Paste the following content into the editor:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  db:
    image: postgres:latest
    environment:
      POSTGRES_PASSWORD: mysecretpassword

Let's break down this file:

• version: '3.8' specifies the Docker Compose file format version.
• services: defines the different services that make up your application.
• web: defines a service named web.
  • image: nginx:latest specifies that this service will use the latest nginx image from Docker Hub.
  • ports: maps port 80 on the host machine to port 80 on the web container, allowing you to access the web server from your browser.
• db: defines a service named db.
  • image: postgres:latest specifies that this service will use the latest postgres image from Docker Hub.
  • environment: sets environment variables inside the container. Here, we set the POSTGRES_PASSWORD required by the PostgreSQL image.

Save the file by pressing Ctrl + X, then Y, and then Enter.

You have now successfully created a docker-compose.yml file defining two services.

Start the services and observe their state

In this step, we will start the services defined in our docker-compose.yml file and observe their state.

First, make sure you are in the ~/project directory where you created the docker-compose.yml file.

cd ~/project

Now, use the docker-compose up command to start the services. The -d flag runs the containers in detached mode, meaning they will run in the background.

docker-compose up -d

When you run this command for the first time, Docker Compose will download the necessary images (nginx:latest and postgres:latest) if they are not already present on your system. This might take some time depending on your internet connection. After downloading, it will create and start the containers for the web and db services.

You should see output indicating that the networks, volumes (if any are defined, though not in our simple example), and containers are being created and started.

To check the status of the running services, use the docker-compose ps command.

docker-compose ps

This command lists the containers managed by Docker Compose in the current directory. You should see both the web and db services listed with their state, which should be Up.

You can also use the standard docker ps command to see all running containers on your system, including those started by Docker Compose.

docker ps

Look for containers whose names are prefixed with the directory name (project in this case) followed by the service name (e.g., project-web-1, project-db-1).

To see the logs of the services, you can use the docker-compose logs command. For example, to see the logs for the web service:

docker-compose logs web

And for the db service:

docker-compose logs db

This is useful for debugging and understanding what is happening inside your containers.

You have now successfully started the services defined in your docker-compose.yml file and observed their state using docker-compose ps.

Use docker compose wait to block until services stop

In this step, we will explore the docker compose wait command, which is used to block until services reach a certain state. By default, docker compose wait waits for services to stop.

First, ensure your services are running from the previous step. You can verify this using docker-compose ps.

cd ~/project
docker-compose ps

You should see both web and db services listed with the state Up.

Now, open a new terminal window or tab. Keep the current terminal window open as we will use it to stop the services later.

In the new terminal window, navigate to the ~/project directory.

cd ~/project

Run the docker compose wait command. This command will block and wait until all services defined in the docker-compose.yml file in the current directory have stopped.

docker compose wait

You will notice that this command appears to hang. This is expected because the services are currently running. The docker compose wait command is waiting for them to stop.

Now, switch back to your original terminal window where the services are running. We will stop the services using the docker-compose down command. This command stops and removes the containers, networks, and volumes created by docker-compose up.

cd ~/project
docker-compose down

Observe the output in the original terminal window. You will see messages indicating that the containers are being stopped and removed.

Now, switch back to the new terminal window where you ran docker compose wait. As the services are stopped by the docker-compose down command in the other terminal, the docker compose wait command in this window will detect that the services have stopped and will exit.

You should see the command prompt return in the new terminal window. This demonstrates how docker compose wait blocks until the specified services (all services by default) have stopped.

You have successfully used docker compose wait to block until all services in your project stopped.

Use docker compose wait with specific services

In the previous step, we used docker compose wait to wait for all services to stop. In this step, we will learn how to use docker compose wait to wait for specific services to reach a certain state.

First, let's start our services again using docker-compose up -d. Make sure you are in the ~/project directory.

cd ~/project
docker-compose up -d

Verify that both services are running using docker-compose ps.

docker-compose ps

Now, open a new terminal window or tab. We will use this new terminal to demonstrate waiting for a specific service.

In the new terminal window, navigate to the ~/project directory.

cd ~/project

We can specify which services to wait for by providing their names after the docker compose wait command. For example, to wait only for the web service to stop:

docker compose wait web

Similar to the previous step, this command will block because the web service is currently running.

Now, switch back to your original terminal window. We will stop only the web service. To do this, we can use the docker stop command with the container name. You can find the container name using docker ps. It will likely be something like project-web-1.

cd ~/project
docker stop project-web-1

Replace project-web-1 with the actual container name if it's different.

Observe the output in the original terminal window. You will see a message indicating that the web container is being stopped.

Now, switch back to the new terminal window where you ran docker compose wait web. As the web service is stopped, the docker compose wait web command will detect this and exit.

You should see the command prompt return in the new terminal window. Notice that the docker compose wait web command exited even though the db service is still running.

To confirm that the db service is still running, switch back to the original terminal and run docker-compose ps.

cd ~/project
docker-compose ps

You should see the db service listed with the state Up, while the web service is no longer listed or shows a stopped state.

Finally, let's stop the remaining db service.

cd ~/project
docker-compose down

You have successfully used docker compose wait to block until a specific service stopped.

Use docker compose wait with --down-project option

In this final step, we will explore the --down-project option with docker compose wait. This option is useful when you want to wait for services to stop and then automatically bring down the entire project.

First, let's ensure our services are stopped from the previous step. You can verify this using docker-compose ps.

cd ~/project
docker-compose ps

If any services are still running, stop them using docker-compose down.

docker-compose down

Now, let's start the services again in detached mode.

cd ~/project
docker-compose up -d

Verify that both services are running.

docker-compose ps

Now, we will use the docker compose wait command with the --down-project option. This command will wait for all services to stop and then automatically execute docker-compose down.

docker compose wait --down-project

Similar to the previous uses of docker compose wait, this command will block because the services are currently running.

Now, open a new terminal window or tab. In this new terminal, we will manually stop the services.

In the new terminal window, navigate to the ~/project directory.

cd ~/project

Stop the services using docker-compose down.

docker-compose down

Observe the output in the new terminal window. You will see messages indicating that the containers are being stopped and removed.

Now, switch back to the original terminal window where you ran docker compose wait --down-project. As the services are stopped by the docker-compose down command in the other terminal, the docker compose wait command will detect this. Because the --down-project option was used, it will then automatically proceed to bring down the project, which in this case means removing the containers, networks, and volumes.

You should see output in the original terminal window similar to what you saw when you manually ran docker-compose down. After the project is brought down, the docker compose wait command will exit.

You have successfully used docker compose wait with the --down-project option to wait for services to stop and then automatically bring down the project.

Summary

In this lab, we learned how to use the docker compose wait command to block until services stop. We began by installing Docker Compose and creating a simple docker-compose.yml file defining two services, web and db. This setup provided the necessary environment to demonstrate the functionality of the wait command.

We then explored how to use docker compose wait to block until all services defined in the docker-compose.yml file stop. We also learned how to use the command with specific service names to wait for only those services to stop, and how to use the --down-project option to wait for the entire project to be brought down. These steps illustrated the flexibility and utility of the docker compose wait command for managing the lifecycle of Docker Compose services.