Health checks and restart policies

In plain English

A HEALTHCHECK instruction runs a command inside the container to report whether it is healthy, so Docker and Compose know if the service is actually ready rather than just started. In Compose, depends_on with condition: service_healthy makes one service wait for another to pass its health check before starting. A restart policy such as unless-stopped tells Docker to restart a container automatically when it exits, while no and on-failure give you finer control. docker ps shows the health status of each container in its STATUS column. Logs from docker logs and failed health checks are usually the first place a crash explains itself.

Step by step

1. 1Add HEALTHCHECK to your Dockerfile with a command that proves the app responds.
2. 2Rebuild and run it, then watch docker ps until STATUS shows healthy.
3. 3Run a container with --restart unless-stopped so it recovers after a crash.
4. 4In Compose, set depends_on with condition: service_healthy on dependents.
5. 5Read docker logs to see health check failures and crash reasons.

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --retries=3 CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "server.js"]

Common mistakes

• Skipping HEALTHCHECK means depends_on can only guess by start order, not actual readiness.
• Using restart always during development keeps restarting a broken container and hides the error.
• Writing a health check that does nothing but return success gives false confidence in a dead service.
• Reading STATUS too soon shows starting, not healthy, because checks run on an interval.