Docker gives you several options to manage your container’s lifecycle. Containers do not normally restart automatically after they terminate. With restart policies, you can take control over individual container lifecycles.
Restart policies will be used whenever a container stops running. Docker also looks at restart policies when the daemon starts up. You can use this mechanism to bring containers up with your host after reboots.
There are currently four different restart policies:
no– This policy will never automatically start a container. This is the default policy for all containers created with
always– Docker will ensure the container is always running. If the container stops, it will be immediately restarted. You can still manually stop the container with
docker stopbut Docker will bring it back up next time the daemon restarts.
on-failure– The container will get restarted if it stops because of an error. Docker won’t bring the container up after the daemon restarts.
unless-stopped– This functions similarly to
always. The difference is that Docker won’t ever restart the container if it has been manually stopped.
You’ll typically use one of the last three options for production workloads. As Docker containers are often used for long-running background services, you usually want them to restart whenever anything goes wrong. The
no policy is best suited to local development use. It’s also useful for utility containers which run a single executable and then terminate.
It can be difficult to decide which restart policy to use.
always is often the most natural choice but the daemon restart behaviour can easily be overlooked. If you want containers to reliably stay stopped after you’ve run
docker stop, you should use
Docker detects errors based on the exit code emitted from the container’s foreground process. An exit code of
1 or higher is interpreted as an error. This matches the Unix handling of exit codes, where only
0 represents a successful execution.
When Docker restarts your container, it’s equivalent to running
docker run again. That means the image’s
ENTRYPOINT script will be invoked. Bootstrap systems should always be resilient to multiple invocations.
Applying a Restart Policy
You can start a container with a specific restart policy by passing the
--restart flag to
docker run --name httpd --restart always httpd:latest
If you’re using Docker Compose, add the
restart field to your
services: httpd: image: httpd:latest restart: always
You can change the restart policy of an existing container using
docker update. Pass the name of the container to the command. You can find container names by running
docker ps -a.
docker update --restart-policy unless-stopped httpd
You can use
docker update with containers that are running or stopped.
Docker includes a couple of safeguards against perpetual restart loops. The first is a mandatory time delay before restart policies activate. Docker won’t begin monitoring restarts until a container has been running for at least 10 seconds. This prevents a failed container from continually restarting.
The other specialist behaviour concerns the
docker stop command. Docker will always respect use of
docker stop, so the container won’t immediately restart after you run the command. If you actually want to restart the container, use
docker restart instead.
Limiting Restart Retries
on-failure restart policy lets you specify how many retries should be attempted. Docker will give up and leave the container in a stopped state if it fails to start multiple times in succession.
docker run httpd:latest --restart on-failure:5
In this example, Docker will try to restart the container five times after a failure (non-zero exit code). If the container fails to start on the fifth attempt, no more retries will be attempted. This option is useful for containers where a persistent starting error is unlikely to be resolved without manual intervention.
Investigating Why Containers Stopped
If you need to know why a container stopped, run
docker ps -a. This will show the details of all your containers, whether stopped or running. Find the target container and look in its “Status” column. For stopped containers, the exit code will be shown in brackets. If the code is greater than zero, the container terminated due to an error.
You’d need to refer to the documentation for the process running in the container to determine the meanings of individual error codes. However, you can often get insights into what caused a crash by retrieving the container’s logs. Logs remain available after a container is stopped.
docker logs my-container
The log stream aggregates the container’s standard output and standard error streams. If the error’s been logged, you should expect to see it in the last few lines of output.
Restart policies help ensure your Docker containers are there when you need them. The default
no policy is unsuitable for most production workloads. You don’t want your containers to stay stopped if they crash!
Use of one of the three restart-capable policies makes your containers more resilient to hardware reboots and unexpected termination. Docker will maintain service availability in the event of a container crash.