From 8eae1986245f9c3d531067c920378fcec8d936e3 Mon Sep 17 00:00:00 2001 From: Luca Sacchi Ricciardi Date: Tue, 24 Mar 2026 19:53:40 +0100 Subject: [PATCH] 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 --- .planning/REQUIREMENTS.md | 20 +-- .planning/STATE.md | 16 ++ .../01-setup-git-foundation/01-01-SUMMARY.md | 145 ++++++++++++++++++ 3 files changed, 171 insertions(+), 10 deletions(-) create mode 100644 .planning/phases/01-setup-git-foundation/01-01-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 552c1bd..58df6e2 100644 --- 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:** diff --git a/.planning/STATE.md b/.planning/STATE.md index 9047662..af25c60 100644 --- 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 diff --git a/.planning/phases/01-setup-git-foundation/01-01-SUMMARY.md b/.planning/phases/01-setup-git-foundation/01-01-SUMMARY.md new file mode 100644 index 0000000..97ca1a0 --- /dev/null +++ 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))