Health checks and automatic restarts

Deplo checks that an app answers, restarts it when it stops, and tells you when a restart did not help.

A running container is not always a working app. It can be up and answer nobody: a stuck process, a deadlock. Deplo asks every app with a domain whether it still answers, and restarts it when it does not.

  • On by default. An app with a domain is checked even if nobody set a health check.
  • The server does the asking, not the panel. It keeps checking and restarting while Deplo itself is down.
  • You are told: every restart is in Activity, and an alert goes out at the first one.

What gets checked

The app hasWhat the server asksRestarted after
A domain, no health checkGET / on the app's port every 30 seconds, 10 seconds to answer3 failures in a row
An HTTP request health checkYour path and port, on your timingsRetries failures in a row
A Command health checkDocker runs your command inside the containerDocker calls it unhealthy
No domain, no health checkNothingNever. A crash still restarts it
  • For the default check, any HTTP answer counts as answering, a 404 or a 500 included. No answer in time, or a refused connection, is a failure. An app that answers 404 on / is never restarted for it.
  • For your own HTTP request check, a status of 400 or above is a failure. The Path field says: "The path Deplo asks for. Anything under 400 is healthy."
  • Nothing counts while the app boots: 60 seconds after a start for the default check, your Start period for your own.
  • Nothing counts during a deploy, or while a zero-downtime deploy has its copy of the new version running.
  • Each replica is checked on its own. One stuck replica is restarted while the others keep serving.
  • A Compose app gets the default check on the service that has the domain. When that service declares a healthcheck: in the compose file you edit in Deplo, the app is restarted on that check's verdict instead. A compose file that lives in the repository still gets GET /.
  • A pull request preview is checked and restarted the same way, on its own.

When an app stops answering

  1. The server restarts it. Activity gets an entry by Deplo: Restarted web: it stopped answering for 90 s.
  2. The alert "App stopped answering" goes out at the first restart, titled web stopped answering: "It was up but did not answer for 90 s, so Deplo restarted it." When it answers again you get web is running again: "It answers again."
  3. After 5 restarts in 30 minutes, restarting pauses. The app is not stopped: a half-working app still serves the visitors it can. Its status reads Not answering · restarts paused, Activity says Paused restarts for web: it restarted 5 times in 30 minutes and still does not answer, and the alert App still not answering goes out. The logs have why.
  4. Restarting resumes on its own after your next deploy, a manual restart, or 30 quiet minutes (no failed check). Activity says which: Resumed restarts for web after a deploy.

Both alerts are on by default. See Notifications and alerts.

What you are told, and how often

  • Every restart is an Activity entry. The alert is quieter: after the first one, no second "App stopped answering" for 30 minutes, however many restarts follow.
  • "App still not answering" goes out once per pause, titled web is still not answering. A new pause after restarting resumed alerts again.
  • web is running again is sent once, when the app answers after either alert went out. It is never sent for a restart nobody was alerted about.
  • A restart or an update of Deplo loses none of this: nothing is repeated, and a recovery is still announced.
Activity saysFor
Restarted web: it stopped answering for 90 sAn app with one replica
Restarted web replica web-2: it stopped answering for 90 sOne of several replicas
Restarted web replica web-1 on server-b: it stopped answering for 90 sA replica of an app spread over the servers of a cluster
Restarted the preview for pull request #7 of web: it stopped answering for 90 sA pull request preview
Paused restarts for the preview for pull request #7 of web: it restarted 5 times in 30 minutes and still does not answerA pull request preview. A preview's restarts never alert

This is not restart loop protection. That one stops an app that keeps crashing. This one restarts an app that is up and silent.

Turn automatic restart off

Open the app, then Settings -> Advanced -> Restart when it stops answering. It needs Configure apps and applies from the next deploy.

Turn it off for an app that is meant to be slow to answer.

The row saysWhat it means
"Restarts the app after 3 failed checks in a row. With no health check of its own, any answer on / counts."It is on, with the default check
"Restarts the app when it keeps failing its own health check."It is on, for an app with its own health check
"Not answering · restarts paused. It resumes after your next deploy, a manual restart, or 30 quiet minutes."Restarting is paused for this app
"Automatic restart needs a newer server agent. Deplo updates it on its own."The server cannot do it yet. Nothing to do: wait for the update

Off, an HTTP request health check is no longer asked either, so the app shows no health result.

Set your own health check

Your own check replaces the default one, so "answering" means what you say it means. Single-image apps only.

Open the app's Advanced settings

Open the app, then Settings -> Advanced, and turn on Health check.

Pick the kind and fill it in

  • HTTP request: the Path (/healthz, or /), and a Port only if the check answers on a port other than the app's own. It asks from the server, so it works on any image.
  • Command: anything that exits 0 when things are fine, such as pg_isready -U app or test -f /tmp/ready. Pipes and fallbacks work.

Set the timings, then Save

All optional:

FieldWhat it meansDefault
IntervalSeconds between checks30
TimeoutSeconds one check may take. Must be shorter than the interval5
RetriesFailures in a row before the app is unhealthy, and restarted3
Start periodSeconds of grace while the app boots, when a failure does not count10

The check reaches the server with the next deploy.

Reading the result

The answer shows on the app's status badge, on the Overview, and in the container breakdown on Monitoring. It is the server's own verdict, the same one the restart acts on.

  • Healthy: the last check was answered.
  • Unhealthy: enough failures in a row to restart it. Running, but not working. An app the server restarted for not answering reads unhealthy, on the Overview too, until it answers again.
  • Starting: inside the start period, so a failure means the app is still booting.
  • No result: nothing checks this app, or the server has not checked it yet. It never reads as healthy by default.

Error is not unhealthy. Error means the last deploy failed. An app can be Error and healthy at once, because the previous version is still serving.

Good to know

  • An unhealthy app keeps its traffic. A check never changes routing. With zero-downtime deploys on, the proxy sends traffic only to a container whose check passes.
  • A stopped app has no result. There is nothing to ask.
  • A worker with no domain opens no port to ask, so only a crash restarts it. Give it a Command health check to have it restarted when it hangs.
  • A database's health check is the engine's own, written by Deplo. It is not editable, and a database is not restarted by this rule.
  • Over the API: setAppRestartWhenUnresponsive, or the MCP tool set_app_restart_when_unresponsive.

Next steps

Did this page help you?

On this page