Hardware FixRecommendedDevice not working? Your driver may be the problemCheck updates for common hardware issues.Fix DriversHalloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix Now×
FREEDOM251

Freedom251 › Blog › Container Health Checks

Docker Health Checks: How to Restart Unhealthy Homelab Services

By Freedom251 Team · · 4 min read

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Docker health checks can detect when a service stops responding as expected, but they do not automatically restart a container that is still running. For a homelab to recover from that failure, pair a useful HEALTHCHECK with a health-aware controller or host automation; use Docker restart policies separately for containers whose main process exits.

What a Docker health check does—and what it does not do

A Docker HEALTHCHECK runs a command inside a container and records the result as starting, healthy, or unhealthy. Docker marks the container unhealthy after the configured number of consecutive failed checks. The check should test a meaningful readiness or service outcome, not merely whether a process exists. Docker’s Dockerfile reference describes the instruction as a way to test whether a container is still working.

As an Amazon Associate I earn from qualifying purchases.

Health status is not a restart command. A container can remain running while unhealthy, and a standard Docker restart policy does not promise to restart it for that reason. Restart policies such as on-failure and unless-stopped govern Docker’s response when a container exits. Keep those mechanisms distinct when designing recovery. Docker’s restart-policy documentation explains the available policies and their behavior.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Choose a recovery mechanism for the failure you need to handle

Mechanism What it detects or acts on Can act on a running unhealthy container? Where recovery is controlled Key trade-off
Docker restart policy Container exit, subject to the selected policy No, not on health status alone Docker Engine Simple for process exits; it does not interpret health checks.
Health-aware controller Health status reported by Docker Yes, if configured to restart unhealthy containers An additional service or controller with Docker access Adds a component and permissions; verify safeguards, logs, and behavior before relying on it.
Host automation or process manager Whatever health signal or condition the automation is configured to monitor Potentially, if it observes health status and issues a restart On the Docker host Flexible, but can conflict with Docker restart policies; Docker cautions against combining them without care.

For an unhealthy container whose process remains alive, something outside that process must notice the health state and issue a restart—or the application must deliberately exit when it cannot recover. Docker’s health-check and restart-policy documentation describes the underlying primitives, not the reliability or security of any particular third-party controller. Grant only the Docker access the chosen mechanism needs, and determine how it handles repeated failures, restart limits, logging, and dependent services.

#1 Best Overall
Glorlin Mini PC, AMD Ryzen 5 3501U CPU (Beats N95, Up to 3.7 GHz, 4C/8T) Small Desktop Computer 16GB DDR4 RAM 512GB NVMe SSD WiFi 6 Bluetooth 5.3 Dual HDMI DP Support Three 4K Display for Home Office
  • 【Great power in a small computer】Get fast performance from the Ryzen 5 3501U ​processor (2.1GHz-3.7GHz, 4 Cores 8 Threads) inside this mini pc, TDP 15W up to 25W. It's perfect for all your home office​ and business use, like daily computing, web browsing, and smooth media streaming. This small desktop computer​ handles everyday tasks easily and quietly.
  • 【Work on many things at once with lots of storage】This mini PC comes with 16GB of fast DDR4 RAM (expandable up to 32GB), allowing you to smoothly run multiple programs, dozens of browser tabs, and large files all at once. It also features a spacious 512GB SSD that provides ample storage and delivers dramatically faster boot-ups, app launches, and file transfers compared to a traditional hard drive.
  • 【See everything clearly on three 4K screens】Connect three monitors for more space to work or play. 1*Type-C 3.2 DP+DATA+PD and 2*HDMI ports​ on this mini pc​ support super sharp 4K Ultra HD​ video. It's great for doubling your work area for business​ or watching movies in high definition.
  • 【Fast modern connections in a tiny box】Enjoy a better and more stable internet connection with the latest WiFi 6. Use Bluetooth 5.3​ to connect wireless headphones, keyboards, and mice without wires. This small pc​ is very compact​ to save desk space and has extra USB ports (2*USB3.2, 2*USB 2.0, 1*Type-C 3.2 DP+DATA+PD, 1*Type-C 2.0, 2*HDMI 4K60Hz) for your printer, webcam, or other computer accessories.
  • 【Ready to use, saves space, and runs quiet】This mini desktop computer comes with the OS 11 Pro operating system pre-installed, so you can set it up and start using it immediately. Its compact, small form factor not only saves valuable desk space but also operates very quietly, ensuring it won't distract you whether you're working, studying, or streaming media.

Write a probe that tests useful readiness

