Bash

A Dokku CHECKS file for zero-downtime deploys

Dokku swaps to a new container before it is actually ready, so requests hit a half-booted app. A CHECKS file makes Dokku wait for a real healthcheck to pass.

26 Jun 2026

Drop a file named CHECKS at the root of your build context (next to the Dockerfile). Dokku reads it during deploy and only routes traffic once the path returns 200.

# CHECKS
# wait this many seconds before the first attempt
WAIT=5
# seconds between attempts
TIMEOUT=10
# number of attempts before the deploy is failed
ATTEMPTS=6
 
# path  expected-substring-in-the-body
/healthz  ok

Pair it with an app endpoint that checks its own dependencies, not just that the process is up:

// in your Express app
app.get("/healthz", async (_req, res) => {
  try {
    await db.query("select 1");
    res.status(200).send("ok");
  } catch {
    res.status(503).send("db down");
  }
});

Gotchas

The check runs against the new container on its internal port, before the proxy switches over. If /healthz touches the database and the database is unreachable, the deploy fails and Dokku keeps the old container serving traffic, which is what you want. Keep the check cheap: it runs up to ATTEMPTS times on every single deploy.

devops dokku