docs(01-01): complete Docker validation scripts plan

- Created 3 bash scripts (check-env.sh, validate-compose.sh, reset-env.sh) - All scripts follow CLAUDE.md standards with proper headers and exit codes - Total: 491 lines of bash scripting with color-coded output - Marked 5 requirements complete (SETUP-01 through SETUP-04, INF-05) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-24 19:53:40 +01:00
parent 9b90ed2169
commit 8eae198624
3 changed files with 171 additions and 10 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -37,7 +37,7 @@ Requirements per il rilascio iniziale. Ogni requisito mappa a una fase della roa
 - [ ] **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
+- [x] **INF-05**: File docker-compose.yml validati con `docker-compose config` prima dell'uso

 ### Git & Workflow

@@ -56,10 +56,10 @@ Requirements per il rilascio iniziale. Ogni requisito mappa a una fase della roa

 ### 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)
+- [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)
 - [ ] **SETUP-05**: Fornito comando di reset completo ambiente (cleanup volumi, reti)

 ## v2 Requirements
@@ -123,7 +123,7 @@ Quali fasi coprono quali requisiti. Aggiornato dopo creazione roadmap.
 | 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 | Pending |
+| INF-05 | Phase 1,10 | Complete |
 | GIT-01 | Phase 8 | Pending |
 | GIT-02 | Phase 8 | Pending |
 | GIT-03 | Phase 8 | Pending |
@@ -133,10 +133,10 @@ Quali fasi coprono quali requisiti. Aggiornato dopo creazione roadmap.
 | 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 | Pending |
-| SETUP-02 | Phase 1 | Pending |
-| SETUP-03 | Phase 1 | Pending |
-| SETUP-04 | Phase 1 | 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 | Pending |

 **Coverage:**
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -1,3 +1,18 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: milestone
+current_phase: Phase 1 (Setup & Git Foundation)
+current_plan: TBD
+status: Not started
+last_updated: "2026-03-24T18:53:20.381Z"
+progress:
+  total_phases: 10
+  completed_phases: 0
+  total_plans: 2
+  completed_plans: 1
+---
+
 # STATE: Laboratori Cloud - Corso Soluzioni Cloud

 **Last Updated:** 2026-03-24
@@ -63,6 +78,7 @@ Configurazione repository Git con struttura chiara, documentazione requisiti Doc
 | Framework Diátaxis obbligatorio | Copre tutti gli stili di apprendimento | Ogni lab include 4 documenti |
 | TDD per infrastruttura | Garantisce verificabilità criteri sicurezza | Script test pre-implementazione |
 | Fine granularity (10 phases) | Permette delivery incrementale e feedback frequente | Confermato in config.json |
+| Phase 01-setup-git-foundation P01 | 180 | 3 tasks | 3 files |

 ### Technical Context

