How to use docker compose stop command to manage services

Introduction

In this lab, you will learn how to use the docker compose stop command to manage services defined in a Docker Compose file. We will begin by preparing a simple Docker Compose project, which includes installing Docker Compose and creating a basic docker-compose.yml file.

Following the project setup, you will practice starting the services defined in the Compose file. The core of the lab focuses on using the docker compose stop command to stop all running services, stop a specific service, and stop services with a specified timeout. This hands-on experience will provide you with practical skills for controlling the lifecycle of your multi-container Docker applications using Docker Compose.

Prepare a simple Docker Compose project

In this step, we will prepare a simple Docker Compose project. 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.

Since Docker Compose is not pre-installed in the LabEx environment, we need to install it first. We will download the Docker Compose binary and make it executable.

First, let's download the Docker Compose binary. We will use curl to download the latest stable release.

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 for your system architecture and saves it to /usr/local/bin/docker-compose.

Next, we need to make the downloaded binary executable.

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

This command adds execute permissions to the Docker Compose binary.

Now, let's verify the installation by checking the Docker Compose version.

docker-compose --version

You should see the installed Docker Compose version in the output, confirming that the installation was successful.

Now that Docker Compose is installed, let's create a simple Docker Compose project. We will create a directory for our project and then create a docker-compose.yml file inside it.

First, create a directory named my-compose-app in your home directory.

mkdir ~/project/my-compose-app

Navigate into the newly created directory.

cd ~/project/my-compose-app

Now, we will create a docker-compose.yml file. This file will define the services for our application. We will use nano to create and edit the file.

nano docker-compose.yml

Inside the nano editor, paste the following content:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  app:
    image: ubuntu:latest
    command: tail -f /dev/null

Let's break down this docker-compose.yml file:

version: '3.8' specifies the Docker Compose file format version.
services: defines the services that make up your application.
web: defines a service named web.
- image: nginx:latest specifies that this service will use the nginx:latest Docker image. If the image is not available locally, Docker Compose will pull it from Docker Hub.
- ports: maps port 80 on the host machine to port 80 on the web container.
app: defines a service named app.
- image: ubuntu:latest specifies that this service will use the ubuntu:latest Docker image.
- command: tail -f /dev/null specifies the command to run when the app container starts. This command keeps the container running indefinitely without exiting.

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

Before we can start the services, we need to make sure the required Docker images are available. Although Docker Compose will pull images if they are not present, it's good practice to explicitly pull them beforehand, especially in environments with limited internet access or for faster startup.

Let's pull the nginx:latest image.

docker pull nginx:latest

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

Next, let's pull the ubuntu:latest image.

docker pull ubuntu:latest

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

Now you have successfully prepared a simple Docker Compose project with two services, web and app, and pulled the necessary Docker images.

Start the services defined in the Compose file

In this step, we will start the services defined in the docker-compose.yml file we created in the previous step. Docker Compose provides a simple command to build, create, and start all the services in your configuration.

Make sure you are in the ~/project/my-compose-app directory where your docker-compose.yml file is located.

cd ~/project/my-compose-app

To start the services, we will use the docker-compose up command. By default, docker-compose up starts the containers in the foreground and prints the logs of each container.

docker-compose up

When you run this command, Docker Compose will:

Look for the docker-compose.yml file in the current directory.
Build or pull the necessary Docker images for each service if they are not already available.
Create and start the containers for each service.
Display the logs from all the running containers in your terminal.

You will see output indicating that the networks and containers are being created and started. The logs from the web (nginx) and app (ubuntu) containers will be displayed.

Since we want the services to run in the background so we can continue using the terminal, we can stop the current execution by pressing Ctrl + C.

To run the services in detached mode (in the background), we can use the -d flag with the docker-compose up command.

docker-compose up -d

This command will start the services in the background and print the names of the created containers.

Now that the services are running in detached mode, you can check the status of the running containers using the docker ps command.

docker ps

You should see two containers running: one for the web service (based on the nginx image) and one for the app service (based on the ubuntu image). The output will show information about the containers, including their IDs, images, status, and ports.

To verify that the web service is accessible, we can use curl to access the nginx server running on port 80. Since we mapped port 80 on the host to port 80 on the web container, we can access it directly from the LabEx VM.

