laboratori-cloud/.planning/REQUIREMENTS.md

# Requirements: Laboratori Cloud - Corso Soluzioni Cloud

**Defined:** 2026-03-24
**Core Value:** Gli studenti imparano i concetti cloud praticamente in locale, senza costi o complessità di account cloud reali.

## v1 Requirements

Requirements per il rilascio iniziale. Ogni requisito mappa a una fase della roadmap.

### Laboratori Core

- [ ] **LAB-01**: Studente può configurare utenti Linux, gruppi e permessi per accesso Docker socket (IAM simulation)
- [ ] **LAB-02**: Studente può creare reti Docker bridge isolate per simulare VPC/Subnets
- [ ] **LAB-03**: Studente può deploy container con limiti CPU/memoria e healthchecks (Compute simulation)
- [ ] **LAB-04**: Studente può configurare Docker volumes e MinIO per storage S3-compatible
- [ ] **LAB-05**: Studente può deploy database PostgreSQL in rete privata con volume persistente (RDS simulation)

### Documentazione (Framework Diátaxis)

- [ ] **DOCT-01**: Ogni lab include Tutorial (guida passo-passo incrementale)
- [ ] **DOCT-02**: Ogni lab include How-to Guides (procedure specifiche slegate dal flusso)
- [ ] **DOCT-03**: Ogni lab include Reference (specifiche tecniche: docker-compose.yml, mappe IP, porte)
- [ ] **DOCT-04**: Ogni lab include Explanation (parallelismo Docker ↔ cloud service)
- [ ] **DOCT-05**: Tutorial seguono principio "little often" (piccoli step, frequente pratica)

### Testing & Qualità

- [ ] **TEST-01**: Ogni lab include script di test bash pre-implementazione (TDI approach RED→GREEN→REFACTOR)
- [ ] **TEST-02**: Script verificano criteri di sicurezza (no root, reti isolate, limiti risorse)
- [ ] **TEST-03**: Script verificano funzionalità (connettività, persistenza dati, accessibilità)
- [ ] **TEST-04**: Ogni lab include sezione troubleshooting con errori comuni e soluzioni
- [ ] **TEST-05**: Ogni lab include comando di verifica finale ("double check")

### Infrastruttura & Sicurezza

- [ ] **INF-01**: Nessun container gira come utente root (principio minimo privilegio)
- [ ] **INF-02**: Reti private non espongono porte sull'host (127.0.0.1 max, mai 0.0.0.0)
- [ ] **INF-03**: Tutti i container hanno limiti risorse obbligatori (cpus, mem_limit)
- [ ] **INF-04**: Dati persistenti sopravvivono a riavvio container (named volumes)
- [x] **INF-05**: File docker-compose.yml validati con `docker-compose config` prima dell'uso

### Git & Workflow

- [ ] **GIT-01**: Ogni lab sviluppato su branch isolato (lab-01-iam, lab-02-network, etc.)
- [ ] **GIT-02**: Commit seguono Conventional Commits (`feat:`, `test:`, `docs:`)
- [ ] **GIT-03**: Commit sono atomici (una funzionalità per commit)
- [x] **GIT-04**: README include istruzioni cloning e setup iniziale
- [x] **GIT-05**: Struttura repo chiara con cartelle `labs/`, `how-to-guides/`, `reference/`

### Parallelismo Cloud ↔ Locale

- [ ] **PARA-01**: Ogni componente Docker è mappato al servizio cloud corrispondente nella Explanation
- [ ] **PARA-02**: Architettura locale usa nomenclatura cloud (VPC, subnet, security groups)
- [ ] **PARA-03**: Differenze tra locale e cloud sono documentate esplicitamente
- [ ] **PARA-04**: Comandi Docker equivalenti a comandi cloud sono mostrati a confronto

### Setup & Requisiti Utente

- [x] **SETUP-01**: Documentato requisito Docker Engine >= 24.0 e Compose V2
- [x] **SETUP-02**: Documentato requisito utility di rete (netcat, curl, iproute2)
- [x] **SETUP-03**: Specificate risorse minime consigliate (RAM, CPU)
- [x] **SETUP-04**: Fornito script di verifica ambiente (check Docker, check versioni)
- [x] **SETUP-05**: Fornito comando di reset completo ambiente (cleanup volumi, reti)

## v2 Requirements

