14.3. Restart Policies
Table of Contents
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.
Core rule: Every restart policy is attached to a container and controls whether Docker automatically starts it again after it stops, crashes, or after the Docker daemon or host is restarted.
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.
Key syntax:
Use --restart=<policy> or --restart=on-failure:<max-retries> with docker run.
For example: --restart=on-failure:5.
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.
Views: 0
Where to Move
Move chapter:
- ☰ 1. Introduction
- ☰ 1.1. What is Docker?
- ☰ 1.2. Why Docker?
- ☰ 1.3. Virtual Machines vs Containers
- ☰ 1.4. When Not to Use Docker
- ☰ 1.5. How Docker Is Used in Real Projects
-
- ☰ 2. Core Concepts
- ☰ 2.1. Images
- ☰ 2.2. Containers
- ☰ 2.3. Docker Engine and Architecture
- ☰ 2.4. Docker Hub and Container Registries
- ☰ 2.5. Tags, Versions, and Digests
-
- ☰ 3. Installing Docker
- ☰ 3.1. Docker on Linux
- ☰ 3.2. Docker on Windows
- ☰ 3.3. Docker on macOS
- ☰ 3.4. Verifying the Installation
- ☰ 3.5. Common Installation Issues
-
- ☰ 4. Your First Docker Container
- ☰ 4.1. Running Your First Container
- ☰ 4.2. Understanding `docker run`
- ☰ 4.3. Interactive vs Detached Mode
- ☰ 4.4. Stopping and Removing Containers
- ☰ 4.5. Listing Containers
-
- ☰ 5. Working with Docker Images
- ☰ 5.1. Pulling Images from Docker Hub
- ☰ 5.2. Listing and Removing Images
- ☰ 5.3. Image Layers Explained
- ☰ 5.4. Image Size Optimization
- ☰ 5.5. Inspecting Images
-
- ☰ 6. Dockerfiles – Building Your Own Images
- ☰ 6.1. What Is a Dockerfile?
- ☰ 6.2. Basic Dockerfile Structure
- ☰ 6.3. Common Instructions (`FROM`, `RUN`, `COPY`, `CMD`, `ENTRYPOINT`)
- ☰ 6.4. Building Images with `docker build`
- ☰ 6.5. Best Practices for Dockerfiles
- ☰ 6.6. Multi-Stage Builds
-
- ☰ 7. Managing Data with Volumes
- ☰ 7.1. Why Containers Are Ephemeral
- ☰ 7.2. Bind Mounts vs Volumes
- ☰ 7.3. Creating and Using Volumes
- ☰ 7.4. Inspecting and Removing Volumes
- ☰ 7.5. Real-World Examples
-
- ☰ 8. Networking in Docker
- ☰ 8.1. Docker Networking Basics
- ☰ 8.2. Bridge Networks
- ☰ 8.3. Port Mapping
- ☰ 8.4. Container-to-Container Communication
- ☰ 8.5. Custom Networks
-
- ☰ 9. Docker Compose
- ☰ 9.1. Why Docker Compose?
- ☰ 9.2. `docker-compose.yml` Structure
- ☰ 9.3. Defining Services, Networks, and Volumes
- ☰ 9.4. Running Multi-Container Applications
- ☰ 9.5. Web App and Database Example
- ☰ 9.6. Docker Compose Best Practices
-
- ☰ 10. Debugging and Monitoring Containers
- ☰ 10.1. Viewing Logs
- ☰ 10.2. Executing Commands in Running Containers
- ☰ 10.3. Inspecting Containers
- ☰ 10.4. Resource Usage
- ☰ 10.5. Common Errors and Fixes
-
- ☰ 11. Security Basics
- ☰ 11.1. Running Containers as Non-Root
- ☰ 11.2. Image Trust and Verification
- ☰ 11.3. Secrets and Environment Variables
- ☰ 11.4. Reducing Attack Surface
- ☰ 11.5. Security Best Practices
-
- ☰ 12. Performance and Optimization
- ☰ 12.1. Reducing Image Size
- ☰ 12.2. Caching and Layer Ordering
- ☰ 12.3. Resource Limits
- ☰ 12.4. Choosing the Right Base Image
-
- ☰ 13. Docker in Development Workflows
- ☰ 13.1. Docker for Local Development
- ☰ 13.2. Hot Reloading with Volumes
- ☰ 13.3. Docker and Git
- ☰ 13.4. Docker in CI/CD Pipelines
- ☰ 13.5. Common Development Patterns
-
- ☰ 14. Deployment Basics
- ☰ 14.1. Running Containers in Production
- ☰ 14.2. Environment Configuration
- ☰ 14.3. Restart Policies
- ☰ 14.4. Logging Strategies
- ☰ 14.5. Basic Scaling Concepts
-
- ☰ 15. Beyond the Basics
- ☰ 15.1. Docker Swarm Overview
- ☰ 15.2. Kubernetes vs Docker
- ☰ 15.3. Container Registries
- ☰ 15.4. When to Move Beyond Docker
-
- ☰ 16. Practical Projects
- ☰ 16.1. Dockerizing a Simple Web App
- ☰ 16.2. Dockerizing a Backend API
- ☰ 16.3. Full-Stack App with Docker Compose
- ☰ 16.4. Common Project Pitfalls
-
- ☰ 17. Troubleshooting and FAQ
- ☰ 17.1. Common Beginner Mistakes
- ☰ 17.2. Docker Command Cheat Sheet
- ☰ 17.3. FAQ
- ☰ 17.4. Useful Resources
-
Comments
Please login to add a comment.
Don't have an account? Register now!