How to Use docker compose restart

The docker compose restart command addresses challenges in managing multi-container applications created with Docker Compose. It handles actions such as applying configuration updates or recovering from service malfunctions.

The command provides a straightforward way to refresh services, ensuring applications remain responsive and up-to-date.

This article teaches you how to use docker compose restart.

Prerequisites

• Docker installed.
• Non-root user access in Docker.

What Is docker compose restart Command?

The docker compose restart command stops and immediately restarts services defined in a project's docker-compose.yml file. It is equivalent to running docker compose stop followed by docker compose start.

When Should You Use docker compose restart?

Use docker compose restart to reinitialize services without recreating their underlying containers. The command is suitable for applying minor configuration adjustments, clearing container memory, or restarting an unresponsive service.

docker compose restart Syntax

The basic syntax for the docker compose restart command is:

docker compose restart [options] [services]

The command has the following arguments:

• [options]. Optional flags that the user can pass to modify the command's behavior.
• [services]. Allows the user to specify the names of one or more services to restart (as defined under the services section in the relevant docker-compose.yml file).

docker compose restart Options

The docker compose restart command features two optional flags:

• -t, --timeout [number]. Specifies a shutdown timeout (in seconds) before sending a SIGKILL signal. The default is 10 seconds.
• --no-deps. Tells Docker Compose not to restart linked services.

How to Use docker compose restart

The following list showcases ways to apply docker compose restart to a Docker Compose project. Execute all the commands from the directory containing the relevant docker-compose.yml file:

• Restart all services:

docker compose restart

The output confirms that the services restarted successfully.

• Restart a specific service, for example, a service named nginx:

docker compose restart nginx

• Restart multiple specific services, e.g., nginx and node-app:

docker compose restart nginx node-app

• Restart a service with a custom timeout, for instance, restart nginx with a 5-second timeout:

docker compose restart -t 5 nginx

• Restart a service without restarting any services it depends on (as defined by depends_on in the relevant docker-compose.yml):

docker compose restart --no-deps nginx

docker compose restart Common Pitfalls

The list below contains important considerations and potential issues that can arise when working with the docker compose restart command:

• Incorrect directory. Running the command outside the directory containing docker-compose.yml results in an error. Ensure the command executes in the correct project directory.
• Service not found. Attempting to restart a service that is not defined in docker-compose.yml fails. Verify service names before executing the command.
• Container health issues. A container may restart but then immediately exit due to underlying application errors. Inspect container logs using docker compose logs [service] to diagnose startup failures.
• Port conflicts. If a service restarts and attempts to bind to a port already in use by another process on the host, the restart will fail. Identify the conflicting process or modify port mappings.
• Volume corruption. In rare cases, frequent restarts or improper shutdowns can lead to data corruption in volumes. Consider creating backups or implementing data persistence strategies to ensure data integrity.

Conclusion

This article showed how to use the docker compose restart command for managing Dockerized multi-container applications. The article covered the command syntax, options, appropriate use cases, and tips for troubleshooting common problems.

Next, learn how to use Docker Compose to set up and use a private Docker registry.