require-healthcheck

Docker HEALTHCHECK examples and why containers without one report as running even when the app inside is dead.

On this page

Without a HEALTHCHECK, Docker's definition of a healthy container is "the process has not exited". An app that is deadlocked, out of database connections, or returning 500s on every request still shows Up 3 hours. This rule suggests adding a HEALTHCHECK instruction so the runtime can actually see whether the app works.

What the rule catches

Dockerfile — 'running' is the only signal

FROM node:22-slim
WORKDIR /app
COPY . .
RUN npm ci
CMD ["node", "server.js"]

Scanning this file reports:

ℹ INFO [docker-doctor/require-healthcheck]
  No HEALTHCHECK instruction found. Containers running services should expose healthchecks to enable auto-healing.

Why it matters

Health status is what turns Docker from "process supervisor" into something operationally useful: docker ps shows (healthy)/(unhealthy), restart tooling and orchestrators can replace containers that stopped serving, and Compose's depends_on: condition: service_healthy — see use-depends-on-condition — can hold dependents until a service is genuinely ready rather than merely started. None of that works on a container that never defines what healthy means.

How to fix it

Use HEALTHCHECK (e.g., HEALTHCHECK --interval=30s --timeout=3s CMD curl -f http://localhost/ || exit 1) so Docker can monitor the container's live status.

Dockerfile — Docker probes the app itself

FROM node:22-slim
WORKDIR /app
COPY . .
RUN npm ci
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "server.js"]

The check must exist in the image — slim bases often lack curl, so either install it, use wget --spider -q, or ship a tiny built-in prober (for Node, a five-line script using fetch avoids any extra package). Keep the endpoint cheap and honest: it should verify the app can do real work, not just that the HTTP server accepts connections. --start-period gives slow-booting apps grace before failures count.

Rule details

Rule key — docker-doctor/require-healthcheck
Category — Best Practices
Default severity — info
Applies to — Dockerfiles

Explain this rule from the CLI:

npx @docker-doctor/cli@latest rules explain docker-doctor/require-healthcheck

Change its severity — or turn it off — in your config file:

// docker-doctor.config.ts
export default {
  rules: {
    "docker-doctor/require-healthcheck": "off",
  },
};

Severity affects the health score: error findings cost more points than warning, and info costs the least.