1. Introduction
In this tutorial, we’ll explore how to configure Docker containers to start automatically at boot. First, we’ll cover the restart policies provided by Docker. Then, we’ll learn how to apply them in different scenarios.
2. Understanding Docker Restart Policies
Docker offers built-in restart policies that control whether containers automatically start when the Docker daemon restarts or when the host system boots. These policies can be defined when creating a container or applied to an existing container.
To configure a restart policy, we must use the –restart flag with the docker run command. Thus, four restart policies are available:
Policy
Description
no
Don’t automatically restart the container. This is the default policy.
on-failure
If the container exits with a non-zero status, indicating an error, restart it. The max-retries option (on-failure[:max-retries]) allows us to specify the maximum number of restart attempts. The container doesn’t restart automatically when the daemon restarts.
always
Restart the container automatically when it stops. It’ll also start when the Docker daemon starts or restarts. It only remains stopped if manually stopped.
unless-stopped
Like always, the container doesn’t restart if stopped manually or after the Docker daemon restarts.
There are some points to consider when implementing restart policies. Firstly, a policy is only activated after the container has successfully started. The container must be running for at least 10 seconds and monitored by Docker. This precaution prevents restart loops in containers that fail to start correctly.
Furthermore, if the container ends manually, the policy is ignored. The container will only be started again when the daemon is restarted or when we run it manually.
Lastly, for containers to start at boot, the Docker itself must also be configured to start automatically when the system boots. This is typically managed by the operating system’s service manager, such as systemd on most Linux distributions:
$ sudo systemctl enable docker
So, let’s understand how to apply this policy in different situations.
3. Setting the Restart Policy When Creating a Container
To configure a restart policy when creating a container, we’ll use the following command:
$ docker run -d --restart=<policy> --name <my-container> <my-image>
The -d flag runs the container in detached mode, allowing it to run in the background. Without -d flag, the container runs in the foreground, displaying logs and output directly in the terminal. Thus, it’s not possible to run other commands in the same terminal.
So, let’s build a Docker container using an Nginx image that will always restart:
$ docker run -d --restart=always --name restart_always nginx
8eca70915f11f1e7ea0bf166a120cfbbe2df3a8aea939d67dbbcbff43dd26203
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
8eca70915f11 nginx "/docker-entrypoint..." 13 seconds ago Up 12 seconds 80/tcp restart_always
The container named restart_always was built correctly. To confirm the policy, we can restart the host or simply restart the Docker daemon:
$ systemctl restart docker
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
8eca70915f11 nginx "/docker-entrypoint..." 47 minutes ago Up 7 seconds 80/tcp restart_always
By comparing the CREATED and STATUS fields, we can see the difference between the creation time and the time the container is live. Hence, we can assume that we’ve configured the policy correctly.
4. Applying a Restart Policy to an Existing Container
Containers that are currently active and running can also have restart policies configured. To do this, use the docker update command:
$ docker update --restart=<policy> <my-container>
This command changes the container’s restart policy based on the specified option.
So, similar to the previous example, let’s create an Nginx container:
$ docker run -d --name restart_always nginx
6e984fb6e5832bdb52ffce8a9bb0d12b519782eb346209bda366e558088f1694
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6e984fb6e583 nginx "/docker-entrypoint..." 3 seconds ago Up 3 seconds 80/tcp restart_always
Another way to check the configuration of the restart policy is by using the docker inspect command:
$ docker inspect -f "{{ .HostConfig.RestartPolicy.Name }}" restart_always
no
As expected, it has the default configuration. Let’s run the docker update command to make the change:
$ docker update --restart=always restart_always
restart_always
$ docker inspect -f "{{ .HostConfig.RestartPolicy.Name }}" restart_always
always
Upon inspection, we can see that the policy has been modified. Restarting the Docker daemon will confirm that the policy is functioning as expected:
$ systemctl restart docker
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6e984fb6e583 nginx "/docker-entrypoint..." 3 minutes ago Up 4 seconds 80/tcp restart_always
5. Adding Restart Policies in Docker Compose
In scenarios where a service runs across multiple containers, it’s common to use Docker Compose. To ensure containers start automatically with the host, we can set the restart policies for each service in the docker-compose.yml file.
As an example, let’s use the following compose file to build a service that runs an Nginx container and a Redis container:
services:
redis:
image: redis
ports:
- '6379:6379'
restart: always
web:
image: nginx
ports:
- "8000:8000"
restart: always
depends_on:
- redis
Note that each service description includes the restart: always option. This ensures that when the Docker host or daemon starts, the containers will start as well.
So, let’s up the service:
$ docker compose up -d
[+] Running 3/3
✔ Network restart_always_default Created 0.1s
✔ Container restart_always-redis-1 Started 0.1s
✔ Container restart_always-web-1 Started 0.0s
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
df6022803202 nginx "/docker-entrypoint..." 5 seconds ago Up 4 seconds 0.0.0.0:80->80/tcp, :::80->80/tcp restart_always-web-1
8cafc676d18a redis "docker-entrypoint.s..." 5 seconds ago Up 4 seconds 0.0.0.0:6379->6379/tcp, :::6379->6379/tcp restart_always-redis-1
To validate the policy, let’s restart the Docker daemon:
$ systemctl restart docker
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
df6022803202 nginx "/docker-entrypoint..." 2 hours ago Up 2 seconds 0.0.0.0:80->80/tcp, :::80->80/tcp restart_always-web-1
8cafc676d18a redis "docker-entrypoint.s..." 2 hours ago Up 2 seconds 0.0.0.0:6379->6379/tcp, :::6379->6379/tcp restart_always-redis-1
6. Conclusion
In this tutorial, we studied how to configure Docker containers to start automatically. By leveraging Docker’s restart policies, we learned how to manage container behavior during host startup and Docker daemon restarts.