Restart policies in Docker - Step-by-Step Execution

Process Flow - Restart policies

Start Container

↓

Container Stops?

No→Keep Running

Yes↓

Check Restart Policy

↓

no

→Do Not Restart

↓

always

→Restart Container

↓

on-failure

→Restart if Exit Code != 0

↓

unless-stopped

→Restart unless Manually Stopped

↓

Restart Container

↓

Container Stops?

This flow shows how Docker checks if a container stops and then applies the chosen restart policy to decide whether to restart it.

Execution Sample

Docker

docker run --restart=on-failure:2 myapp
# Container runs, stops, and Docker restarts it up to 2 times if it fails

Runs a container with a restart policy that restarts it up to 2 times on failure.

Process Table

Step	Container State	Restart Policy	Action	Restart Count	Result
1	Running	on-failure:2	No action	0	Container runs normally
2	Stopped with exit code 1	on-failure:2	Restart container	1	Container restarts
3	Stopped with exit code 1	on-failure:2	Restart container	2	Container restarts again
4	Stopped with exit code 1	on-failure:2	No restart (limit reached)	2	Container stays stopped

💡 Restart limit 2 reached, container stopped with failure exit code, no more restarts

Status Tracker

Variable	Start	After 1	After 2	After 3	Final
Restart Count	0	1	2	2	2
Container State	Running	Stopped (exit 1)	Stopped (exit 1)	Stopped (exit 1)	Stopped

Key Moments - 3 Insights

Why does the container stop restarting after the third failure?

Because the restart policy 'on-failure:2' limits restarts to 2 times, as shown in execution_table step 4 where Restart Count is 2 and no restart happens.

What happens if the container exits with code 0 under 'on-failure' policy?

The container will not restart because 'on-failure' only restarts on non-zero exit codes, so no restart action is taken.

How does 'always' restart policy differ from 'on-failure'?

'always' restarts the container regardless of exit code or failure count, unlike 'on-failure' which restarts only on failure and up to a limit.

Visual Quiz - 3 Questions

Look at the execution table, what is the Restart Count at step 3?

A 1

B 2

C 3

D 0

💡 Hint

Check the Restart Count column in execution_table row for step 3

At which step does the container stop restarting due to reaching the restart limit?

A Step 2

B Step 3

C Step 4

D Step 1

💡 Hint

Look at the Action and Result columns in execution_table for when no restart occurs

If the restart policy was changed to 'always', what would happen at step 4?

A Container would not restart

B Container would restart again

C Container would stop permanently

D Container would restart only once more

💡 Hint

Recall that 'always' restarts regardless of exit code or count

Concept Snapshot

Docker Restart Policies:
- no: Do not restart container
- always: Restart container no matter what
- on-failure[:max]: Restart only on failure, up to max times
- unless-stopped: Restart unless container stopped manually
Use with docker run --restart option
Controls container availability after stops

Full Transcript

This visual execution shows how Docker restart policies work. When a container stops, Docker checks the restart policy. For 'on-failure:2', Docker restarts the container up to 2 times if it exits with a failure code. The execution table tracks container state, restart count, and actions taken. Key moments clarify why restarts stop after the limit and how different policies behave. The quiz tests understanding of restart counts and policy effects. The snapshot summarizes the main restart policies and their behavior.

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