How to use docker compose restart command to manage services

Introduction

In this lab, you will learn how to effectively manage the lifecycle of your Docker services using the docker compose restart command. We will begin by setting up a simple multi-service application using Docker Compose, consisting of a web service and a database service.

Following the setup, you will explore various ways to utilize the docker compose restart command. This includes restarting all services within your application, targeting and restarting a specific service, restarting a service without affecting its dependencies, and finally, restarting a service with a defined timeout period. Through these hands-on exercises, you will gain practical experience in controlling and maintaining your Dockerized applications.

Skills Graph

Prepare a simple multi-service application

In this step, we will prepare a simple multi-service application that we will use throughout this lab to practice restarting Docker services. This application consists of two services: a web service and a database service. We will define these services using a Docker Compose file.

First, we need to install Docker Compose. Since it's not pre-installed in the LabEx VM environment, we will download and install it.

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

The first command downloads the Docker Compose binary from the official GitHub repository and saves it to /usr/local/bin/docker-compose. The $(uname -s) and $(uname -m) parts automatically detect your operating system and architecture to download the correct binary. The second command makes the downloaded file executable.

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

docker-compose --version

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

Next, navigate to the ~/project directory, which is your working directory for this lab.

cd ~/project

Now, we will create a docker-compose.yml file to define our multi-service application. This file will specify the services, their images, and any necessary configurations.

nano docker-compose.yml

Paste the following content into the docker-compose.yml file:

version: "3.8"

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    depends_on:
      - db

  db:
    image: postgres:latest
    environment:
      POSTGRES_PASSWORD: mysecretpassword

In this docker-compose.yml file:

• version: '3.8' specifies the Docker Compose file format version.
• services: defines the different services in our application.
• The web service uses the nginx:latest image, maps port 80 on the host to port 80 in the container, and depends on the db service. This means the db service will be started before the web service.
• The db service uses the postgres:latest image and sets the POSTGRES_PASSWORD environment variable, which is required by the PostgreSQL image.

Save the file and exit the nano editor (Press Ctrl + X, then Y, then Enter).

Before starting the services, we need to pull the necessary Docker images.

docker pull nginx:latest
docker pull postgres:latest

These commands download the nginx:latest and postgres:latest images from Docker Hub.

Finally, let's start the services defined in our docker-compose.yml file.

docker-compose up -d

The docker-compose up -d command builds, creates, and starts the services in the background (detached mode).

You can check the status of the running services using the following command:

docker-compose ps

You should see output indicating that both the web and db services are running.

Restart all services

In this step, we will learn how to restart all services defined in our docker-compose.yml file. Restarting services is a common operation when you make changes to your application code, configuration, or the Docker Compose file itself.

To restart all services, we use the docker-compose restart command. This command will stop all running containers defined in the docker-compose.yml file and then start them again.

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

cd ~/project

Now, execute the following command to restart all services:

docker-compose restart

You will see output indicating that the services are being stopped and then started.

After the command finishes, you can verify that the services have been restarted and are running again using the docker-compose ps command.

docker-compose ps

The output should show that both the web and db services are in the Up state, indicating they have been successfully restarted.

Restarting all services is useful when you need to apply changes that affect multiple parts of your application or when you want to ensure a clean restart of the entire application stack.

Restart a specific service

In this step, we will learn how to restart only a specific service within our multi-service application. This is useful when you've made changes to a single service and don't need to restart the entire application stack.

To restart a specific service, you use the docker-compose restart command followed by the name of the service you want to restart. The service names are defined in your docker-compose.yml file (in our case, web and db).

Make sure you are in the ~/project directory.

cd ~/project

Let's restart the web service.

docker-compose restart web

You will see output indicating that the web service is being stopped and then started. The db service will remain running.

After the command finishes, verify the status of the services using docker-compose ps.

docker-compose ps

The output should show that both web and db services are still in the Up state. However, the web service would have been stopped and started again.

Now, let's restart the db service.

docker-compose restart db

You will see output indicating that the db service is being stopped and then started. Note that because the web service depends on the db service, Docker Compose might also briefly stop and restart the web service to ensure the dependency is met during the db restart.

Verify the service status again:

docker-compose ps

Both services should be Up. Restarting individual services allows for more granular control over your application's lifecycle.

Restart a service without its dependencies

In the previous step, we saw that restarting the db service also caused the web service to briefly restart because of the depends_on relationship defined in docker-compose.yml. In some cases, you might want to restart a service without affecting its dependencies.

To restart a service without restarting its dependencies, you can use the docker-compose restart command with the --no-deps flag.

Make sure you are in the ~/project directory.

cd ~/project

Let's try restarting the db service again, this time using the --no-deps flag.

docker-compose restart --no-deps db

Observe the output. You should see that only the db service is stopped and started. The web service, which depends on db, is not affected.

Verify the service status using docker-compose ps.

docker-compose ps

Both services should still be in the Up state. This demonstrates how to restart a service in isolation, which can be useful for debugging or applying changes to a single service without disrupting others that depend on it.

Restart a service with a specific timeout

In this final step, we will learn how to specify a timeout for the restart operation. When you restart a service, Docker Compose sends a stop signal to the container and waits for it to shut down gracefully. If the container doesn't stop within a certain period, Docker forces a shutdown. You can control this waiting period using the --timeout flag.

The default timeout for stopping containers is 10 seconds. Let's try restarting the web service with a shorter timeout of 3 seconds.

Make sure you are in the ~/project directory.

cd ~/project

Now, execute the following command to restart the web service with a 3-second timeout:

docker-compose restart --timeout 3 web

You will see output indicating that the web service is being stopped and then started. Docker Compose will wait for a maximum of 3 seconds for the container to stop gracefully before forcing a shutdown.

After the command finishes, verify the service status using docker-compose ps.

docker-compose ps

Both services should still be in the Up state.

Using the --timeout flag allows you to control how long Docker Compose waits for a service to stop during a restart. This can be useful for services that require more or less time to shut down cleanly.

Finally, let's clean up the running services by stopping and removing them.

docker-compose down

The docker-compose down command stops and removes the containers, networks, and volumes created by docker-compose up.

Summary

In this lab, we learned how to prepare a simple multi-service application using Docker Compose. This involved installing Docker Compose, verifying the installation, and creating a docker-compose.yml file to define two services: a web service (nginx) and a database service (postgres), with the web service depending on the database service.

We then explored various ways to manage these services using the docker compose restart command. We learned how to restart all services defined in the docker-compose.yml file, restart a specific service, restart a service without restarting its dependencies, and restart a service with a specified timeout period. These steps demonstrated the flexibility and control offered by Docker Compose for managing the lifecycle of multi-container applications.