Docker Mastery: Docker Restart Policies Explained with Practical Demo

This chapter covers the inner workings of Docker restart policies, exploring how containers behave during Docker daemon restarts, system reboots, and application failures. Through a series of hands-on demonstrations using Nginx and HTTPD on an AWS EC2 instance, we examine all four Docker restart policies alongside advanced container update and cleanup flags.

1. Why Do We Need Restart Policies? (Problem Statement)

By default, when a Docker container finishes its task, crashes due to an application error, or when the host machine/Docker daemon restarts, the container remains in an Exited state. In production environments, manually restarting containers after every server reboot or transient crash is unfeasible.

Docker Restart Policies automate this lifecycle management, defining precisely how the Docker daemon should handle container restarts under various system events.

2. Core Mental Model & The Four Restart Policies

Think of a Docker restart policy as a set of operational instructions given to a hotel receptionist regarding how to handle guests (containers) when the power grid resets or when a guest causes a disturbance.

Docker provides four distinct restart policies:

3. Environment Cleanup & Prerequisites

Before executing hands-on experiments, it is vital to clean up existing containers and images to maintain a pristine environment.

# Forcefully remove all containers (running and exited)
docker rm -f $(docker ps -aq)

# Forcefully remove all downloaded images
docker rmi -f $(docker images -q)

# Verify clean state
docker ps -a
docker images

4. Policy 1: Default (no)

When you launch a container without specifying a restart flag, Docker assigns the default policy: no.

Hands-on Demonstration

# Run an Nginx container in detached mode with a custom name
docker run -d --name nginx-default nginx

# Inspect the container's restart policy
docker inspect nginx-default | grep -i -A 3 "restartpolicy"

Output snippet from inspection:

"RestartPolicy": {
    "Name": "no",
    "MaximumRetryCount": 0
}

Behavior Analysis

1. Restarting the Docker service (sudo systemctl restart docker) causes nginx-default to transition to an Exited state.
2. Rebooting the host AWS EC2 instance leaves the container stopped.
3. Verdict: Unsuitable for production web servers because any infrastructure hiccup leaves your application offline.

5. Policy 2: always

The always policy instructs the Docker daemon to restart the container unconditionally, regardless of how it stopped (even if it was manually stopped or encountered an error).

Hands-on Demonstration

# Pull and run an Apache HTTPD container with the 'always' restart policy
docker run -d --name httpd-always --restart always httpd

# Verify the policy using inspect and grep
docker inspect httpd-always | grep -i -A 3 "restartpolicy"

Real-World Production Behavior

• Docker Daemon Restart (sudo systemctl restart docker): The container automatically comes back up.
• Host OS Reboot: Once the EC2 instance reconnects and the Docker daemon starts, the container automatically resumes running.
• Manual Stop (docker stop httpd-always): During runtime, the container stops. However, upon the next Docker service restart or host reboot, it will start up again.

6. Policy 3: unless-stopped

The unless-stopped policy is identical to always, with one crucial operational difference: if an administrator manually stops the container, Docker respects that intent. It will not restart the container upon daemon restart or system reboot until it is manually started again.

Hands-on Demonstration

# Run HTTPD with the 'unless-stopped' policy
docker run -d --name httpd-unless-stopped --restart unless-stopped httpd

# Verify policy via inspect
docker inspect httpd-unless-stopped | grep -i -A 3 "restartpolicy"

Flow Walkthrough (Manual Stop & Reboot Test)

7. Policy 4: on-failure (with Max Retry Limits)

The on-failure policy restarts a container only if it exits with a non-zero exit code (indicating an application crash or error). You can also configure a maximum retry count to prevent infinite restart loops.

Hands-on Demonstration with Retry Limits

# Run Nginx with on-failure policy and a maximum of 6 retries
docker run -d --name nginx-onfail --restart on-failure:6 nginx

# Verify configuration
docker inspect nginx-onfail | grep -i -A 4 "restartpolicy"

Forcing an Application Failure

1. Exec into the running Nginx container:
   BASH

   Copy

   docker exec -it nginx-onfail /bin/bash
   

2. Corrupt the primary Nginx configuration file to trigger a startup failure:
   BASH

   Copy

   echo "fatal error syntax" >> /etc/nginx/nginx.conf
   exit
   

3. Restart the Docker daemon to trigger the failure loop:
   BASH

   Copy

   sudo systemctl restart docker
   

4. Monitor container restarts in real-time using watch:
   BASH

   Copy

   watch docker ps -a
   

   (Notice the container repeatedly failing and retrying up to the maximum count of 6). Press Ctrl + C to exit the watch screen.

8. Modifying Existing Containers with docker update

What happens if you deployed a container without a restart policy and need to apply one without destroying or recreating the container? Docker allows live updates using docker update.

# Run a container with default (no) policy
docker run -d --name legacy-app nginx

# Update the restart policy on-the-fly to 'always'
docker update --restart always legacy-app

# Inspect to confirm the update
docker inspect legacy-app | grep -i -A 3 "restartpolicy"

9. Bonus: Automatic Cleanup with --rm

While not strictly a restart policy, the --rm flag solves a related operational problem: cluttering your disk with stopped, exited containers.

# Run an interactive Ubuntu container that auto-deletes upon exit
docker run --rm -it --name temp-ubuntu ubuntu /bin/bash

# Inside container, type:
exit

# Verify container is completely gone (does not appear in docker ps -a)
docker ps -a

Comparison: Restart Policies vs. --rm

• Restart Policies (always, unless-stopped, on-failure): Designed for persistent services that need to survive restarts and crashes.
• --rm Flag: Designed for ephemeral tasks, testing, and one-off builds where you want zero footprint left behind after execution.

Summary and Key Takeaways

• Definition: Restart policies dictate how Docker manages container lifecycles following container exits, daemon restarts, and host system reboots.
• Default Policy (no): Containers remain in an Exited state when stopped or rebooted; requires manual intervention.
• always Policy: Unconditionally restarts containers on failure, daemon restart, or host reboot, even if manually stopped during prior runtimes.
• unless-stopped Policy: Similar to always, but respects manual administrative stops—if you stop it, it stays stopped across reboots until explicitly started.
• on-failure Policy: Restarts containers only when they crash (non-zero exit code), supporting bounded retry limits (e.g., --restart on-failure:5).
• Live Updates: Existing containers can have their restart policies modified dynamically using docker update --restart <policy> <container_id>.
• Ephemeral Cleanup: The --rm flag automatically purges containers upon exit, preventing exited-state clutter for temporary runs.