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.
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:latestspecifies 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.
