From 3b02229e817ecaeb9a50270c256836b395fc07fa Mon Sep 17 00:00:00 2001 From: Luca Sacchi Ricciardi Date: Tue, 24 Mar 2026 19:55:47 +0100 Subject: [PATCH] docs(01-02): add comprehensive project README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added project overview explaining Docker-based cloud simulation - Documented prerequisites (Docker >= 24.0, Compose V2) - Added Quick Start section with cloning and check-env.sh instructions - Described all 5 labs with objectives and cloud parallels - Added Git workflow brief with Conventional Commits - Included troubleshooting section for common issues - Followed Diátaxis principles (direct, simple, technically accurate) --- README.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) diff --git a/README.md b/README.md index e69de29..e1a327a 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,186 @@ +# Laboratori Cloud - Corso Soluzioni Cloud + +Simulazione pratica di servizi cloud usando Docker locale. + +Questo corso ti insegna i concetti fondamentali del cloud (IAM, Network, Compute, Storage, Database) +attraverso laboratori pratici che usano Docker per simulare servizi AWS/Azure/GCP. + +## Perché questo corso? + +I servizi cloud sono potenti, ma imparare su account reali può essere costoso e intimidatorio. +Questo corso usa Docker per simulare i componenti core della cloud infrastructure direttamente sul tuo computer. +Ogni laboratorio costruisce un parallelismo diretto tra i container locali e i servizi cloud reali. + +## Prerequisiti + +Prima di iniziare, assicurati di avere: + +- Docker Engine >= 24.0 installato +- Docker Compose V2 (comando `docker compose`, non `docker-compose`) +- Utility di rete: netcat, curl, iproute2 + +### Risorse Minime Consigliate + +- RAM: 16 GB (funziona con 8 GB, ma alcuni lab potrebbero essere lenti) +- CPU: 4 core +- Spazio disco: 20 GB liberi + +### Installazione Docker + +**Linux:** +```bash +# Ubuntu/Debian +curl -fsSL https://get.docker.com -o get-docker.sh +sudo sh get-docker.sh +sudo usermod -aG docker $USER +``` + +**macOS:** +Scarica Docker Desktop da https://www.docker.com/products/docker-desktop/ + +**Windows:** +Scarica Docker Desktop da https://www.docker.com/products/docker-desktop/ + +## Quick Start + +1. Clona questa repository: + ```bash + git clone https://github.com/your-org/laboratori-cloud.git + cd laboratori-cloud + ``` + +2. Verifica il tuo ambiente: + ```bash + ./scripts/check-env.sh + ``` + +3. Se tutti i check passano, sei pronto per iniziare il primo laboratorio! + + Vai in `labs/lab-01-iam/` e segui le istruzioni. + +## Laboratori + +Il corso è composto da 5 laboratori progressivi: + +### 1. IAM & Sicurezza +Configura utenti Linux, permessi Docker socket, capisci i paralleli IAM. +- Crea utenti con permessi limitati +- Configura accesso al Docker socket +- Parallelismo: Utenti Linux -> IAM Users, Gruppi -> IAM Roles + +### 2. Network & VPC +Crea reti Docker isolate che simulano VPC e Subnets cloud. +- Reti bridge isolate +- Regole di firewall tra container +- Parallelismo: Docker Networks -> VPC, Container -> EC2 instances + +### 3. Compute & EC2 +Deploy container con limiti CPU/memoria e healthchecks. +- Configura limiti di risorse +- Implementa healthcheck personalizzati +- Parallelismo: Container -> EC2, Resource limits -> Instance types + +### 4. Storage & S3 +Configura Docker Volumes e MinIO per storage S3-compatible. +- Volumes named e bind mounts +- MinIO come S3 locale +- Parallelismo: Docker Volumes -> EBS, MinIO -> S3 + +### 5. Database & RDS +Deploy PostgreSQL in rete privata con persistenza dati. +- Container database in rete isolata +- Backup e restore dei dati +- Parallelismo: PostgreSQL container -> RDS, Volume -> Snapshot + +## Struttura Repository + +``` +laboratori-cloud/ +├── labs/ # Laboratori (1 per modulo cloud) +│ ├── lab-01-iam/ # IAM & Sicurezza +│ ├── lab-02-network/ # Network & VPC +│ ├── lab-03-compute/ # Compute & EC2 +│ ├── lab-04-storage/ # Storage & S3 +│ └── lab-05-database/ # Database & RDS +├── how-to-guides/ # Guide procedurali specifiche +├── reference/ # Specifiche tecniche e reference +└── scripts/ # Script di verifica e utilità +``` + +## Git Workflow + +Questo repository segue [Conventional Commits](https://www.conventionalcommits.org/). + +Esempi di commit che troverai: +- `feat(lab-01): add user configuration script` +- `test(lab-02): add network isolation test` +- `docs(lab-03): add explanation for healthchecks` + +Ogni laboratorio è sviluppato su un branch isolato (es. `lab-01-iam`) e +mergeggiato su `main` solo quando completo e testato. + +## Framework Diátaxis + +Ogni laboratorio include 4 tipi di documento per supportare diversi stili di apprendimento: + +1. **Tutorial** - Guida passo-passo incrementale +2. **How-to Guides** - Procedure specifiche e task-focused +3. **Reference** - Specifiche tecniche e parametri +4. **Explanation** - Concetti e parallelismi cloud/locale + +## Troubleshooting + +### Docker non parte +- Verifica che il demone Docker sia in esecuzione: `docker ps` +- Riavvia Docker: `sudo systemctl restart docker` (Linux) + +### Script check-env.sh fallisce +- Verifica la versione di Docker: `docker --version` (deve essere >= 24.0) +- Verifica Compose V2: `docker compose version` (non `docker-compose`) +- Assicurati di essere nel gruppo docker: `groups $USER` + +### Permesso negato su Docker socket +```bash +sudo usermod -aG docker $USER +# Fai logout e login oppure +newgrp docker +``` + +### Container non parte o crasha subito +- Controlla i log: `docker logs ` +- Verifica le risorse disponibili: `docker stats` +- Controlla le porte in uso: `docker ps` + +### Reset completo ambiente +Per pulire tutto tra un lab e l'altro: +```bash +./scripts/reset-env.sh +``` + +Questo script ferma tutti i container, rimuove volumi e reti create per i laboratori. + +## Safety First + +Questo corso segue principi di sicurezza rigorosi: + +1. **Minimo Privilegio**: I container non girano mai come root +2. **Isolamento di Rete**: Le reti private non espongono porte sull'host +3. **Limiti di Risorse**: Ogni container ha limiti CPU e memoria configurati +4. **Persistenza**: I dati sopravvivono al riavvio dei container + +## Roadmap + +- [x] Phase 1: Setup & Git Foundation +- [ ] Phase 2-5: Sviluppo Laboratori Core +- [ ] Phase 6: Integration & Testing +- [ ] Phase 7-10: Polish & Final Validation + +Vedi `.planning/ROADMAP.md` per dettagli completi. + +## Contributing + +Questo è un progetto didattico. Suggerimenti e miglioramenti sono benvenuti tramite pull request. + +## License + +MIT License - Vedi LICENSE file per dettagli.