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.

Available Policies

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

          docker run
      

  .

•         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 stop but 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

        unless-stopped
    

.

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
    

:

docker run --name httpd --restart always httpd:latest

If you're using Docker Compose, add the restart field to your docker-compose.yml:

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.

Restart Loops

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

The 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.

Summary

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.