Beginner's Guide to Docker Restart Policy
Using a restart policy can be extremely helpful in restarting containers automatically in certain events or failures.
Docker provides a restart policy option to let your containers restart automatically in case of certain events or failures.
This is extremely helpful in scenarios where you have to restart the Docker host (your Linux server) or if the service running in the container fails.
Docker restart policies are applied on a per-container basis. There are two ways to assign restart policy to a container. You can set it in the YAML file if you are going to use Docker Compose or Swarm or Kubernetes.
You can also set the restart policy directly in the command line when you run a container:
docker container run --restart <policy>
Let's talk about what kind of restart policy you can use.
Docker restart policies
There are following restart policies for Docker containers:
- no: The default behavior is to not start containers automatically
- always: Always restart a stopped container unless the container was stopped explicitly
- unless-stopped: Restart the container unless the container was in stopped state before the Docker daemon was stopped (explained later)
- on-failure: Restart the container if it exited with a non-zero exit code or if the docker daemon restarts
As I mentioned, if you don't explicitly add a restart policy, it goes with "no", meaning containers won't be restarted automatically.
Explaining Docker restart policies with examples
Let me show these policies in action so that you can actually visualize them. This is specially useful for understanding the difference between
Always restart policy
Let's start with the
always restart policy. With this policy set, the container will always be restarted unless it was stopped explicitly.
I am going to run an Alpine Linux container with
always restart policy. I am naming it always-policy.
The container has one task. It runs the bash sleep command for 10 seconds and then exits.
docker container run --name always-policy --restart always alpine sleep 10
always restart policy, the container would have stopped after 10 seconds. But here, it will restart automatically and run the sleep command for another 10 seconds and it continues like this.
abhishek@handbook:~$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1171dcfb7e06 alpine "sleep 10" 25 seconds ago Up 4 seconds always-policy
You can see in the above command that though the container was created 25 seconds ago, it has been up for only 4 seconds. Please bear in mind that the same container is restarted, a new one is not created.
You can use the docker inspect command to see how many times the container has been restarted so far.
abhishek@handbook:~$ docker inspect always-policy | grep -i restartcount "RestartCount": 4,
If you stop the container with the stop command, it will not restart automatically afterwards. You may see in the example below that the container now has 'Exited' status instead of Up.
abhishek@handbook:~$ docker stop always-policy always-policy abhishek@handbook:~$ docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1171dcfb7e06 alpine "sleep 10" 58 seconds ago Exited (0) 6 seconds ago always-policy
I have used the
-it option for running the container with interactive terminal in the above screenshot. That was out of habit and unnecessary here.
unless-stopped vs always restart policy
unless-stopped is similar to the
always restart policy. Both restart the containers automatically and if you stop the containers explicitly, they don't restart.
But the main difference between the two is that if you stop the containers with docker stop command and then restart the docker daemon, the container with
always restart policy will start the container automatically but the container with
unless-stopped policy won't be restarted.
Let me show it with examples. I already have a stopped container with always restart policy. Let me create a new container named unless-stopped-policy with
docker container run --name unless-stopped-policy --restart always alpine sleep 10
Stop the container:
docker stop unless-stopped-policy
Now I have two containers who have been explicitly stopped:
abhishek@handbook:~$ docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES d244b6e08899 alpine "sleep 10" 2 minutes ago Exited (0) About a minute ago unless-stopped-policy 1171dcfb7e06 alpine "sleep 10" 22 minutes ago Exited (0) 21 minutes ago always-policy
Restart Docker daemon:
sudo systemctl restart docker
Now if you check the running containers, you can see that the container named always-policy is running because it was set with
always restart policy.
abhishek@handbook:~$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1171dcfb7e06 alpine "sleep 10" 30 minutes ago Up 8 seconds always-policy
The entire steps can be seen in this screenshot:
on-failure restart policy
on-failure restart policy restarts a container if it was exited with a non-zero exit code (indicating error/failure). It also restarts the containers if the docker daemon restarts including the ones that were in the stopped state before.
If you manually stop a container with docker stop command, it exists with code zero indicating everything was normal.
Setting restart policy in Docker Compose file
By now, you have a pretty good idea about running a container with a restart policy.
If you are using something like Docker Compose for deploying containers, you can mention the restart policy for the service object in YAML file.
Here's a sample example:
version: "3.3" services: NginxProxy: image: "jwilder/nginx-proxy:latest" restart: "on-failure" networks: ["net"] ports: - "80:80" - "443:443"
Which Docker restart policy to use?
Honestly, there is no straightforward answer to this question. It depends on your use case and what you want.
I hope this article was helpful for understanding the Docker restart policy. If you have any questions or suggestions, please let me know in the comment section.