Docker and Compose
Choosing a Docker Compose restart policy
Compare no, on-failure, always and unless-stopped against application exit behaviour and operator intent.
By AppLaunch Editorial · Reviewed 2026-08-25
Direct answer
Use restart behaviour that matches the service: long-running production services commonly need automatic recovery, while one-shot migrations and jobs should surface failure rather than loop forever. A restart policy is not a fix for deterministic crashes.
What this means in plain English
A restart policy tells Docker what to do when a container stops. Long-running web services often should return after an unexpected crash or host restart. One-time jobs, such as a database migration, should usually finish once and show a clear failure instead of looping forever.
Automatic restart is useful recovery, not a cure. If the same programming error makes a service crash every five seconds, restarting it hides the symptom behind a noisy loop and can fill logs. Alert on repeated restarts and fix the cause.
Which failures should restart automatically?
| Long-running service | Restart after unexpected exit |
|---|---|
| One-shot job | Run to completion and expose status |
| Crash loop | Alert and preserve logs instead of hiding it |
A simple example
A web server uses unless-stopped so it returns after a machine reboot but stays off when an operator deliberately stops it. A migration container uses no endless restart policy; if its SQL fails, the release stops and shows the error for investigation.
What to do, step by step
1. Classify each service as daemon or job.
Start here before buying anything or changing several settings at once. It gives you a clear starting point based on long-running service: restart after unexpected exit. Write the result down so you can compare it later.
2. Test clean shutdown and non-zero exit.
Use the same files, versions and settings that the real project will use. A quick test with an empty or different setup can look successful while completely missing the problem you are trying to solve.
3. Set a finite backoff in the application where relevant.
Try the busiest realistic situation, not the easiest one. Include the people, data, traffic or background work you genuinely expect, then watch for slowdowns and errors rather than relying on a single headline number.
4. Alert on repeated restarts.
Finish by checking the result against crash loop: alert and preserve logs instead of hiding it. Keep the old setting or release available until you know the change works and can be reversed safely.
One more useful tip
Test both a clean shutdown and a forced failure. The application should finish active work where possible, exit with a useful code and return only when the chosen policy says it should.
Common mistakes and how to avoid them
Applying always to migrations.
This gives a misleading or unsafe result because it leaves out long-running service. A better approach is to classify each service as daemon or job, then check the result before making the change permanent.
Ignoring crash-loop root causes.
This gives a misleading or unsafe result because it leaves out one-shot job. A better approach is to test clean shutdown and non-zero exit, then check the result before making the change permanent.
Using restarts as a health check.
This gives a misleading or unsafe result because it leaves out crash loop. A better approach is to set a finite backoff in the application where relevant, then check the result before making the change permanent.
Words explained
- Compose
- Docker Compose is a file-based way to describe several containers, their settings, storage and networks as one application.
- health check
- A small test that tells Docker whether the application inside a container is actually working.
Quick checklist
- Classify each service as daemon or job.
- Test clean shutdown and non-zero exit.
- Set a finite backoff in the application where relevant.
- Alert on repeated restarts.
Common questions
What is the simple answer?
Use restart behaviour that matches the service: long-running production services commonly need automatic recovery, while one-shot migrations and jobs should surface failure rather than loop forever. A restart policy is not a fix for deterministic crashes.
What should I check first?
Start with long-running service: restart after unexpected exit. That is usually more useful than choosing from a marketing label or copying somebody else’s setting.
How can I make the change safely?
Classify each service as daemon or job. Then change one thing at a time, keep a backup or old version, and use the same real-world test after each change.
What is the easiest mistake to avoid?
Applying always to migrations. Avoiding that one mistake makes the rest of the comparison much more trustworthy.