Restart unhealthy containers automatically with DeUnhealth
DeUnhealth watches your containers and restarts the ones that Docker marks as unhealthy. This page shows how to install it, check that it runs and, if you want, turn it on for another app.
What DeUnhealth does
Section titled “What DeUnhealth does”DeUnhealth has no web page and no login. It runs in the background.
It restarts a container only when both of these are true:
- The container has a Docker health check. Docker then reports it as
healthyorunhealthy. - The container has the label
deunhealth.restart.on.unhealthy=true.
A container without the label is left alone, even when it is unhealthy.
In Deployrr v6, only qBittorrent VPN has the label. It runs behind a VPN client. When the VPN reconnects, qBittorrent can lose its connection and turn unhealthy. DeUnhealth then restarts it. qBittorrent VPN won’t install unless DeUnhealth is running.
To see the idea in a manual setup, watch DeUnhealth video: health check and automatic restart at 2:51 (manual Docker Compose setup with labels).
Before you start
Section titled “Before you start”- You finished Prerequisites. See the Quick start.
- You have a Basic, Plus or Pro license. See Licenses. Socket Proxy needs one, and so does installing apps.
- Socket Proxy is installed and running. See Socket Proxy. In the Docker menu, its line ends with
RUNNING.
Install DeUnhealth
Section titled “Install DeUnhealth”- Go to Apps > Browse Apps.
- Select DeUnhealth (“Restart unhealthy containers”).
- Choose Install.
- At “Do you want to install this app?”, choose Yes.
DeUnhealth asks no other questions.
If you see Required app not running with [REQUIRED] socket-proxy must be installed and running first, install or start Socket Proxy first, then run the install again. See Requirements Not Met for other boxes.
Check it worked
Section titled “Check it worked”-
Go to Apps > Manage Apps. The DeUnhealth line shows [Running]. It has no exposure or login, because it isn’t behind Traefik.
-
In a terminal, list the containers:
Terminal window sudo docker psWith the Deployrr bash aliases:
dps(it lists all containers, including stopped ones). Thedeunhealthcontainer showsUp. -
Read its log:
Terminal window sudo docker logs deunhealthWith the aliases:
dlogs deunhealth. It keeps following the log. Press Ctrl+C to stop. You can also go to Apps > Manage Apps, select DeUnhealth, press Manage, then choose Logs. See Install and manage apps from the Apps menu.
Add DeUnhealth to another app
Section titled “Add DeUnhealth to another app”Do this only if the app has a health check. DeUnhealth can’t tell that a container is unhealthy without one. The App reference lists which apps have one by default.
1. Check that the app has a health check
Section titled “1. Check that the app has a health check”Replace NAME with the app’s container name. This is a value you fill in.
sudo docker inspect --format '{{json .State.Health}}' NAMEIf the output is null, the app has no health check, and the label would do nothing. Give it one first: see Add a health check to an app.
Otherwise the output lists the status and the last checks. You can also read the status in docker ps. The STATUS column shows (healthy), (unhealthy) or (health: starting) after the uptime.
2. Back up the compose file
Section titled “2. Back up the compose file”-
Go to your Docker folder:
Terminal window cdd -
Copy the app’s compose file. Replace
APPwith the app’s name. Bash fills in$HOSTNAMEfor you.Terminal window cp compose/$HOSTNAME/APP.yml compose/$HOSTNAME/APP.yml.bak
3. Add the label
Section titled “3. Add the label”-
Open the file. Replace
APPwith the app’s name.Terminal window nano compose/$HOSTNAME/APP.yml -
Find the service of the app. Add this label under it. If the service already has a
labels:list, add only the line that starts with the dash. Keep the same indentation as the lines around it.labels:- "deunhealth.restart.on.unhealthy=true" -
Save the file.
If the app is one of your own containers in custom.yml, add the same label to its service there.
4. Recreate the app
Section titled “4. Recreate the app”Restart does not read the compose file again. Use Recreate. See Restart, Recreate or Reinstall.
- Go to Tools > Stack Manager > Recreate.
- Type the number of the app and press Enter.
- Look for “APP recreated”.
With the aliases: dcrec APP. Replace APP with the app’s name.
5. Check the label
Section titled “5. Check the label”Replace NAME with the app’s container name:
sudo docker inspect --format '{{json .Config.Labels}}' NAMEThe output includes "deunhealth.restart.on.unhealthy":"true".
If Docker or Compose reports an error after your edit, copy the backup back over the file, then recreate the app. See Docker environment setup fails with: docker-compose file is malformed for the main file.
Add a health check to an app
Section titled “Add a health check to an app”Most apps have no health check (see the App reference). You can add one to the app’s compose file. Docker then runs a test command inside the container at a set interval and marks it unhealthy after a number of failures in a row.
1. Find a test that works inside the container
Section titled “1. Find a test that works inside the container”The test runs inside the container, so it can only use tools the image has. Replace NAME with the container name and PORT with the app’s internal port. Both are in the App reference.
-
Check whether the image has
curlorwget:Terminal window sudo docker exec NAME sh -c 'command -v curl wget'It prints the path of each tool it finds. If it prints nothing, the image has neither. If it says
shwas not found, the image has no shell either; use a test the app’s own documentation gives, or leave the app without a health check. -
Run the test by hand. With
curl:Terminal window sudo docker exec NAME curl -fsS -o /dev/null http://localhost:PORT/ && echo OKWith
wget:Terminal window sudo docker exec NAME wget -q --spider http://localhost:PORT/ && echo OKOKmeans the test passes. If you see noOK:- The page may need a login (an error such as 401) or the port is wrong. Try another address the app answers without a login, for example a health or ping address from the app’s own documentation.
- Some images resolve
localhostto an IPv6 address the app doesn’t listen on. Try127.0.0.1instead oflocalhost. wget --spiderasks only for the page headers, and a few apps refuse that. If the page opens in your browser, try thecurltest.
2. Add the health check
Section titled “2. Add the health check”-
Back up the compose file and open it, as in Back up the compose file and Add the label above. Apps with a database or cache have a separate file for each helper container, for example
APP-postgresql.yml. Edit the file of the container you want to check. -
Under the app’s service, add a
healthcheck:block at the same indent asimage:. Use the command that printedOK. Withcurl:healthcheck:test: ["CMD-SHELL", "curl -fsS -o /dev/null http://localhost:PORT/ || exit 1"]interval: 30stimeout: 10sretries: 3start_period: 1mWith
wget, thetest:line is:test: ["CMD-SHELL", "wget -q --spider http://localhost:PORT/ || exit 1"] -
Save the file.
To see a health check block added to a compose file, watch DeUnhealth video: add a health check at 3:29 (manual Docker Compose setup; the video’s file paths differ from Deployrr’s).
What the lines mean:
| Line | What it does |
|---|---|
test |
The command Docker runs. Exit code 0 is healthy, anything else is a failure. |
interval |
How often the test runs. |
timeout |
How long one test may take before it counts as a failure. |
retries |
How many failures in a row turn the app unhealthy. |
start_period |
Time to start up. Failures in this time don’t count. Raise it for apps that start slowly. |
For one of your own containers in custom.yml, add the same block to its service there.
3. Recreate and check
Section titled “3. Recreate and check”-
Recreate the app, as in Recreate the app above.
-
Wait for
intervalplusstart_period, then read the status:Terminal window sudo docker inspect --format '{{json .State.Health}}' NAMEThe output shows
"Status":"healthy"and the last checks.startingmeans Docker is still in the start period. Forunhealthy, read the output of the last checks. See Read the health check.
If Docker or Compose reports an error after your edit, copy the backup back over the file, then recreate the app.
Once the app shows healthy, you can add the DeUnhealth label to it.
If it doesn’t work
Section titled “If it doesn’t work”- DeUnhealth can’t see your containers. Socket Proxy may be stopped. Check that its line in the Docker menu ends with
RUNNING. If it saysSTOPPED, see When Socket Proxy is not running. After it runs again, recreate DeUnhealth in Tools > Stack Manager > Recreate. - An unhealthy app is not restarted. Check that it has a health check and the label. See the steps above.
- An app restarts again and again. DeUnhealth only restarts it. It does not fix the reason it is unhealthy. Read the app’s log and fix the cause. See A container keeps restarting, is unhealthy or has exited.