--- a/.planning/phases/01-setup-git-foundation/01-01-SUMMARY.md
+++ b/.planning/phases/01-setup-git-foundation/01-01-SUMMARY.md
@@ -0,0 +1,145 @@
+---
+phase: 01-setup-git-foundation
+plan: 01
+subsystem: scripts
+tags: [docker, validation, environment, setup]
+depends_on: []
+provides: [environment-verification, compose-validation, environment-cleanup]
+affects: [labs-startup, student-onboarding]
+tech_stack:
+  added: [bash-scripting, docker-cli, docker-compose-cli]
+  patterns: [idiomatic-bash, color-output, exit-code-handling]
+key_files:
+  created:
+    - path: scripts/check-env.sh
+      size_lines: 165
+      purpose: Verifies Docker environment meets course requirements
+    - path: scripts/validate-compose.sh
+      size_lines: 94
+      purpose: Validates docker-compose.yml files before deployment
+    - path: scripts/reset-env.sh
+      size_lines: 232
+      purpose: Cleans Docker environment between labs
+  modified: []
+decisions: []
+metrics:
+  duration_seconds: 180
+  completed_date: 2026-03-24T18:53:00Z
+  tasks_completed: 3
+  files_created: 3
+  files_modified: 0
+---
+
+# Phase 1 Plan 01: Docker Validation Scripts Summary
+
+**One-liner:** Created three bash scripts for Docker environment verification, compose validation, and environment cleanup with color-coded output and proper exit codes.
+
+## Objective
+
+Create validation scripts that verify Docker environment requirements and provide cleanup utilities for lab workflows. Students need reliable tools to verify their Docker setup meets course requirements before starting labs, and a way to reset their environment between labs.
+
+## Artifacts Created
+
+### scripts/check-env.sh (165 lines)
+
+**Purpose:** Verifies Docker environment meets course requirements.
+
+**Features:**
+- Docker Engine version check (>= 24.0 required)
+- Docker Compose V2 detection (not legacy docker-compose)
+- Network utilities verification (netcat/nc, curl, iproute2)
+- System resources reporting (RAM, CPU cores)
+- Color-coded output (green pass, red fail, yellow warn)
+- Exit code 0 on success, 1 on failures
+
+**Test results:**
+- PASS: Docker Engine 29.2.1 detected
+- PASS: Docker Compose V2 5.1.0 detected
+- PASS: All network utilities available
+- WARN: 15GB RAM (recommended: 16GB)
+
+### scripts/validate-compose.sh (94 lines)
+
+**Purpose:** Validates docker-compose.yml files before deployment.
+
+**Features:**
+- YAML syntax validation using `docker compose config`
+- Clear usage message when called without arguments
+- Graceful handling of missing files
+- Help flag support (-h, --help)
+- Color-coded output
+- Exit code 0 on valid config, 1 on errors
+
+**Test results:**
+- PASS: Shows usage when called without arguments
+- PASS: Exits 1 when given non-existent file
+- PASS: Validates valid compose files successfully
+- PASS: Detects YAML syntax errors
+
+### scripts/reset-env.sh (232 lines)
+
+**Purpose:** Cleans Docker environment between labs.
+
+**Features:**
+- Interactive mode with user confirmation
+- --dry-run flag for safe preview
+- Stops all containers
+- Removes all user-created networks (preserves bridge, host, none)
+- Removes all volumes
+- Preserves Docker images
+- Clear warning messages
+- Progress reporting
+
+**Test results:**
+- PASS: --dry-run shows what would be deleted
+- PASS: Default mode requires user confirmation
+- PASS: Detects and reports current environment state
+- PASS: Preserves default Docker networks
+
+## Deviations from Plan
+
+**Rule 1 - Bug:** Fixed `set -e` causing premature exit in check-env.sh
+
+**Found during:** Task 1 execution
+
+**Issue:** The script used `set -e` which caused it to exit when command substitutions encountered expected failures (like `docker compose version` when checking for V2).
+
+**Fix:** Removed `set -e` and handled command failures gracefully using conditional checks instead.
+
+**Files modified:** scripts/check-env.sh
+
+**Commit:** a60a9ab
+
+## Technical Decisions
+
+1. **Color-coded output:** All three scripts use ANSI color codes for better readability (green for success, red for errors, yellow for warnings).
+
+2. **Exit code consistency:** All scripts follow standard Unix conventions (0 for success, 1 for errors).
+
+3. **Idempotency:** All scripts can be run multiple times without side effects.
+
+4. **Safety first:** reset-env.sh requires confirmation by default and provides --dry-run flag for safe preview.
+
+## Cross-Verification
+
+- check-env.sh validates SETUP-01 (Docker >= 24.0), SETUP-02 (network utilities), SETUP-03 (resources), SETUP-04 (verification script)
+- validate-compose.sh validates INF-05 (compose validation before use)
+
+## Self-Check: PASSED
+
+**Verification steps:**
+- [x] All scripts exist in scripts/ directory and are executable (rwxrwxrwx)
+- [x] check-env.sh accurately detects Docker Engine >= 24.0, Compose V2, and network utilities
+- [x] validate-compose.sh catches YAML syntax errors in docker-compose.yml files
+- [x] reset-env.sh provides safe cleanup with --dry-run flag
+- [x] All scripts follow CLAUDE.md standards (headers, error messages, exit codes)
+
+**File existence checks:**
+- FOUND: /home/luca/Sources/LucaSacchiNet/laboratori-cloud/scripts/check-env.sh
+- FOUND: /home/luca/Sources/LucaSacchiNet/laboratori-cloud/scripts/validate-compose.sh
+- FOUND: /home/luca/Sources/LucaSacchiNet/laboratori-cloud/scripts/reset-env.sh
+
+**Commit checks:**
+- FOUND: a60a9ab (feat(01-01): add environment check script (check-env.sh))
+- FOUND: f9a3e1e (feat(01-01): add compose validation script (validate-compose.sh))
+- FOUND: 9b90ed2 (feat(01-01): add environment reset script (reset-env.sh))