Restart policies in Docker - Commands & Configuration

Introduction

When a container crashes or the host machine reboots, Docker does not restart it by default. Restart policies tell Docker what to do automatically — whether to always restart, restart only on failure, or never restart.

When you run a web server that must stay running even if it crashes unexpectedly.

When you want containers to start automatically after a host server reboot.

When you run background workers and want them restarted only if they exit with an error.

When you run one-time task containers and want to make sure they never restart after completing.

When you deploy long-running services in production that must self-heal without manual intervention.

Commands

Runs an nginx container that always restarts automatically — whether it crashes, exits cleanly, or the Docker daemon restarts.

Terminal

docker run -d --restart always nginx

Expected Output

b2c3d4e5f6a7890bcdef1234567890abcdef1234567890abcdef1234567890ab

→

--restart always - Restarts the container under any exit condition including Docker daemon restart

Runs a worker container that restarts only if it exits with a non-zero error code, up to a maximum of 3 attempts.

Terminal

docker run -d --restart on-failure:3 my-worker

Expected Output

c3d4e5f6a7b8901cdef1234567890abcdef1234567890abcdef1234567890abc

→

--restart on-failure:3 - Restarts on error exit only, max 3 retries before giving up

Inspects the restart policy of the running nginx container to confirm it is set correctly.

Terminal

docker inspect --format='{{.HostConfig.RestartPolicy.Name}}' nginx

Expected Output

always

Updates the restart policy of an already running container without restarting it. 'unless-stopped' restarts automatically except when manually stopped.

Terminal

docker update --restart unless-stopped nginx

Expected Output

nginx

→

--restart unless-stopped - Restart automatically unless the container was explicitly stopped by the user

Key Concept

If you remember nothing else from this pattern, remember: use --restart always for services that must never go down, and --restart on-failure for workers where a clean exit means the job is done.

Common Mistakes

Using --restart always for batch jobs or one-time tasks

The container restarts forever even after successfully completing its work, wasting resources.

Use --restart on-failure for jobs that should only retry on errors, or no restart policy for one-time tasks.

Forgetting that 'always' restarts even after a manual docker stop

After restarting Docker daemon, containers with 'always' come back even if you stopped them intentionally.

Use --restart unless-stopped so manually stopped containers stay stopped after a daemon restart.

Not setting any restart policy for production services

The container stays down after a crash until someone manually restarts it, causing downtime.

Always set --restart unless-stopped or --restart always for production services.

Summary

Use --restart always to keep a container running under any exit condition including daemon restarts.

Use --restart on-failure:N to retry only on error exits up to N times — good for workers.

Use --restart unless-stopped to auto-restart except when you explicitly stop the container.

Practice

1. What does the --restart=always policy do when used with docker run?

easy

A. It restarts the container only if it exits with an error.

B. It never restarts the container automatically.

C. It restarts the container automatically whenever it stops, no matter the reason.

D. It restarts the container only if manually triggered.

Solution

1. Step 1: Understand the restart policy options

   The --restart flag controls when Docker restarts a container automatically.

2. Step 2: Analyze the always policy

   The always policy means Docker restarts the container whenever it stops, regardless of exit status or manual stop.

3. Final Answer:

   It restarts the container automatically whenever it stops, no matter the reason. -> Option C

4. Quick Check:

   --restart=always = restart always [OK]

Hint: Always means restart no matter what, even manual stops [OK]

Common Mistakes:

• Confusing 'always' with 'on-failure'
• Thinking 'always' ignores manual stops
• Mixing 'no' restart with 'always'

2. Which of the following is the correct syntax to run a container with a restart policy that restarts only on failure?

easy

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

B. docker run --restart=always myimage

C. docker run --restart unless-stopped myimage

D. docker run --restart=no myimage

Solution

1. Step 1: Recall the syntax for restart policies

   The correct syntax uses --restart=policy[:max-retries] with an equals sign and optional retry count.

2. Step 2: Identify the option that matches restart on failure with max retries

   on-failure:5 means restart only if the container fails, up to 5 times.

3. Final Answer:

   docker run --restart=on-failure:5 myimage -> Option A

4. Quick Check:

   Correct syntax uses equals sign and policy [OK]

Hint: Use --restart=policy with equals sign, e.g. --restart=on-failure [OK]

Common Mistakes:

• Missing equals sign (=) after --restart
• Using wrong policy names or formats
• Confusing 'always' with 'on-failure'

3. What will happen if you run this command?

docker run --restart=unless-stopped myapp

medium

A. The container restarts unless you manually stop it.

B. The container restarts always, even if stopped manually.

C. The container never restarts automatically.

D. The container restarts only if it fails, not if stopped manually.

Solution

1. Step 1: Understand the 'unless-stopped' policy

   This policy restarts the container automatically except when you stop it manually.

2. Step 2: Apply the policy to the command

   Since the command uses --restart=unless-stopped, the container will restart on failures or Docker daemon restarts, but not if manually stopped.

3. Final Answer:

   The container restarts unless you manually stop it. -> Option A

4. Quick Check:

   unless-stopped means restart except manual stop [OK]

Hint: 'unless-stopped' means restart except manual stop [OK]

Common Mistakes:

• Thinking it restarts always even after manual stop
• Confusing 'unless-stopped' with 'on-failure'
• Assuming no restart happens

4. You tried to run a container with this command:

docker run --restart always:3 myimage

Why does it fail?

medium

A. The container name is missing.

B. The image name is invalid.

C. The '--restart' flag is misspelled.

D. The 'always' policy does not accept a retry count.

Solution

1. Step 1: Check the restart policy syntax

   The always policy does not support a retry count suffix like ':3'. Only on-failure accepts that.

2. Step 2: Identify the cause of failure

   Using always:3 is invalid syntax, so Docker rejects the command.

3. Final Answer:

   The 'always' policy does not accept a retry count. -> Option D

4. Quick Check:

   always policy has no retry count [OK]

Hint: 'always' policy never uses retry count suffix [OK]

Common Mistakes:

• Adding retry count to 'always' policy
• Assuming all policies accept retry counts
• Ignoring error messages from Docker

5. You want a container to restart automatically only if it crashes, but not if you stop it manually. Which restart policy and command should you use?

hard

A. docker run --restart=always mycontainer

B. docker run --restart=on-failure mycontainer

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

D. docker run --restart=no mycontainer

Solution

1. Step 1: Understand the requirement

   The container should restart only if it crashes (fails), but not if stopped manually.

2. Step 2: Match the restart policy

   on-failure restarts the container only when it exits with an error, ignoring manual stops.

3. Step 3: Verify the command

   The command docker run --restart=on-failure mycontainer correctly applies this policy.

4. Final Answer:

   docker run --restart=on-failure mycontainer -> Option B

5. Quick Check:

   on-failure = restart only on crash [OK]

Hint: Use 'on-failure' to restart only on crashes, not manual stops [OK]

Common Mistakes:

• Using 'always' which restarts even after manual stop
• Using 'unless-stopped' which restarts after manual stop
• Choosing 'no' which disables restart