WittCode💻

Restarting Containers with Docker Compose

By

Learn how Docker Compose restarts containers, Docker's restart policy, and the restart and restart_policy Docker attributes.

Table of Contents 📖

Docker Compose Restart Policies

Docker containers can fail and crash unexpectedly. Therefore, Docker has restart policies to manage these container failures. We can configure Docker's restart policy with the restart attribute as shown in this docker-compose.yaml file.

version: '3.9'
services:
  restart-example:
    image: restart-example
    container_name: r-c
    build:
      context: .
      dockerfile: Dockerfile
    restart: always

The restart attribute accepts 4 different options.

  • no - Never restart the container. The default restart policy.
  • always - Always restart the container on termination. If the container is manually stopped, it will be restarted when the Docker daemon restarts.
  • on-failure - Restart the container if the container exits with an error exit code. We can also limit the number of retries with this option.
  • unless-stopped - Does the same as always but will not restart a manually stopped container after the Docker daemon restarts.

Docker Compose Restart Demonstrations

As an example, consider the following Docker configuration. This creates a container that will run for 5 seconds before exiting.

FROM busybox:latest
COPY --chmod=755 <<"EOF" /start.sh
echo "Starting..."
for i in $(seq 1 5); do
  echo "$i"
  sleep 1
done
echo "Exiting..."
exit 1
EOF
ENTRYPOINT /start.sh

We will create this container with docker compose using the docker-compose.yaml file above. First, we will demonstrate always.

restart: always

docker compose up
r-c  | Starting...
r-c  | 1
r-c  | 2
r-c  | 3
r-c  | 4
r-c  | 5
r-c  | Exiting...
r-c exited with code 1
r-c  | 2
r-c  | 3
r-c  | 4
çr-c  | 5
r-c  | Exiting...
r-c exited with code 1
...
...

Note how the container is restarting each time it exits. We can set restart to no so that it won't restart.

restart: no

docker compose up
r-c  | Starting...
r-c  | 1
r-c  | 2
r-c  | 3
r-c  | 4
r-c  | 5
r-c  | Exiting...
r-c exited with code 1

The on-failure option will restart if the container exits with an error exit code, like exit code 1 that we have in script we created.

restart: on-failure

docker compose up
r-c  | Starting...
r-c  | 1
r-c  | 2
r-c  | 3
r-c  | 4
r-c  | 5
r-c  | Exiting...
r-c exited with code 1
r-c  | 2
r-c  | 3
r-c  | 4
r-c  | 5
r-c  | Exiting...
r-c exited with code 1
...
...

We can limit the number of times the Docker daemon attempts to restart the container by appending a number to the end of the on-failure option.

restart: on-failure:3

This tells Docker Compose to limit the number of restarts to 3. However, if we set the exit code to be 0, then we will not restart.

exit 0

docker compose up
r-c  | Starting...
r-c  | 1
r-c  | 2
r-c  | 3
r-c  | 4
r-c  | 5
r-c  | Exiting...
r-c exited with code 0

The final option we can set restart to is unless-stopped.

restart: unless-stopped

docker compose up
r-c  | Starting...
r-c  | 1
r-c  | 2
r-c  | 3
r-c  | 4
r-c  | 5
r-c  | Exiting...
r-c exited with code 0
r-c  | 2
r-c  | 3
r-c  | 4
r-c  | 5
r-c  | Exiting...
r-c exited with code 0

The unless-stopped option does the same thing as always except that when the container is stopped manually, it isn't restarted even after the Docker daemon starts.

Docker Compose restart_policy

We can also configure a container's restart behavior with the restart_policy attribute. Setting the restart_policy attribute will replace the restart attribute. This attribute is essentially the same as the restart attribute, just with more options. These are condition, delay, max_attempts, and window.

restart_policy:
  condition: on-failure
  delay: 5s
  max_attempts: 3
  window: 60s
  • condition - Either none, on-failure, or any. None means containers are not restarted regardless of exit status. On-failure means that the container is restarted if it exits with a non-zero exit code. Any means that the container is restarted regardless of exit status. Any is the default value.
  • delay - How long to wait between restart attempts. The default is 0 meaning restarts occur immediately.
  • max_attempts - Number of retry attempts before giving up. Default is to never give up.
  • window - How long to wait before deciding if a restart has succeeded. Default is to decide immediately.

These options are essentially the same as the ones we saw previously except for the presence of the delay and window options providing slightly more customization.

Restarting Containers with Docker Compose