laboratori-cloud/TROUBLESHOOTING.md

# Troubleshooting - Guida Risoluzione Problemi

Questo documento copre i problemi più comuni che possono verificarsi durante i laboratori.

## Problemi Generali Docker

### Container non parte

**Sintomo:** `docker compose up` fallisce con errori

**Soluzioni:**
```bash
# Verifica Docker sia in esecuzione
docker ps

# Verifica logs del container
docker logs <container-name>

# Verifica non ci siano conflitti di porte
docker ps
netstat -tuln | grep <porta>
```

### Permesso negato

**Sintomo:** `permission denied` o `Got permission denied`

**Soluzioni:**
```bash
# Aggiungi utente al gruppo docker
sudo usermod -aG docker $USER

# Logout e login, oppure:
newgrp docker

# Verifica appartenenza al gruppo
groups $USER
```

### Porta già in uso

**Sintomo:** `port is already allocated`

**Soluzioni:**
```bash
# Prima prova la pulizia mirata del corso
./scripts/prepare-lab.sh --dry-run
./scripts/prepare-lab.sh

# Trova processo usando la porta
sudo lsof -i :<porta>
sudo netstat -tulpn | grep <porta>

# Ferma il servizio che usa la porta
sudo systemctl stop <servizio>

# Oppure cambia porta nel docker-compose.yml
ports:
  - "127.0.0.1:8081:80"  # Usa porta diversa
```

## Lab-Specifici

### Lab 01 - IAM & Sicurezza

#### Container gira come root

**Verifica:**
```bash
docker exec lab01-<container> whoami
```

**Soluzione:** Il Dockerfile deve creare un utente non-root.

#### Utente non può accedere a Docker

**Sintomo:** `permission denied while trying to connect`

**Verifica:**
```bash
groups <utente>
```

**Soluzione:**
```bash
sudo usermod -aG docker <utente>
newgrp docker
```

### Lab 02 - Network & VPC

#### Container non possono comunicare

**Verifica:**
```bash
docker network inspect lab02-vpc-private
docker network inspect lab02-vpc-public
```

**Soluzione:** Assicurati che i container siano nella stessa rete.

#### Ping fallisce tra reti

**Sintomo:** `ping: bad address` o `Network is unreachable`

**Verifica:**
```bash
# Verifica IP assegnati
docker inspect <container> | grep IPAddress
```

**Soluzione:** Le reti sono isolate per design. Usa container multi-homed per testare.

### Lab 03 - Compute & EC2

#### Healthcheck sempre unhealthy

**Verifica:**
```bash
docker inspect <container> --format '{{.State.Health}}'
```

**Soluzione:** Verifica il comando healthcheck e la configurazione del servizio.

#### Resource limits non applicati

**Verifica:**
```bash
docker stats
docker inspect <container> --format '{{.HostConfig.Memory}}'
```

**Soluzione:** Assicurati che `deploy.resources` sia configurato in docker-compose.yml.

### Lab 04 - Storage & S3

#### Dati persi dopo riavvio

**Verifica:**
```bash
docker volume ls
docker volume inspect <volume>
```

**Soluzione:** Assicurati di usare volumi nominativi, non bind mount anonimi.

#### MinIO non accessibile

**Verifica:**
```bash
curl http://localhost:9000/minio/health/live
```

**Soluzione:** Verifica che MinIO sia in esecuzione e che le porte siano corrette.

### Lab 05 - Database & RDS

#### Database non accessibile

**Verifica:**
```bash
docker exec lab05-db pg_isready -U lab05_user
```

**Soluzione:** Il database è in rete privata. Usa un client PostgreSQL nella stessa rete privata:
```bash
docker run --rm --network lab05-vpc-private \
  -e PGPASSWORD=lab05_password \
  postgres:16-alpine \
  psql -h db -U lab05_user -d lab05_db
```

#### Connessione dal host fallisce

**Sintomo:** `connection refused`

**Soluzione:** CORRETTO! Il database non deve essere accessibile dall'host (INF-02).

## Comandi Utili

### Pulizia completa

```bash
# Ferma tutti i container
docker compose down

# Rimuovi volumi (ATTENZIONE: perdita dati!)
docker compose down -v

# Rimuovi reti non usate
docker network prune

# Rimuovi container stopped
docker container prune

# Pulizia mirata dei laboratori cloud
./scripts/prepare-lab.sh --dry-run
./scripts/prepare-lab.sh

# Reset completo
./scripts/reset-env.sh --dry-run
./scripts/reset-env.sh
```

### Diagnostica

```bash
# Verifica risorse
docker stats

# Verifica eventi
docker events

# Ispeziona container
docker inspect <container>

# Verifica reti
docker network ls
docker network inspect <network>

# Verifica volumi
docker volume ls
docker volume inspect <volume>
```

## Quando Chiedere Aiuto

Prima di chiedere:

1. ✅ Cerca nei tutorial del lab
2. ✅ Controlla troubleshooting del lab specifico
3. ✅ Esegui i test per identificare il problema
4. ✅ Verifica i log dei container

Se il problema persiste:

- Apri una issue su GitHub
- Includi: errore completo, passi per riprodurre, ambiente
- Specifica: OS, Docker version, lab specifico

---

**Nota:** La maggior parte dei problemi sono risolvibili verificando i log e assicurandosi che i prerequisiti siano soddisfatti.