Differiti a rilascio futuro. Tracciati ma non nella roadmap corrente.

### Enhancement Post-Validation

- **SOLU-01**: Soluzioni ufficiali per ogni lab (trigger: richiesta ricorrente studenti)
- **SOLU-02**: Script di auto-correzione per validazione autonoma studente
- **CHAL-01**: Challenge labs opzionali per studenti avanzati
- **MULTI-01**: Versioni multi-cloud (paralleli Azure/GCP oltre ad AWS)

### Infrastructure

- **VM-01**: VM pre-configurata (OVA/Vagrant) per studenti con problemi setup locale

## Out of Scope

Esplicitamente esclusi. Documentati per prevenire scope creep.

| Feature | Reason |
|---------|--------|
| Account cloud reali (AWS/Azure/GCP) | Simulazione locale elimina costi e complessità onboarding |
| Video streaming integrato | Complessità tecnica, bandwidth, distoglie dal "doing" |
| Piattaforma web custom | Sviluppo frontend = distrazione dal valore educativo |
| Lab multi-user collaborativi | Complessità infrastrutturale enorme per v1 |
| Mobile apps | Comandi Docker su mobile = esperienza terribile |
| AI/Chatbot integrato | Costo, complessità manutenzione, risposte inaffidabili |
| Gamification eccessiva | Distrazione dal learning reale |
| Real-time collaboration | Laboratori individuali, condivisione via Git sufficiente |
| Video posts/storage | Storage/bandwidth costs, defer to v2+ |
| OAuth login | Email/password sufficient per v1 |
| Progress tracking integrato | Richiede backend/database, non essenziale per v1 |
| Certification exam prep | Richiede allineamento vendor-specific, lavoro enorme |
| Community features (forum, chat) | Moderation overhead, distrazione dal core |
| Instructor dashboard | Richiede multi-tenancy, mercato diverso |

## Traceability

Quali fasi coprono quali requisiti. Aggiornato dopo creazione roadmap.

| Requirement | Phase | Status |
|-------------|-------|--------|
| LAB-01 | Phase 2 | Pending |
| LAB-02 | Phase 3 | Pending |
| LAB-03 | Phase 4 | Pending |
| LAB-04 | Phase 5 | Pending |
| LAB-05 | Phase 6 | Pending |
| DOCT-01 | Phase 2,3,4,5,6 | Pending |
| DOCT-02 | Phase 2,3,4,5,6,9 | Pending |
| DOCT-03 | Phase 2,3,4,5,6 | Pending |
| DOCT-04 | Phase 2,3,4,5,6 | Pending |
| DOCT-05 | Phase 2,3,4,5,6 | Pending |
| TEST-01 | Phase 2,3,4,5,6 | Pending |
| TEST-02 | Phase 7,10 | Pending |
| TEST-03 | Phase 7,10 | Pending |
| TEST-04 | Phase 7,9 | Pending |
| TEST-05 | Phase 2,3,4,5,6,9 | Pending |
| INF-01 | Phase 2,7,10 | Pending |
| INF-02 | Phase 3,6,7,10 | Pending |
| INF-03 | Phase 4,6,7,10 | Pending |
| INF-04 | Phase 5,6,7,10 | Pending |
| INF-05 | Phase 1,10 | Complete |
| GIT-01 | Phase 8 | Pending |
| GIT-02 | Phase 8 | Pending |
| GIT-03 | Phase 8 | Pending |
| GIT-04 | Phase 1 | Complete |
| GIT-05 | Phase 1,8 | Complete |
| PARA-01 | Phase 2,3,4,5,6,10 | Pending |
| PARA-02 | Phase 3,6,10 | Pending |
| PARA-03 | Phase 2,3,4,5,6,10 | Pending |
| PARA-04 | Phase 2,3,4,5,6,10 | Pending |
| SETUP-01 | Phase 1 | Complete |
| SETUP-02 | Phase 1 | Complete |
| SETUP-03 | Phase 1 | Complete |
| SETUP-04 | Phase 1 | Complete |
| SETUP-05 | Phase 1 | Complete |

**Coverage:**
- v1 requirements: 40 total
- Mapped to phases: 40 ✓
- Unmapped: 0
- Orphaned requirements: 0

---

*Requirements defined: 2026-03-24*
*Last updated: 2026-03-24 after roadmap creation*