Use a lightweight, side-effect-free command that exists in the image and checks the outcome users or dependent services need. Docker’s documentation shows an HTTP check using curl -f against an application page, but that example only works if the image contains curl and the endpoint is a meaningful signal for your service. A process check alone can miss a wedged API, failed database connection, or unavailable application route; an overly broad external check can also mark a healthy container unhealthy because of a dependency beyond its intended scope.

Decide what the check is meant to establish: that the service has initialized, that a local endpoint responds, or that a specific dependency is reachable. A passing probe establishes only that its tested condition passed at that moment; it does not prove every external path or dependent system is working.

Tune timing for the application, not by copying defaults

Docker documents defaults of 30 seconds for interval, 30 seconds for timeout, zero seconds for start_period, five seconds for start_interval, and three consecutive failures for retries. These are documented defaults, not universal homelab recommendations. start_interval requires Docker Engine 25.0 or later, so check the installed Engine version before using it.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
Sale
KAMRUI Pinova P2 Mini PC 16GB RAM 512GB SSD, AMD Ryzen 4300U(Beats 5400U/3500U/N95,Up to 3.7GHz,4C/8T) Mini Computers,Triple 4K Display/HDMI+DP+Type-C/WiFi/BT for Home/Business Mini Desktop Computers
  • 【AMD Ryzen 4300U True 4-Core CPU: Outperforms N95 & i3-10110U】KAMRUI P2 Mini PC is equipped with true 4-core AMD Ryzen 4300U processor built on advanced 7nm Zen2 architecture,This means you get consistent, unthrottled performance for hours on end, whether you’re running multiple browser tabs, streaming 4K content, or managing virtual machines. Compare that to Intel N95 (4 efficiency cores that throttle under load) or Intel i3-10110U (only 2 cores total), and the difference is night and day: The KAMRUI P2 AMD Ryzen 4300U (28W) is 40% faster than the Intel i3-10110U and 25% faster than the Intel N95 in multi-core tasks, ensuring smooth, lag-free performance even during heavy workloads.
  • 【Integrated AMD Radeon Graphics: 2.5X Stronger for Tri 4K】The KAMRUI P2 AMD 4300U Mini PC have unlocked the full potential of the built-in AMD Radeon Vega 5 graphics with 28W power delivery, making it 2.5 times stronger than the Intel UHD graphics found in the N95 and i3-10110U. This means you can enjoy Tri 4K@60Hz displays without a single stutter, perfect for productivity setups, home theaters, or even light photo/video editing and casual gaming. While the Intel N95/i3-10110U struggle to run a single 4K display without lag, The KAMRUI AMD 4300U Mini PC handles Tri 4K effortlessly, turning your workspace into a high-efficiency hub or your living room into a premium entertainment center.
  • 【Large Storage Capacity, Easy Expansion】KAMRUI Pinova P2 mini computers is equipped with 16GB LPDDR4 for faster multitasking and smooth application switching. 512GB M.2 SSD ensures fast startup, fast file transfers and plenty of storage space,eliminating slow loading times and ensuring fast responsiveness. the two storage slots (1x M.2 2280 SATA/NVMe PCIe3.0 slot, 1x M.2 2280 SATA slot) can be combined to provide up to 4TB of total storage(Not included). This gives you enough space for all your projects, media and data.
  • 【4K Triple Display】KAMRUI Pinova P2 4300U mini desktop computers is equipped with HDMI2.0 ×1 +DP1.4 ×1+USB3.2 Gen2 Type-C ×1 interfaces for faster transmission, Triple 4K@60Hz Display, KAMRUI P2 mini computer is ideal for visual home entertainment, home office, conference rooms, etc. USB3.2 Gen2 Type-A port ×2 with a transfer speed of up to 10 Gbps (21 times faster than USB 2.0) for efficient data transfer. Ideal for seamless multitasking between spreadsheets, browsers and presentations, or for an immersive entertainment experience.
  • 【USB3.2 Gen2 Type-C 10Gbps, Versatile connectivity】KAMRUI P2 mini desktop pc fast and versatile connectivity! The USB3.2 Gen2 Type-C port offers a data transfer rate of 10Gbps and simultaneously supports DisplayPort 1.4 video output. The P2 AMD Ryzen 4300U Mini PC is complemented by Gigabit LAN, WiFi and Bluetooth, so nothing stands in the way of a productive working environment.
  • interval sets how often checks run during normal operation.
  • timeout limits how long one check may take before it fails.
  • start_period gives a slow-starting application time to initialize without treating early failures as ordinary runtime failures.
  • retries sets how many consecutive failures trigger the unhealthy state.
  • start_interval, where supported, sets the check interval during startup.

