OwnStack

Healthchecks

Before rotating traffic to a freshly-deployed container, dokku runs healthchecks. The default is a port-listening probe on $PORT; you can override with a richer set of checks via app.json.

The default check

Dokku enters the new container and verifies the web process is listening on $PORT. If the listen-check passes within ~10 seconds, traffic rotates. If it doesn't, the deploy is rolled back and the previous container keeps serving.

Custom checks via app.json

{
  "checks": {
    "web": {
      "wait-to-retire": 30,
      "checks": [
        { "type": "uptime", "name": "default", "uptime": 5 },
        { "type": "http",   "name": "ready",   "path": "/healthz", "expected_status": 200 }
      ]
    }
  }
}

The uptime check waits for the container to be up for N seconds. The http check hits a path on $PORT and expects a status code. Add as many as you want; all must pass.

Common health endpoints

PathWhat it should return
/healthz200 OK if the app's basic dependencies (DB, Redis, anything required at startup) are reachable. No auth, no expensive work.
/readyz200 OK when the app is ready to serve traffic — distinct from "alive" if your app does long warm-up (preloading caches, JIT warmups).
/livez200 OK if the process is responsive at all. Cheaper than readyz; used in some environments to detect deadlocks.

Why a check fails

Symptom in deploy logLikely cause
port listening check: unable to enter the containerWeb process never bound to $PORT. Check your start command.
Failure in name='ready': expected status 200, got 502App started but the health endpoint returns an error. Often means a downstream dependency (DB) is unreachable.
container has restarted N timesThe process is crashing on startup. Check ownstack remote logs --tail 100 for the stack trace.
Healthcheck times outSlow startup. Increase wait-to-retire or add an explicit uptime check with a longer wait.