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:

# 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:

# 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:

# 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:

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:

groups <utente>

Soluzione:

sudo usermod -aG docker <utente>
newgrp docker

Lab 02 - Network & VPC

Container non possono comunicare

Verifica:

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:

# 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:

docker inspect <container> --format '{{.State.Health}}'

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

Resource limits non applicati

Verifica:

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:

docker volume ls
docker volume inspect <volume>

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

MinIO non accessibile

Verifica:

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:

docker exec lab05-db pg_isready -U lab05_user

Soluzione: Il database è in rete privata. Usa un client PostgreSQL nella stessa rete privata:

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

# 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

# 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.