Docker HEALTHCHECK

Also Known As

TL;DR

Explanation

HEALTHCHECK CMD defines a command run periodically inside the container. Docker tracks three states: starting (grace period), healthy, unhealthy. After a configurable number of consecutive failures (--retries), the container is marked unhealthy. Docker Swarm and Kubernetes use this signal to restart unhealthy containers and remove them from load balancer rotation. Without HEALTHCHECK, a container that is running but serving errors is invisible to the orchestrator.

Common Misconception

Why It Matters

Common Mistakes

• Setting --interval too short on slow-starting apps — container is marked unhealthy before it has finished initialising.
• Not having a dedicated /health endpoint — using the app's main route mixes health checks with request logs.
• Forgetting that curl must be installed in the container image for curl-based health checks.

Avoid When

• Do not use the main application route as the health check endpoint — it pollutes access logs and may have side effects.
• Do not set --start-period too short for slow-starting applications — they will be killed before they finish initialising.

When To Use

• Add HEALTHCHECK to every production Docker image — it is the orchestrator's only window into application health.
• Use a dedicated /health endpoint that checks all critical dependencies (DB, cache, queue).

Code Examples

# No HEALTHCHECK — orchestrator has no visibility into app health
FROM php:8.3-fpm
COPY . /var/www/html
# Container marked 'running' even if PHP-FPM is deadlocked

# Dockerfile
HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

# PHP health endpoint
<?php
header('Content-Type: application/json');
// Check DB connection
try {
    $pdo = getDatabaseConnection();
    $pdo->query('SELECT 1');
    echo json_encode(['status' => 'ok']);
} catch (\Throwable $e) {
    http_response_code(503);
    echo json_encode(['status' => 'error', 'detail' => 'db unavailable']);
}

References

• ↗ https://docs.docker.com/engine/reference/builder/#healthcheck

Tags

Related Terms