dokku-zero-downtime-checks

Dokku zero-downtime deploy checks

Version: Dokku 0.37.x. Safety: checks:enable/disable/skip and checks:set change deploy behavior — confirm before running. checks:disable causes downtime on the next deploy. checks:report and checks:run are safe.

How zero-downtime works

On deploy Dokku starts the new container, waits, runs the configured checks against it, and only then routes traffic and retires the old container. If checks fail, the new container is not promoted.

dokku checks:report <app>             # read-only: current check state per process
dokku checks:run <app>                # run checks now against the running app
dokku checks:enable <app>             # enable for all process types
dokku checks:enable <app> web,worker  # or a comma-separated subset
dokku checks:skip <app>               # deploy without waiting for checks (no downtime, no gating)
dokku checks:disable <app>            # ** WARNING: reintroduces downtime on deploy **

Define healthchecks in app.json (repo root)

For the Dockerfile builder, commit app.json to the repository root:

{
  "healthchecks": {
    "web": [
      {
        "type": "startup",
        "name": "web check",
        "path": "/health/ready",
        "port": 8080,
        "attempts": 3,
        "timeout": 5,
        "wait": 5,
        "initialDelay": 0
      }
    ]
  }
}

• type: startup, readiness, or liveness.
• path + port: HTTP check target inside the container.
• attempts, timeout, wait, initialDelay: retry/timing controls.
• A command/content pair can be used instead of an HTTP path for command-based checks.

Tune timing

Set per-app or globally:

dokku checks:set <app> wait-to-retire 60     # grace seconds before killing old containers

Note: on 0.37.x the checks:set help text mislabels the target as a "logs property"; it is a known cosmetic help-string bug — the command does set check properties.

Environment-variable controls (defaults shown):

Var	Default	Meaning
DOKKU_DEFAULT_CHECKS_WAIT	10	initial wait before checking container status
DOKKU_CHECKS_WAIT	5	seconds to wait before running checks
DOKKU_CHECKS_TIMEOUT	30	per-check response timeout
DOKKU_CHECKS_ATTEMPTS	5	retries before marking failed
wait-to-retire	60	grace period before retiring old containers

Verify (read-only)

dokku checks:report <app>
dokku checks:run <app>      # exits non-zero if a check fails