From 478e940b4302ae0b654f1763cea01d0264dd676b Mon Sep 17 00:00:00 2001 From: Luca Sacchi Ricciardi Date: Fri, 10 Apr 2026 14:50:06 +0000 Subject: [PATCH] feat: add targeted lab preparation workflow --- README.md | 24 ++++- STUDENT-GUIDE.md | 189 ++++++++++++++++++++------------- TROUBLESHOOTING.md | 9 ++ labs/lab-02-network/README.md | 8 ++ labs/lab-03-compute/README.md | 8 ++ labs/lab-04-storage/README.md | 6 ++ labs/lab-05-database/README.md | 8 ++ scripts/prepare-lab.sh | 151 ++++++++++++++++++++++++++ 8 files changed, 327 insertions(+), 76 deletions(-) create mode 100755 scripts/prepare-lab.sh diff --git a/README.md b/README.md index 8ea19cd..c988abf 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,17 @@ sudo usermod -aG docker $USER 4. Se tutti i check passano, sei pronto per iniziare il primo laboratorio! +## Preparazione Lab + +Prima di iniziare un nuovo laboratorio, prepara l'ambiente del corso: + +```bash +./scripts/prepare-lab.sh --dry-run +./scripts/prepare-lab.sh +``` + +Questo script pulisce solo le risorse create dai laboratori cloud e riduce i conflitti di porte, reti e container tra un lab e l'altro. + ## Laboratori Il corso è composto da 5 laboratori progressivi: @@ -169,12 +180,21 @@ newgrp docker - Controlla le porte in uso: `docker ps` ### Reset completo ambiente -Per pulire tutto tra un lab e l'altro: +Per pulire solo le risorse del corso tra un lab e l'altro: ```bash +./scripts/prepare-lab.sh --dry-run +./scripts/prepare-lab.sh +``` + +Per pulire invece tutto l'ambiente Docker locale: +```bash +./scripts/reset-env.sh --dry-run ./scripts/reset-env.sh ``` -Questo script ferma tutti i container, rimuove volumi e reti create per i laboratori. +`prepare-lab.sh` e il comando consigliato per gli studenti. + +`reset-env.sh` e piu distruttivo: ferma tutti i container e rimuove tutte le reti e i volumi Docker creati dall'utente. ## Safety First diff --git a/STUDENT-GUIDE.md b/STUDENT-GUIDE.md index 77c1cd6..b634f55 100644 --- a/STUDENT-GUIDE.md +++ b/STUDENT-GUIDE.md @@ -1,8 +1,8 @@ # Guida per Studenti - Corso Laboratori Cloud -Benvenuto nel Corso Laboratori Cloud! Questa guida ti spiega come utilizzare al meglio questo corso di simulazione pratica dei servizi cloud usando Docker locale. +Benvenuto nel Corso Laboratori Cloud. Questa guida ti spiega come usare al meglio il corso di simulazione pratica dei servizi cloud con Docker locale. -## Cosa è questo corso? +## Cosa e questo corso? Questo corso ti insegna i concetti fondamentali del cloud computing (IAM, Networking, Compute, Storage, Database) attraverso laboratori pratici. Invece di usare account cloud costosi, usiamo Docker sul tuo computer per simulare i servizi AWS/Azure/GCP. @@ -13,35 +13,39 @@ Ogni laboratorio ti guida passo-passo nella creazione di infrastrutture locali c Prima di iniziare, assicurati di avere: - **VM Linux Debian** (es. Debian 13) con Docker Engine >= 24.0 installato -- **Docker Compose V2** (usa `docker compose`, NON `docker-compose` deprecato) -- **Strumenti di rete**: netcat, curl, iproute2 (solitamente preinstallati) +- **Docker Compose V2** (usa `docker compose`, non `docker-compose`) +- **Strumenti di rete**: netcat, curl, iproute2 ### Installazione VM e Docker 1. **Installa una VM con Debian 13** (o versione recente) 2. **Installa Docker nella VM:** - ```bash - wget -O install-docker.sh https://get.docker.com/ - chmod +x ./install-docker.sh - ./install-docker.sh - sudo usermod -aG docker $USER - # Fai logout e login per applicare i cambiamenti - ``` + +```bash +wget -O install-docker.sh https://get.docker.com/ +chmod +x ./install-docker.sh +./install-docker.sh +sudo usermod -aG docker $USER +# Fai logout e login per applicare i cambiamenti +``` ### Verifica dell'ambiente 1. Apri un terminale nella tua VM Debian 2. Clona la repository: - ```bash - git clone https://gitea.lab.home.lucasacchi.net/lucasacchi/laboratori-cloud - cd laboratori-cloud - ``` -3. Verifica che tutto funzioni: - ```bash - ./scripts/check-env.sh - ``` -Se tutti i controlli passano, sei pronto! +```bash +git clone https://gitea.lab.home.lucasacchi.net/lucasacchi/laboratori-cloud +cd laboratori-cloud +``` + +3. Verifica che tutto funzioni: + +```bash +./scripts/check-env.sh +``` + +Se tutti i controlli passano, sei pronto. ## Come seguire il corso @@ -59,40 +63,64 @@ Il corso ha **5 laboratori progressivi**: Ogni laboratorio ha la stessa struttura: -``` +```text labs/lab-XX-nome/ -├── tutorial/ # Guida passo-passo (LEGGI PRIMA QUESTO) -├── how-to-guides/ # Procedure specifiche per task particolari -├── reference/ # Documentazione tecnica completa -├── explanation/ # Spiegazione dei paralleli cloud/locale -├── docker-compose.yml # Configurazione infrastruttura -└── tests/ # Script di verifica - └── 99-final-verification.sh +|-- README.md # Punto di ingresso del lab +|-- tutorial/ # Guida passo-passo (leggi prima questo) +|-- how-to-guides/ # Procedure specifiche per task particolari +|-- reference/ # Documentazione tecnica completa +|-- explanation/ # Spiegazione dei paralleli cloud/locale +|-- docker-compose.yml # Configurazione infrastruttura +`-- tests/ + `-- 99-final-verification.sh ``` **Ordine consigliato:** -1. Leggi il **tutorial** dall'inizio alla fine -2. Esegui i comandi nel tuo terminale -3. Quando arrivi alla fine, verifica con lo script finale + +1. Leggi `README.md` del lab +2. Segui l'`Ordine Consigliato` indicato nel README +3. Esegui i comandi nel tuo terminale +4. Quando arrivi alla fine, verifica con lo script finale ### 3. Workflow tipico per un laboratorio 1. **Vai nella cartella del lab:** - ```bash - cd labs/lab-01-iam - ``` -2. **Leggi il tutorial** (inizia da `01-*.md`): - - Segui ogni passo attentamente - - Non saltare sezioni - - Pratica ogni comando nel tuo terminale +```bash +cd labs/lab-01-iam +``` -3. **Verifica il completamento:** - ```bash - bash tests/99-final-verification.sh - ``` +2. **Leggi prima `README.md` del lab:** +- Ti dice in che ordine leggere i tutorial +- Ti dice quando avviare `docker compose` +- Ti dice se serve anche `--build` -4. **Se tutto è OK**, passa al laboratorio successivo +3. **Leggi il tutorial** (inizia da `01-*.md`): +- Segui ogni passo attentamente +- Non saltare sezioni +- Pratica ogni comando nel tuo terminale + +4. **Avvia i servizi solo quando README o tutorial te lo chiedono:** +- In molti lab basta `docker compose up -d` +- In alcuni casi puo essere richiesto `docker compose up -d --build` +- In `lab-01-iam` il compose serve soprattutto nella parte finale + +5. **Prima di iniziare un nuovo lab, prepara l'ambiente del corso:** + +```bash +./scripts/prepare-lab.sh --dry-run +./scripts/prepare-lab.sh +``` + +Questo script pulisce solo le risorse create dai laboratori cloud e aiuta a evitare conflitti di porte tra lab consecutivi. + +6. **Verifica il completamento dalla root del lab:** + +```bash +bash tests/99-final-verification.sh +``` + +7. **Se tutto e OK**, passa al laboratorio successivo ## Come verificare che stai facendo bene @@ -100,12 +128,12 @@ labs/lab-XX-nome/ Ogni laboratorio ha uno script `99-final-verification.sh` che controlla: -- ✅ Configurazioni corrette -- ✅ Sicurezza (no root containers, etc.) -- ✅ Funzionalità dei servizi -- ✅ Compliance con i requisiti tecnici +- Configurazioni corrette +- Requisiti di sicurezza del lab +- Funzionalita dei servizi +- Compliance con i requisiti tecnici -**Esegui sempre questo script alla fine di ogni laboratorio!** +**Esegui sempre questo script alla fine di ogni laboratorio, dalla cartella del lab.** ### Cosa fare se la verifica fallisce @@ -113,21 +141,23 @@ Ogni laboratorio ha uno script `99-final-verification.sh` che controlla: 2. Controlla l'output per capire cosa non va 3. Riguarda il tutorial per il passo problematico 4. Riprova la configurazione -5. Se ancora problemi, consulta: - - **How-to guides** per procedure specifiche - - **Troubleshooting** nel tutorial - - **Reference** per sintassi tecnica +5. Se hai ancora problemi, consulta: +- **How-to guides** per procedure specifiche +- **Troubleshooting** nel tutorial +- **Reference** per sintassi tecnica ## Sicurezza e best practices Questo corso segue principi di sicurezza rigorosi: -- 🔒 **Container non-root**: Mai eseguire container come root -- 🚫 **Isolamento rete**: Reti private non esposte sull'host -- 📊 **Limiti risorse**: Ogni container ha limiti CPU/memoria -- 💾 **Persistenza**: Dati che sopravvivono ai riavvii +- **Processi di servizio non privilegiati**: dove previsto, il processo principale del servizio non deve girare come root +- **Isolamento rete**: reti private non esposte sull'host +- **Limiti risorse**: ogni container ha limiti CPU/memoria +- **Persistenza**: i dati sopravvivono ai riavvii -**Rispetta sempre questi principi nei tuoi progetti reali!** +Nota pratica: una shell aperta con `docker exec` puo mostrarti un utente diverso dal processo principale del servizio. Se il tutorial ti fa controllare l'utente effettivo del servizio, segui sempre il metodo documentato nel lab. + +**Rispetta sempre questi principi nei tuoi progetti reali.** ## Pulizia tra laboratori @@ -135,13 +165,20 @@ Per evitare conflitti tra laboratori: ```bash # Dalla root del progetto +./scripts/prepare-lab.sh --dry-run +./scripts/prepare-lab.sh +``` + +Questo e il comando consigliato tra un lab e l'altro. Agisce solo sulle risorse create dal corso. + +Se invece vuoi una pulizia totale del tuo ambiente Docker locale: + +```bash +./scripts/reset-env.sh --dry-run ./scripts/reset-env.sh ``` -Questo comando: -- Ferma tutti i container -- Rimuove reti e volumi creati -- Pulisce l'ambiente per il prossimo lab +Attenzione: `reset-env.sh` agisce su **tutto l'ambiente Docker locale**, non solo sui container del corso. ## Strumenti utili @@ -185,7 +222,7 @@ docker compose ps # Logs di tutti i servizi docker compose logs -# Ricostruisci e riavvia +# Ricostruisci e riavvia (solo se il README del lab lo richiede) docker compose up -d --build ``` @@ -233,24 +270,29 @@ docker image prune # Rimuovi volumi orfani docker volume prune -# Reset completo ambiente +# Pulizia mirata dei laboratori cloud +./scripts/prepare-lab.sh --dry-run +./scripts/prepare-lab.sh + +# Reset completo ambiente (attenzione: rimuove tutti i volumi Docker) +./scripts/reset-env.sh --dry-run ./scripts/reset-env.sh ``` ## Come imparare al meglio -1. **Non copiare-incollare**: Scrivi ogni comando a mano -2. **Comprendi prima di eseguire**: Leggi perché fai ogni passo -3. **Sperimenta**: Modifica parametri e vedi cosa succede -4. **Documenta**: Prendi appunti sui comandi importanti -5. **Collega al cloud**: Pensa sempre "questo in AWS sarebbe..." +1. **Non copiare-incollare**: scrivi ogni comando a mano +2. **Comprendi prima di eseguire**: leggi perche fai ogni passo +3. **Sperimenta**: modifica parametri e vedi cosa succede +4. **Documenta**: prendi appunti sui comandi importanti +5. **Collega al cloud**: pensa sempre "questo in AWS sarebbe..." ## Supporto -- **Documentazione**: Ogni lab ha guide complete -- **Script di verifica**: Ti dicono esattamente cosa è sbagliato -- **Troubleshooting**: Sezioni dedicate in ogni tutorial -- **Reference**: Sintassi completa e parametri +- **Documentazione**: ogni lab ha guide complete +- **Script di verifica**: ti dicono esattamente cosa e sbagliato +- **Troubleshooting**: sezioni dedicate in ogni tutorial +- **Reference**: sintassi completa e parametri ## Prossimi passi dopo il corso @@ -261,5 +303,4 @@ Una volta completati tutti i 5 laboratori: - Potrai applicare questi concetti nei tuoi progetti reali - Sarai pronto per certificazioni cloud (AWS, Azure, GCP) -**Buon apprendimento! 🚀** -student-guide.md \ No newline at end of file +**Buon apprendimento!** diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 1107fdb..67348cb 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -43,6 +43,10 @@ groups $USER **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 : sudo netstat -tulpn | grep @@ -186,7 +190,12 @@ 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 ``` diff --git a/labs/lab-02-network/README.md b/labs/lab-02-network/README.md index 05c874e..8f14ecf 100644 --- a/labs/lab-02-network/README.md +++ b/labs/lab-02-network/README.md @@ -6,6 +6,14 @@ Crea reti Docker isolate che simulano VPC e Subnets cloud. Leggi prima i tutorial nell'ordine indicato sotto. In questo lab il `Dockerfile` e solo un supporto per esempi e test manuali: il flusso principale usa `docker-compose.yml`. +Prima di avviare il lab, dalla root del repository esegui: + +```bash +./scripts/prepare-lab.sh +``` + +Questo evita conflitti con porte e container rimasti dai lab precedenti. + ```bash cd labs/lab-02-network docker compose up -d diff --git a/labs/lab-03-compute/README.md b/labs/lab-03-compute/README.md index 868fefb..819a83e 100644 --- a/labs/lab-03-compute/README.md +++ b/labs/lab-03-compute/README.md @@ -6,6 +6,14 @@ Deploy container con limiti CPU/memoria e healthchecks. Leggi prima i tutorial nell'ordine indicato sotto. Il flusso principale del lab usa `docker-compose.yml`; il `Dockerfile` e un supporto separato per test e strumenti. +Prima di avviare il lab, dalla root del repository esegui: + +```bash +./scripts/prepare-lab.sh +``` + +Questo evita conflitti con porte e container rimasti dai lab precedenti. + ```bash cd labs/lab-03-compute docker compose up -d diff --git a/labs/lab-04-storage/README.md b/labs/lab-04-storage/README.md index b2f7546..b65a3b7 100644 --- a/labs/lab-04-storage/README.md +++ b/labs/lab-04-storage/README.md @@ -6,6 +6,12 @@ Configura Docker Volumes e MinIO per storage S3-compatible. Leggi prima i tutorial nell'ordine indicato sotto. Questo lab usa direttamente `docker-compose.yml`: non serve alcun `docker build` manuale. +Prima di avviare il lab, dalla root del repository esegui: + +```bash +./scripts/prepare-lab.sh +``` + ```bash cd labs/lab-04-storage docker compose up -d diff --git a/labs/lab-05-database/README.md b/labs/lab-05-database/README.md index 8919a88..bb7b815 100644 --- a/labs/lab-05-database/README.md +++ b/labs/lab-05-database/README.md @@ -6,6 +6,14 @@ Deploy PostgreSQL in rete privata con persistenza dati. Leggi prima i tutorial nell'ordine indicato sotto. Il flusso principale del lab usa `docker-compose.yml`; il `Dockerfile` e solo un riferimento per client e strumenti, non un prerequisito di avvio. +Prima di avviare il lab, dalla root del repository esegui: + +```bash +./scripts/prepare-lab.sh +``` + +Questo evita conflitti con porte e container rimasti dai lab precedenti. + ```bash cd labs/lab-05-database docker compose up -d diff --git a/scripts/prepare-lab.sh b/scripts/prepare-lab.sh new file mode 100755 index 0000000..28a39ab --- /dev/null +++ b/scripts/prepare-lab.sh @@ -0,0 +1,151 @@ +#!/bin/bash +# Laboratori Cloud - Lab Preparation Script +# Part of: "Corso Soluzioni Cloud" +# +# Description: Cleans only resources created by this course to avoid port/network conflicts before starting a lab. +# Usage: ./scripts/prepare-lab.sh [--dry-run] [--keep-volumes] + +set -u + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +DRY_RUN=false +KEEP_VOLUMES=false + +print_error() { + echo -e "${RED}[ERROR]${NC} $1" >&2 +} + +print_success() { + echo -e "${GREEN}[SUCCESS]${NC} $1" +} + +print_warn() { + echo -e "${YELLOW}[WARN]${NC} $1" +} + +print_info() { + echo -e "${BLUE}[INFO]${NC} $1" +} + +print_usage() { + cat << EOF +Usage: $0 [--dry-run] [--keep-volumes] + +Prepares the environment for a new lab by removing only resources created by this course. + +Options: + --dry-run Show what would be removed without changing anything + --keep-volumes Remove containers and networks, but preserve named volumes + -h, --help Show this help message + +What this script targets: + - Containers named lab01*, lab02-*, lab03-*, lab04-*, lab05-* + - Networks named lab02-vpc-*, lab05-vpc-*, lab-04-storage_default + - Volumes named lab-02-network_*, lab-03-compute_*, lab-04-storage_*, lab-05-database_* + +Examples: + $0 + $0 --dry-run + $0 --keep-volumes + +Exit codes: + 0 - Preparation completed successfully + 1 - Invalid arguments or command failure +EOF +} + +while [ $# -gt 0 ]; do + case "$1" in + --dry-run) + DRY_RUN=true + ;; + --keep-volumes) + KEEP_VOLUMES=true + ;; + -h|--help) + print_usage + exit 0 + ;; + *) + print_error "Unknown option: $1" + echo "" + print_usage + exit 1 + ;; + esac + shift +done + +mapfile -t COURSE_CONTAINERS < <(docker ps -a --format '{{.ID}} {{.Names}}' 2>/dev/null | grep -E '^[0-9a-f]+ (lab01|lab02-|lab03-|lab04-|lab05-)' | cut -d' ' -f1) +mapfile -t COURSE_NETWORKS < <(docker network ls --format '{{.Name}}' 2>/dev/null | grep -E '^(lab02-vpc-|lab05-vpc-|lab-04-storage_default)' || true) +mapfile -t COURSE_VOLUMES < <(docker volume ls --format '{{.Name}}' 2>/dev/null | grep -E '^lab-(02-network|03-compute|04-storage|05-database)_' || true) + +echo "==========================================" +echo "Laboratori Cloud - Prepare Lab" +echo "==========================================" +echo "" + +if [ "$DRY_RUN" = true ]; then + print_warn "DRY RUN MODE: no changes will be made" +fi + +if [ "$KEEP_VOLUMES" = true ]; then + print_warn "KEEP VOLUMES MODE: named volumes will be preserved" +fi + +echo "" +print_info "Resources detected for this course:" +echo " - Containers: ${#COURSE_CONTAINERS[@]}" +echo " - Networks: ${#COURSE_NETWORKS[@]}" +echo " - Volumes: ${#COURSE_VOLUMES[@]}" +echo "" + +if [ ${#COURSE_CONTAINERS[@]} -eq 0 ] && [ ${#COURSE_NETWORKS[@]} -eq 0 ] && { [ "$KEEP_VOLUMES" = true ] || [ ${#COURSE_VOLUMES[@]} -eq 0 ]; }; then + print_success "No course resources found. Environment already ready." + exit 0 +fi + +run_or_print() { + local description="$1" + shift + + if [ "$DRY_RUN" = true ]; then + print_info "Would ${description}: $*" + else + "$@" + fi +} + +if [ ${#COURSE_CONTAINERS[@]} -gt 0 ]; then + print_info "Removing course containers..." + run_or_print "remove containers" docker rm -f "${COURSE_CONTAINERS[@]}" >/dev/null 2>&1 || true + print_success "Processed ${#COURSE_CONTAINERS[@]} container(s)" +fi + +if [ ${#COURSE_NETWORKS[@]} -gt 0 ]; then + print_info "Removing course networks..." + run_or_print "remove networks" docker network rm "${COURSE_NETWORKS[@]}" >/dev/null 2>&1 || true + print_success "Processed ${#COURSE_NETWORKS[@]} network(s)" +fi + +if [ "$KEEP_VOLUMES" = false ] && [ ${#COURSE_VOLUMES[@]} -gt 0 ]; then + print_info "Removing course volumes..." + run_or_print "remove volumes" docker volume rm "${COURSE_VOLUMES[@]}" >/dev/null 2>&1 || true + print_success "Processed ${#COURSE_VOLUMES[@]} volume(s)" +elif [ "$KEEP_VOLUMES" = true ]; then + print_info "Skipping volume removal as requested" +fi + +echo "" +if [ "$DRY_RUN" = true ]; then + print_success "Dry run completed" +else + print_success "Environment ready for the next lab" +fi + +exit 0