Homelab/docs/guides/health_checks.md

Health Check Examples for Docker Compose/Swarm

Example 1: Portainer with Health Check

version: '3.8'
services:
  portainer:
    image: portainer/portainer-ce:latest
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:9000/api/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3

Example 2: OpenWebUI with Health Check

version: '3.8'
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3

Example 3: Nextcloud with Health Check

version: '3.8'
services:
  nextcloud:
    image: nextcloud:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/status.php"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 120s
    deploy:
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 3

Implementation Notes

• interval: How often to check (30-60s for most services)
• timeout: Max time to wait for check to complete
• retries: Number of consecutive failures before marking unhealthy
• start_period: Grace period after container start before checking

Auto-Restart Configuration

All services should have restart policies configured:

• condition: on-failure or any
• delay: Time to wait before restarting
• max_attempts: Maximum restart attempts

Monitoring Health Status

Check container health with:

docker ps --filter "health=unhealthy"
docker inspect <container_id> | jq '.[0].State.Health'