Shorter intervals and fewer retries can detect a real outage sooner, but may react to transient slowness. Longer settings reduce sensitivity to brief interruptions but delay detection. Base the values on observed startup time and the failure tolerance of the service; do not treat Docker’s defaults or an example configuration as a prescription.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Gate dependent startup with Compose readiness

Compose can wait for a dependency to become healthy before starting a dependent service by using depends_on with condition: service_healthy. This is a startup gate, not a continuing runtime recovery mechanism. Docker notes that Compose otherwise waits for a container to be running, not necessarily ready. The Compose startup-order guide demonstrates this pattern.

Compose’s depends_on option restart: true applies to explicit Compose-controlled dependency updates or restarts; it does not continuously monitor runtime health and restart dependents whenever a dependency becomes unhealthy. Check the Compose version and documentation for the fields you use.

Rank #3
Sale
BOSGAME E5 Mini PC Ryzen 3 5300U, 16GB DDR4 512GB NVMe SSD
  • 【Responsive Quad-Core Productivity】 Powered by the AMD Ryzen 3 5300U processor (4 Cores/8 Threads, up to 3.8GHz), the BOSGAME E5 delivers stable and efficient processing for your daily workflows. It is perfectly optimized to run standard business software, manage large spreadsheets, and handle online classes smoothly. Please note: This budget-friendly PC excels at daily office productivity and network server applications, but is not designed for demanding professional 3D rendering or intensive 3A gaming.
  • 【Expandable Memory & Dual NVMe Storage】 Equipped with 16GB DDR4 memory and a fast 512GB M.2 2280 NVMe PCIe 3.0 SSD out of the box, ensuring quick boot times and fluid application loading. Designed for future flexibility, the system features dual SODIMM slots supporting memory upgrades up to 64GB, along with an additional empty M.2 2280 NVMe PCIe 3.0 slot for seamless dual-drive expansion without removing your original system drive.
  • 【Dual 2.5G LAN & Pro-Level Networking】 Featuring two ultra-fast 2.5GbE RJ45 LAN ports (Realtek RTL8125) and built-in Wi-Fi 5, this micro computer is a powerhouse for advanced network environments. It serves as the perfect hardware foundation for IT enthusiasts and professionals looking to build a secure home server, deploy a pfSense/OPNsense firewall appliance, configure a high-speed NAS, or run stable virtual machines.
  • 【True Triple 4K Display Productivity】 Maximize your screen real estate and eliminate constant window switching. Integrated AMD Radeon Graphics easily drive up to three independent 4K@60Hz monitors via 1x HDMI 2.0, 1x DisplayPort, and 1x Full-Function Type-C port. This versatile multi-screen setup is the ultimate solution for side-by-side document editing, financial stock tracking, or home entertainment.
  • 【Full-Function Type-C & Quiet Efficiency】 Streamline your workspace with the front-facing full-function USB Type-C port, supporting high-speed data transfer, 4K display output, and Power Delivery (PD 3.0). Engineered with an optimized cooling fan and copper heat pipes, the E5 operates at whisper-quiet noise levels. Its ultra-compact footprint easily replaces bulky traditional computer towers, pre-installed with a clean system.

Docker’s PostgreSQL startup-order example uses a health test with a 10-second interval, 10-second timeout, five retries, and a 30-second start period. Those are example values for that demonstration, not recommended settings for every database or homelab service.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Verify detection and recovery separately

  1. Inspect the container’s state with docker inspect and review its recorded health-check output. Confirm the probe is running and that its result reflects the condition you intended to test.
  2. Watch Docker’s health_status events to see when a container changes health state. Docker’s events reference documents the event stream.
  3. Test a controlled probe failure and confirm that Docker records the expected unhealthy state after the configured failures.
  4. Test the recovery actor separately: confirm it detects the unhealthy state, takes the intended action, logs what happened, and does not create an uncontrolled restart loop.
  5. Check the dependent-service behavior you actually require. A startup gate does not, by itself, demonstrate recovery from a dependency failure after startup.

Keep Docker’s restart policy for appropriate process-exit cases, and avoid layering host process managers over it without understanding which mechanism wins and how they interact. A health check detects a condition; the restart policy, controller, or application determines what happens next.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Container Health ChecksDockerDocker ComposeHomelabself-hosting

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
Windows Errors? Fix Them Before They SpreadFree repair scan
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.