TL;DR
Here is how to implement Docker restart policies:
- No Restart Policy: Set up your Docker container to not restart automatically by running
docker run --restart=no [IMAGE], perfect for containers used in temporary tasks or batch jobs that need manual control over start and stop. - Always Restart Policy: Configure your Docker container to always restart if it stops by using
docker run --restart=always [IMAGE], ensuring it remains running for critical applications requiring minimal downtime. - Unless-stopped Restart Policy: Implement this policy by running d
ocker run --restart=unless-stopped [IMAGE], which keeps the container running automatically unless you explicitly stop it, ideal for maintaining service continuity through reboots unless manually halted. - On-failure Restart Policy: It restarts a container only if it exits with an error (non-zero exit status), using the command
docker run --restart=on-failure [OPTIONS] IMAGE [COMMAND] [ARG…]to maintain service reliability without unnecessary restarts.
Are you finding it tricky to manage when and how your Docker containers restart? If you juggle different environments, setting the right restart policies is essential for keeping everything running smoothly. In this post, I’ll break down Docker’s restart policies like no, always, on-failure, and unless-stopped, giving you clear, actionable steps to implement them effectively. We’ll tackle common issues together and I’ll share some best practices to make sure your Docker setups are as reliable and efficient as possible. Ready to get your Docker containers dialed in just right? Let’s get started!
What are Docker Restart Policies?
Docker restart policies determine how Docker containers should handle restarts under different circumstances, such as after crashes or when the system reboots. Setting a restart policy is essential for managing container operations efficiently, especially in production environments where automatic recovery from failures is crucial.
Here are the four most common Docker restart policies:
- No: As Docker’s default policy, it does not restart containers after they stop, ensuring they remain inactive unless manually restarted. This policy is particularly valuable in development settings, where developers need to manually control when containers run to facilitate debugging and troubleshooting without dealing with automated restarts interfering with the process.
- Always: This policy ensures that Docker will automatically restart the container no matter the reason for its stop—be it crash or manual termination. It’s especially crucial for critical services that must stay running continuously, like key web servers or databases, providing a guarantee of maximum uptime and resilience in production environments.
- On-failure: Docker applies this restart policy specifically when containers exit due to an error indicated by a non-zero exit status. This approach is essential in environments where reliability is crucial, allowing containers to attempt auto-recovery from errors while providing the option to set a limit on restart attempts to prevent endless restart loops.
- Unless-stopped: Under this policy, Docker will restart the container automatically if it stops unexpectedly or during a system reboot, unless it has been manually stopped by the operator. This balance is perfect for maintaining operational continuity without overriding user interventions, making it ideal for environments where manual control over restarts is sometimes necessary.
How to Implement Docker Restart Policies?
To implement Docker restart policies, use the docker run --restart=POLICY command, selecting no, always, on-failure, or unless-stopped as the POLICY. For example, docker run --restart=always [OPTIONS] IMAGE [COMMAND] [ARG...] ensures continuous operation, while docker run --restart=on-failure [OPTIONS] IMAGE [COMMAND] [ARG...] restarts only after failures.
That was a brief overview. For a detailed step-by-step guide on implementing Docker restart policies, continue reading below:
1. No Restart Policy
The no-restart policy is used when you want full control over when your container starts and stops. This policy is ideal for containers that don’t need to run continuously or for those that should not restart automatically under any circumstances, such as temporary workloads or batch jobs. Follow these steps to use this policy:
- Start by opening your command line interface.
- Use the Docker run command to start your container with the no restart policy. Type the following command:
sudo docker run --restart=no [IMAGE]Replace [IMAGE] with the name of the Docker image you want to use.
- You can list the running containers using the command
sudo docker psKnow the status of container before applying any policy.
- Once your container is running, you can stop it using:
sudo docker stop [CONTAINER_ID]Stops the running container manually.
- After stopping, check that it does not restart automatically. You can list the running containers using:
sudo docker psLists the current Docker containers to show their status, verifying that the stopped container hasn’t restarted.
2. Always Restart Policy
The always restart policy ensures that your container restarts automatically if it ever stops. This is useful for critical applications that must have minimal downtime. Here is how to use this restart policy:
- Launch your Terminal window and start your container with the always restart policy by entering:
sudo docker run --restart=always [IMAGE]Replace [IMAGE] with your desired Docker image.
- To verify that the container is in a running state, use the command:
sudo docker ps
- If you want to test whether the always restart policy works as expected (excluding manual stops), you can simulate a crash or an error within the container that causes it to exit abnormally. For instance:
sudo docker exec [CONTAINER_ID] /bin/sh -c 'kill 1'This command sends a signal to terminate the main process inside the container, simulating a crash.
- Check that it restarts automatically using:
sudo docker psConfirm that the container is running again after being stopped.
3. Unless-stopped Restart Policy
This policy is used when you want your container to generally restart automatically, unless you have explicitly stopped it. It’s great for ensuring that services resume after reboots unless they’ve been manually deactivated. Here is the step-by-step guide to implement this policy:
- Open your Terminal and use this command to run your container with the unless-stopped restart policy:
sudo docker run --restart=unless-stopped [IMAGE]Replace [IMAGE] with the Docker image of your choice.
- After the container starts, stop it using:
sudo docker stop [CONTAINER_ID]Replace the [CONTAINER_ID] with the docker id of your choice.
- Reboot your system by running the command:
sudo systemctl restart dockerIt will restart the docker service.
- Now check that the container does not restart with the command:
sudo docker psShows all Docker containers to confirm that the manually stopped container remains stopped even after a system reboot.
4. On-failure Docker Restart Policy
The on-failure restart policy is designed to restart your Docker container only when it exits due to an error, indicated by a non-zero exit status. This targeted approach helps maintain service reliability without burdening the system with unnecessary restarts. Follow these steps:
- Before you begin, open your Terminal and run your container with the On-failure policy:
- To set up the on-failure restart policy when you run a new container, use the command:
docker run --restart=on-failure [OPTIONS] IMAGE [COMMAND] [ARG…]Replace [OPTIONS] with any Docker options you need, IMAGE with the Docker image you are using, and [COMMAND] [ARG…] with the command and any arguments that the container should execute.
4 Best Practices for Docker Restart Policies
Implementing effective Docker restart policies helps ensure your applications run smoothly and recover from failures automatically. It’s important to understand and apply these practices to manage your containers efficiently. Here are four best practices to follow:
- 🔄 Choose the Right Policy: Select a restart policy that aligns with the container’s role. Use
alwaysfor crucial services to ensure constant availability. Opt fornooron-failureduring development or for non-critical applications, providing greater control over when containers restart. - 🔁 Set a Retry Limit: Apply a retry limit with the
on-failurepolicy to prevent endless restart attempts that can strain your system. For example, settingon-failure:3restricts Docker to three restart attempts, helping to manage resources effectively and maintain system stability. - 💾 Protect Your Data: Utilize Docker volumes to keep data separate from containers. This protects your data from being lost or corrupted during restarts or deletions, ensuring data continuity and integrity across various operational scenarios.
- 📑 Document Your Configuration: Always keep a clear record of your restart policy settings and the reasons for choosing them for each container. This documentation makes it easier to troubleshoot problems and ensures everyone on your team understands and can maintain consistency, no matter where the container runs.
Final Thoughts
In this guide, I’ve gone through the steps to implement Docker restart policies correctly. Some best practices to follow when implementing Docker restart policies, such as choosing specific policies for different needs and integrating health checks, will really help you get the most out of your Docker setups.
If you are looking to improve your Docker expertise, consider exploring topics such as learning to fix the “Command Not Found: Docker Compose” error is crucial for managing multi-container setups. Additionally, mastering how to list Docker containers can improve the management of large systems. Also, understanding how to add a user to the Docker group will aid in creating a secure and collaborative environment.
Frequently Asked Questions
What happens if Docker itself crashes or restarts—do restart policies still apply?
How can you temporarily disable a restart policy without changing Docker configuration files?
Docker update command to modify a running container’s policy. For instance, docker update --restart=no [CONTAINER_ID] changes the policy to no, stopping automatic restarts without altering the Dockerfile or configuration files permanently.Are there any specific log files that can help diagnose issues with Docker restart policies?
docker logs [CONTAINER_ID] to see logs specific to a container. Additionally, checking the system logs with journalctl -u docker.service can provide insights into Docker’s behavior and operational issues.What are the default Docker restart settings if none is specified?
no, meaning containers will not automatically restart when they exit. This default setting ensures that Docker does not attempt to manage container lifecycles without explicit configuration.What should I do if my Docker container fails to restart automatically?
docker ps -a. For containers stopped manually, the always or unless-stopped policies won’t restart them. To test restart policies, simulate a failure by running docker exec [CONTAINER_ID] /bin/sh -c 'kill 1, which forces the container to exit and triggers the restart policy.
