How to use docker compose pause command to pause services

Introduction

In this lab, you will learn how to use the docker compose pause command to temporarily suspend running services defined in a docker-compose.yml file. We will start by creating a simple docker-compose.yml file that defines a web service using the Nginx image.

Following the creation of the docker-compose.yml file, you will learn how to start the services using docker compose up, pause a specific running service using docker compose pause, verify that the service is indeed paused, and finally, unpause the service using docker compose unpause. This hands-on exercise will provide practical experience in managing the lifecycle of Docker Compose services.

Skills Graph

Create a simple docker-compose.yml file

In this step, we will create a simple docker-compose.yml file. Before we start, we need to install Docker Compose. Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application's services. Then, with a single command, you create and start all the services from your configuration.

First, let's install Docker Compose. We will download the Docker Compose binary and make it executable.

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
sudo chmod +x /usr/local/bin/docker-compose

After the installation, you can verify the installation by checking the version of Docker Compose.

docker-compose --version

You should see output similar to Docker Compose version v2.20.2.

Now, let's create a directory for our project and navigate into it.

mkdir my-docker-app
cd my-docker-app

Inside the my-docker-app directory, we will create a file named docker-compose.yml. This file will define the services for our application. We will use the nano editor to create and edit this file.

nano docker-compose.yml

In the nano editor, paste the following content. This docker-compose.yml file defines a single service named web that uses the nginx:latest image.

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"

Let's break down this file:

• version: '3.8' specifies the Docker Compose file format version.
• services: defines the services that make up your application.
• web: is the name of our service.
• image: nginx:latest specifies the Docker image to use for this service. In this case, we are using the latest version of the Nginx image.
• ports: maps ports between the host and the container. "80:80" maps port 80 on the host to port 80 on the container.

After pasting the content, save the file by pressing Ctrl + X, then Y, and finally Enter.

Before starting the service, we need to make sure the nginx:latest image is available locally. If it's not, Docker Compose will automatically pull it when you start the service. However, you can also manually pull the image using the docker pull command.

docker pull nginx:latest

This command downloads the nginx:latest image from Docker Hub.

Start services defined in docker-compose.yml

In this step, we will start the services defined in our docker-compose.yml file. We will use the docker-compose up command to build, create, and start the services.

Make sure you are in the ~/project/my-docker-app directory where you created the docker-compose.yml file in the previous step.

cd ~/project/my-docker-app

Now, run the following 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

This command will read the docker-compose.yml file, create the necessary containers based on the service definitions, and start them. If the nginx:latest image is not already present on your system, Docker Compose will pull it automatically before starting the container.

You should see output indicating that the network, volume (if any), and the service container are being created and started. For example:

[+] Running 1/1
 ⠿ Container my-docker-app-web-1  Started

To verify that the service is running, you can use the docker-compose ps command. This command lists the containers managed by Docker Compose in the current directory.

docker-compose ps

You should see output similar to this, showing the web service container with a state of running:

NAME                  IMAGE         COMMAND                  SERVICE   CREATED        STATUS        PORTS
my-docker-app-web-1   nginx:latest  "/docker-entrypoint.…"   web       2 minutes ago  running       0.0.0.0:80->80/tcp, :::80->80/tcp

You can also verify that the Nginx web server is accessible by using the curl command to access localhost on port 80.

curl localhost:80

You should see the default Nginx welcome page HTML output, indicating that the web server is running and accessible.

Pause a running service

In this step, we will pause the running web service container. Pausing a container suspends all processes in the container. This is different from stopping a container, which shuts down the container's processes. When a container is paused, its state is frozen, and it consumes minimal CPU resources.

Make sure you are in the ~/project/my-docker-app directory.

cd ~/project/my-docker-app

To pause the web service, use the docker-compose pause command followed by the service name.

docker-compose pause web

You should see output indicating that the service is being paused:

[+] Paused 1/1
 ⠿ Container my-docker-app-web-1  Paused

Now, let's verify the status of the service using docker-compose ps.

docker-compose ps

The output should show the web service container with a state of paused:

NAME                  IMAGE         COMMAND                  SERVICE   CREATED        STATUS        PORTS
my-docker-app-web-1   nginx:latest  "/docker-entrypoint.…"   web       5 minutes ago  paused        0.0.0.0:80->80/tcp, :::80->80/tcp

When a container is paused, it should not be able to respond to requests. Let's try to access the Nginx web server again using curl.

curl localhost:80

This command might hang or return an error, indicating that the service is not responding because it is paused. This confirms that the container's processes are suspended.

Verify the service is paused

In this step, we will explicitly verify that the web service container is in a paused state. While we checked the status using docker-compose ps in the previous step, it's good practice to confirm the state using Docker commands directly as well.

First, make sure you are in the ~/project/my-docker-app directory.

cd ~/project/my-docker-app

We can use the docker ps command to list all running (including paused) containers. We will filter the output to find our web service container and check its status.

docker ps --filter "name=my-docker-app-web-1"

The output of this command should show the container with the STATUS column indicating Paused.

Alternatively, you can use the docker inspect command to get detailed information about the container, including its state. We will use grep to specifically look for the "Paused" state within the output.

docker inspect my-docker-app-web-1 | grep Paused

This command should output a line similar to "Paused": true,, confirming that the container is indeed paused.

As demonstrated in the previous step, attempting to access the service via curl should fail or hang, further indicating that the container is not actively processing requests.

curl localhost:80

This command should not return the Nginx welcome page.

Unpause the service

In this step, we will unpause the web service container that we paused in the previous step. Unpausing a container resumes all processes that were suspended when the container was paused.

Make sure you are in the ~/project/my-docker-app directory.

cd ~/project/my-docker-app

To unpause the web service, use the docker-compose unpause command followed by the service name.

docker-compose unpause web

You should see output indicating that the service is being unpaused:

[+] Unpaused 1/1
 ⠿ Container my-docker-app-web-1  Unpaused

Now, let's verify the status of the service again using docker-compose ps.

docker-compose ps

The output should now show the web service container with a state of running:

NAME                  IMAGE         COMMAND                  SERVICE   CREATED        STATUS        PORTS
my-docker-app-web-1   nginx:latest  "/docker-entrypoint.…"   web       8 minutes ago  running       0.0.0.0:80->80/tcp, :::80->80/tcp

Since the container is now running, it should be able to respond to requests again. Let's try to access the Nginx web server using curl.

curl localhost:80

You should now see the default Nginx welcome page HTML output, confirming that the service is running and accessible again.

Finally, to clean up the resources created during this lab, you can stop and remove the containers, networks, and volumes defined in the docker-compose.yml file using the docker-compose down command.

docker-compose down

This command will stop the running containers and remove the containers, networks, and volumes.

Summary

In this lab, we learned how to use the docker compose pause command to manage the state of services defined in a docker-compose.yml file. We began by installing Docker Compose and creating a simple docker-compose.yml file that defines a web service using the Nginx image.

Following the setup, we started the service using docker compose up -d, paused the running service with docker compose pause web, verified its paused state, and finally unpaused it using docker compose unpause web. This hands-on experience demonstrated the practical application of the pause and unpause commands for temporarily suspending and resuming Docker Compose services.