From 18d5b2b0622dc5248beb4907543076cd5a8f8b31 Mon Sep 17 00:00:00 2001 From: Luca Sacchi Ricciardi Date: Tue, 24 Mar 2026 19:27:41 +0100 Subject: [PATCH] docs: define v1 requirements --- .planning/REQUIREMENTS.md | 150 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..a7d655a --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,150 @@ +# 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) +- [ ] **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) +- [ ] **GIT-04**: README include istruzioni cloning e setup iniziale +- [ ] **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 + +- [ ] **SETUP-01**: Documentato requisito Docker Engine >= 24.0 e Compose V2 +- [ ] **SETUP-02**: Documentato requisito utility di rete (netcat, curl, iproute2) +- [ ] **SETUP-03**: Specificate risorse minime consigliate (RAM, CPU) +- [ ] **SETUP-04**: Fornito script di verifica ambiente (check Docker, check versioni) +- [ ] **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 durante creazione roadmap. + +| Requirement | Phase | Status | +|-------------|-------|--------| +| LAB-01 | Phase 1 | Pending | +| LAB-02 | Phase 2 | Pending | +| LAB-03 | Phase 3 | Pending | +| LAB-04 | Phase 4 | Pending | +| LAB-05 | Phase 5 | Pending | +| DOCT-01 | Phase 1-5 | Pending | +| DOCT-02 | Phase 1-5 | Pending | +| DOCT-03 | Phase 1-5 | Pending | +| DOCT-04 | Phase 1-5 | Pending | +| DOCT-05 | Phase 1-5 | Pending | +| TEST-01 | Phase 1-5 | Pending | +| TEST-02 | Phase 1-5 | Pending | +| TEST-03 | Phase 1-5 | Pending | +| TEST-04 | Phase 1-5 | Pending | +| TEST-05 | Phase 1-5 | Pending | +| INF-01 | Phase 1-5 | Pending | +| INF-02 | Phase 2-5 | Pending | +| INF-03 | Phase 3-5 | Pending | +| INF-04 | Phase 4-5 | Pending | +| INF-05 | Phase 1-5 | Pending | +| GIT-01 | Phase 1-5 | Pending | +| GIT-02 | Phase 1-5 | Pending | +| GIT-03 | Phase 1-5 | Pending | +| GIT-04 | Phase 1 | Pending | +| GIT-05 | Phase 1 | Pending | +| PARA-01 | Phase 1-5 | Pending | +| PARA-02 | Phase 2-5 | Pending | +| PARA-03 | Phase 1-5 | Pending | +| PARA-04 | Phase 1-5 | Pending | +| SETUP-01 | Phase 1 | Pending | +| SETUP-02 | Phase 1 | Pending | +| SETUP-03 | Phase 1 | Pending | +| SETUP-04 | Phase 1 | Pending | +| SETUP-05 | Phase 1-5 | Pending | + +**Coverage:** +- v1 requirements: 40 total +- Mapped to phases: 0 (pending roadmap creation) +- Unmapped: 40 ⚠️ + +--- + +*Requirements defined: 2026-03-24* +*Last updated: 2026-03-24 after initial definition*