Health checks

Přehled

Každá služba v Turtor stacku má vlastní health check, který Docker používá pro sledování stavu kontejnerů a řízení závislostí při startu.

API health check

NestJS API vystavuje health endpoint na /api/v1/health:

# Ověření z vnějšku
curl https://api.ckk.byadf.ai/api/v1/health

# Očekávaná odpověď
{ "status": "ok", "timestamp": "2026-02-28T10:30:00.000Z" }

Docker health check konfigurace

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:3001/api/v1/health || exit 1

Health check používá 127.0.0.1 místo localhost. Na Alpine Linuxu wget s localhost zkouší nejdříve IPv6 (::1), což v Docker kontejneru selhává.

Parametry

Parametr	Hodnota	Popis
`interval`	30s	Kontrola každých 30 sekund
`timeout`	10s	Timeout pro jeden pokus
`start-period`	5s	Čekací doba po startu kontejneru
`retries`	3	Počet neúspěšných pokusů před označením jako unhealthy

Web health check

Web kontejner (nginx) má inline health endpoint:

location /health {
    access_log off;
    return 200 "ok\n";
    add_header Content-Type text/plain;
}

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://127.0.0.1/ || exit 1

PostgreSQL health check

healthcheck:
  test: ['CMD-SHELL', 'pg_isready -U turtor -d turtor']
  interval: 10s
  timeout: 5s
  retries: 5

Příkaz pg_isready ověřuje, že PostgreSQL akceptuje spojení.

Redis health check

healthcheck:
  test: ['CMD', 'redis-cli', 'ping']
  interval: 10s
  timeout: 5s
  retries: 5

Redis odpovídá PONG na příkaz ping, pokud je funkční.

Závislosti při startu

Produkční Docker Compose využívá health checks pro řízení pořadí startu:

services:
  api:
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  web:
    depends_on:
      - api

  nginx:
    depends_on:
      - api
      - web

API kontejner se nespustí, dokud PostgreSQL a Redis nehlásí zdravý stav.

Kontrola stavu kontejnerů

# Zobrazení stavu všech kontejnerů
pnpm deploy:status

# Nebo přímo přes SSH
ssh deploy@<VPS_IP> "cd /opt/apps/turtor && docker compose ps"

# Výstup ukazuje sloupec STATUS s (healthy)/(unhealthy)
# NAME           STATUS                 PORTS
# turtor-api     Up 2 hours (healthy)   3001/tcp
# turtor-web     Up 2 hours (healthy)   80/tcp
# turtor-postgres Up 2 hours (healthy)  5432/tcp
# turtor-redis   Up 2 hours (healthy)   6379/tcp

Deploy health check

Deploy skript (scripts/deploy.sh) po nasazení automaticky čeká na API health:

# Čeká max 60 sekund (12 pokusů po 5 sekundách)
for i in $(seq 1 12); do
    curl -sf https://api.ckk.byadf.ai/api/v1/health && break
    sleep 5
done

Pokud health check po deployi selže, zkontrolujte logy: pnpm deploy:logs

Troubleshooting

Příznak	Pravděpodobná příčina	Řešení
API unhealthy	Chybějící migrace nebo špatné env	`pnpm deploy:logs`
PostgreSQL unhealthy	Nedostatek místa na disku	`docker system df`
Redis unhealthy	Plná paměť	Kontrola `maxmemory` nastavení
Web unhealthy	Chybějící build soubory	Rebuild: `pnpm deploy:build`

On this page