# Reference: Docker Compose Healthcheck Syntax

Riferimento completo per la configurazione degli healthchecks.

## Sezione healthcheck

### Struttura Completa

```yaml
services:
  service_name:
    healthcheck:
      test: ["CMD", "command", "arg1", "arg2"]
      interval: 30s
      timeout: 30s
      retries: 3
      start_period: 0s
```

## Parametri

### test (Required)

Comando da eseguire per verificare la salute.

**Formato CMD:**
```yaml
test: ["CMD", "wget", "--spider", "-q", "http://localhost/health"]
```

**Formato CMD-SHELL:**
```yaml
test: ["CMD-SHELL", "curl -f http://localhost/ || exit 1"]
```

**Formato NONE:**
```yaml
test: ["NONE"]
```
Disabilita healthcheck ereditato dall'immagine.

### interval

Frequenza di esecuzione del test.

```yaml
interval: 5s       # Ogni 5 secondi
interval: 10s      # Ogni 10 secondi
interval: 30s      # Ogni 30 secondi (default)
interval: 1m       # Ogni minuto
```

**Validità:**
- Minimo: `1s` (1 secondo)
- Massimo: Nessuno
- Default: `30s`

### timeout

Tempo massimo per completare il test.

```yaml
timeout: 2s        # 2 secondi
timeout: 5s        # 5 secondi (default)
timeout: 30s       # 30 secondi
```

**Nota:** Se il test supera il timeout, conta come fallimento.

### retries

Numero di fallimenti consecutivi prima di marcare unhealthy.

```yaml
retries: 1         # 1 fallimento = unhealthy
retries: 3         # 3 fallimenti = unhealthy (default)
retries: 5         # 5 fallimenti = unhealthy
```

**Calcolo del tempo unhealthy:**
```
tempo_totale = (interval + timeout) × retries
```

Esempio con `interval: 10s, timeout: 5s, retries: 3`:
- Check 1: 0s - 5s
- Check 2: 10s - 15s
- Check 3: 20s - 25s
- Unhealthy dopo: 25s

### start_period

Grace period prima di contare retries verso unhealthy.

```yaml
start_period: 0s   # Nessun grace period (default)
start_period: 5s   # 5 secondi di grace
start_period: 10s  # 10 secondi di grace
start_period: 30s  # 30 secondi di grace
```

**Comportamento:**
- Durante `start_period`: Fallimenti non contano
- Dopo `start_period`: `retries` inizi a contare

## Esempi per Tipo di Servizio

### HTTP Service (Nginx)

```yaml
healthcheck:
  test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
  interval: 10s
  timeout: 5s
  retries: 3
  start_period: 5s
```

### Database (PostgreSQL)

```yaml
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres || exit 1"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 10s
```

### Cache (Redis)

```yaml
healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 10s
  timeout: 3s
  retries: 3
```

### TCP Connection

```yaml
healthcheck:
  test: ["CMD-SHELL", "nc -z localhost 8080 || exit 1"]
  interval: 15s
  timeout: 2s
  retries: 3
```

### File Check

```yaml
healthcheck:
  test: ["CMD-SHELL", "test -f /tmp/ready || exit 1"]
  interval: 5s
  timeout: 1s
  retries: 5
```

## Stati di Salute

### Ciclo di Vita

```
created → starting → healthy
                ↓
              unhealthy
```

**Transizioni:**

| Da | A | Condizione |
|----|---|------------|
| created | starting | Container avviato con healthcheck |
| starting | healthy | `retries` consecutivi passano |
| starting | unhealthy | `retries` consecutivi falliscono (dopo start_period) |
| healthy | unhealthy | `retries` consecutivi falliscono |
| unhealthy | healthy | 1 check passa |

### Ispezionare Stato

```bash
# Stato corrente
docker inspect lab03-web --format '{{.State.Health.Status}}'
# Output: healthy / unhealthy / starting

# Exit code dell'ultimo check
docker inspect lab03-web --format '{{.State.Health.ExitCode}}'
# Output: 0 (success) o !0 (failure)

### Vedi Anche
- Tutorial: Implementare Healthchecks
- How-to: Custom Healthcheck