docs(01-02): add comprehensive project README.md
- 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)
This commit is contained in:
Luca Sacchi Ricciardi
186
README.md
186
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 <container-name>`
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user