curl http://localhost:80

You should see the default HTML content served by the nginx web server, which confirms that the web service is running and accessible.

Stop all running services

In this step, we will learn how to stop all the services that are currently running as part of our Docker Compose project. Docker Compose provides a convenient command to stop all the containers defined in the docker-compose.yml file.

Make sure you are in the ~/project/my-compose-app directory where your docker-compose.yml file is located.

cd ~/project/my-compose-app

To stop all the running services, we use the docker-compose down command. This command stops and removes the containers, networks, and volumes defined in the docker-compose.yml file.

docker-compose down

When you run this command, Docker Compose will:

Stop the running containers gracefully.
Remove the stopped containers.
Remove the networks created by Docker Compose for this project.
Remove any volumes defined in the docker-compose.yml file (unless explicitly told not to).

You will see output indicating that the containers and networks are being stopped and removed.

After running docker-compose down, you can verify that the containers are no longer running by using the docker ps command.

docker ps

This command lists the currently running containers. Since we stopped all the services, you should not see the web or app containers in the output. The output should only show the header row or be empty if no other containers are running on your system.

Stopping services with docker-compose down is the standard way to clean up your Docker Compose project resources when you are finished with them.

Stop a specific service

In this step, we will learn how to stop a specific service within our Docker Compose project, rather than stopping all services at once. This is useful when you only need to restart or stop a single component of your application.

First, let's make sure our services are running. Navigate to the project directory and start the services in detached mode.

cd ~/project/my-compose-app
docker-compose up -d

Verify that both the web and app services are running using docker ps.

docker ps

You should see both containers listed as running.

Now, let's stop only the app service. To stop a specific service, we use the docker-compose stop command followed by the name of the service.

docker-compose stop app

This command will send a stop signal to the container for the app service and wait for it to stop gracefully.

After running the command, let's check the status of the containers again.

docker ps

You should now see only the web container listed as running. The app container should no longer be in the list of running containers.

To confirm that the app container has stopped, you can also use docker ps -a, which shows all containers, including stopped ones.

docker ps -a

You should see the app container listed with a status of Exited.

Stopping a specific service allows you to manage individual components of your application without affecting others. This is particularly helpful during development or when troubleshooting a specific service.

Stop services with a timeout

In this step, we will explore how to stop services with a specified timeout. When you stop a container, Docker sends a SIGTERM signal to the main process in the container, giving it time to shut down gracefully. If the process doesn't exit within a certain period, Docker sends a SIGKILL signal to force it to stop. By default, this timeout is 10 seconds. You can adjust this timeout using the -t or --timeout flag with the docker-compose stop or docker-compose down commands.

First, let's ensure our services are running. Navigate to the project directory and start the services in detached mode.

cd ~/project/my-compose-app
docker-compose up -d

Verify that both services are running:

docker ps

Now, let's stop the web service with a timeout of 5 seconds.

docker-compose stop -t 5 web

This command tells Docker Compose to stop the web service and wait for a maximum of 5 seconds for the container to stop gracefully after sending the SIGTERM signal. If the container doesn't stop within 5 seconds, Docker will send a SIGKILL signal.

You will see output indicating that the web service is being stopped.

Let's check the status of the containers again:

docker ps

You should now see only the app container running. The web container should be stopped.

Similarly, you can apply a timeout when stopping all services using docker-compose down. Let's stop all services with a timeout of 3 seconds.

docker-compose down -t 3

This command will attempt to stop all services defined in the docker-compose.yml file, waiting for a maximum of 3 seconds for each container to stop gracefully before forcefully stopping it.

Verify that no containers are running after executing the command:

docker ps

The output should show no running containers.

Using the timeout option is important for ensuring that your applications have enough time to perform cleanup tasks before being stopped, preventing data corruption or other issues.

Summary

In this lab, we learned how to prepare a simple Docker Compose project. This involved installing Docker Compose by downloading the binary and making it executable, and then verifying the installation. We then created a project directory and a docker-compose.yml file to define the services for our application.

We also learned how to manage the lifecycle of services defined in the Compose file using the docker compose stop command. This included starting all services, stopping all running services, stopping a specific service, and stopping services with a specified timeout.