Skip to content

Traefik Healthcheck Fix

Problem

Traefik container shows as unhealthy even though: - HTTPS is working (certificates are valid) - Services are routing correctly - Traefik is functioning properly

Root Cause

The healthcheck command traefik healthcheck --ping requires the ping endpoint to be explicitly enabled in Traefik configuration. Without --ping=true, the healthcheck fails.

Fix

Added two configuration changes:

  1. Enable ping endpoint: 

    - --ping=true

  2. Add start period to healthcheck: 

    healthcheck:
  test: ["CMD", "traefik", "healthcheck", "--ping"]
  interval: 10s
  timeout: 5s
  retries: 3
  start_period: 10s  # Give Traefik time to start before checking

Complete Configuration

command:
  - --api.dashboard=true
  - --api.insecure=true
  - --ping=true  # Enable ping endpoint for healthcheck
  # ... other configuration ...

healthcheck:
  test: ["CMD", "traefik", "healthcheck", "--ping"]
  interval: 10s
  timeout: 5s
  retries: 3
  start_period: 10s  # Wait 10s before first healthcheck

Why This Works

  1. --ping=true: Enables the /ping endpoint that the healthcheck command uses
  2. start_period: 10s: Gives Traefik time to fully initialize before healthchecks begin, preventing false negatives during startup

Verification

After applying the fix:

# On VPS
cd /opt/po-platform

# Pull latest changes
git pull origin main

# Restart Traefik
docker compose -f infrastructure/compose/shared.yml --env-file infrastructure/compose/.env.shared restart traefik

# Wait a few seconds
sleep 10

# Check health status
docker ps | grep traefik
# Should show: Up (healthy) not (unhealthy)

# Test ping endpoint manually
docker exec po-traefik traefik healthcheck --ping
# Should exit with code 0 (success)

Expected Result

  • ✅ Traefik shows as healthy in docker ps
  • ✅ Healthcheck passes consistently
  • ✅ No impact on functionality (Traefik was already working)