14.3 Restart Policies

Why Restart Policies Matter

Containers are designed to be disposable. In production, however, you usually want key services to come back automatically after failures, crashes, or host restarts. Restart policies give Docker instructions about when and how to restart containers without manual intervention.

Restart policies are configured when you start a container and become part of that container’s definition. Once set, they continue to apply until the container is removed.

The Main Restart Policy Types

Docker supports several predefined restart policies that you choose with the --restart option in docker run. Each one defines when Docker should try to restart the container.

The most important policies are:

no is the default policy. Docker will not try to restart the container automatically, no matter why it stopped. This is useful for short lived tasks, such as one off scripts or batch jobs where automatic restarts would not make sense.

always tells Docker to always restart the container if it stops. This includes exits with an error, normal exits, and restarts of the Docker daemon or the host. If you explicitly stop the container, Docker will still start it again after the next daemon or host restart. This policy is very aggressive and is often used for critical long running services that must always be up.

on-failure restarts the container only if it exits with a non zero exit code, which usually signals an error. When the container exits normally with code 0, Docker does not restart it. You can also set a maximum number of restart attempts with this policy, which prevents infinite restart loops if something is fundamentally broken.

unless-stopped restarts the container whenever Docker starts, as long as the container was not explicitly stopped by a user. If the container crashes or exits, Docker restarts it. If you run docker stop, Docker remembers that you chose to stop it and will not bring it back automatically after a daemon or host restart.

Configuring Restart Policies with `docker run`

Restart policies are applied when you create a container, most commonly through docker run. You attach the policy with the --restart option.

For example, to run a web application so that Docker always brings it back if it stops, you might use:

docker run --restart=always ...

The on-failure policy supports a limit on the number of restarts. This is expressed as on-failure:N where N is the maximum number of restart attempts.

A typical use could be:

docker run --restart=on-failure:5 ...

Here, Docker will try to restart the container up to 5 times if it exits with a non zero exit code. After the fifth failed attempt, Docker gives up and leaves the container stopped.

unless-stopped is useful when you want the container to behave like a long running service, but you also want the ability to stop it in a way that survives system reboots. You might run:

docker run --restart=unless-stopped ...

If the container exits by itself, Docker restarts it. If you stop it manually, Docker does not start it again automatically after a reboot.

How Restart Policies Behave on Daemon and Host Restarts

Restart policies are especially relevant when the Docker daemon stops or the host machine reboots. Docker keeps track of which containers have restart policies and what their last state was.

With the no policy, nothing is restarted automatically after the daemon starts again. Any containers that were running remain stopped until you start them manually or through some external process.

With always, Docker starts the container whenever the daemon starts, regardless of why the container stopped before. This makes your container behave much like a traditional system service.

With on-failure, Docker evaluates the container exit code when it stopped. If it had failed and the maximum number of retries has not been reached, Docker will restart it when possible. If it had exited cleanly with code 0, it stays stopped even after daemon restarts.

With unless-stopped, Docker restarts the container whenever the daemon restarts, as long as the container was not deliberately stopped by a user. If you had run docker stop before the host rebooted, Docker will remember that and leave the container stopped afterwards.

Updating Restart Policies of Existing Containers

Restart policies are not limited to the moment you create a container. You can change them later without recreating the container. This is helpful when you refine your deployment behavior or fix an overly aggressive or too relaxed policy.

To modify the policy of an existing container, you can use a Docker command that updates container configuration. When you change the policy, Docker applies it the next time the container stops and is considered for restart. The container ID and its filesystem are not affected, only the restart behavior changes.

If a container already has a counters based on-failure policy, adjusting it will reset how Docker handles future failures. Past failures are not retried again, but new exits follow the updated policy.

Choosing Policies for Different Use Cases

Picking the correct restart policy is an important design decision since it affects how your application behaves during failures and host events.

For stateful databases, unless-stopped is a common choice. The database should almost always run, but administrators sometimes need to stop it intentionally and keep it offline across reboots. always might be too aggressive here because it ignores the intent to stop the container once the system comes back.

For stateless web services that must be highly available, always is attractive, particularly when combined with other deployment tools. This policy ensures that if the service crashes or the host reboots, the container comes back as soon as Docker is available.

For batch jobs and scheduled tasks, on-failure often makes more sense. You may want Docker to retry transient failures a few times, but if the job runs successfully, you probably want it to stay completed. Combining on-failure with a retry limit helps avoid endless restart loops due to persistent errors.

For experimental containers and development environments, the default no is typically enough. Automatic restarts can hide problems or complicate debugging if you are not expecting them.

Restart Policies and Production Reliability

Restart policies are only one part of a reliable deployment. They ensure that containers behave predictably when unexpected exits or host events occur, but they do not replace monitoring, alerting, or proper health checks.

A container that restarts repeatedly may indicate deeper issues, such as misconfiguration, missing dependencies, or bugs in the application. Restart policies can keep the service available for short outages, but long term reliability still depends on understanding and fixing the underlying causes.

In a simple production environment, thoughtful use of always, unless-stopped, or on-failure integrated with your logging and monitoring strategy gives you a basic form of self healing behavior. This is an important step toward more advanced orchestration, where similar ideas are applied at scale and coordinated across many containers and hosts.