docs(phase-02): complete phase execution - Lab 01 IAM & Sicurezza

2026-03-24 22:35:47 +01:00
parent 72a634e357
commit b99407c6e0
5 changed files with 602 additions and 7 deletions
--- a/.planning/phases/01-setup-git-foundation/01-RESEARCH.md
+++ b/.planning/phases/01-setup-git-foundation/01-RESEARCH.md
@@ -0,0 +1,236 @@
+# Phase 1: Setup & Git Foundation - Research
+
+**Researched:** 2026-03-24
+**Status:** Ready for planning
+
+---
+
+## Domain Analysis
+
+### Context: Educational Cloud Lab Infrastructure
+
+This phase establishes the foundation for a 5-lab course that simulates cloud services (IAM, Network, Compute, Storage, Database) using local Docker infrastructure. The project follows the **Diátaxis Framework** for documentation and uses **Test-Driven Infrastructure** (TDI) methodology.
+
+### Target Audience
+
+Students who have seen Azure superficially but lack practical experience. They need:
+- Clear, step-by-step instructions
+- Verification that their environment is correctly set up
+- Understanding of how local Docker maps to cloud services
+
+---
+
+## Technical Research
+
+### 1. Git Workflow & Conventional Commits
+
+**Standard:** [Conventional Commits Specification](https://www.conventionalcommits.org/)
+
+**Why:** Provides clear, atomic commit history that guides students by example.
+
+**Key commit types for this project:**
+- `feat:` - New features (labs, components, infrastructure)
+- `test:` - Test scripts and validation
+- `docs:` - Documentation (Tutorial, How-to, Reference, Explanation)
+- `chore:` - Setup, configuration, tooling
+- `fix:` - Bug fixes
+
+**Implementation approach:**
+- Each lab developed on isolated branch (`lab-01-iam`, `lab-02-network`, etc.)
+- Merge to main only when complete and tested
+- Commit messages follow pattern: `<type>: <description>`
+
+### 2. Docker Environment Requirements
+
+**Required versions:**
+- Docker Engine >= 24.0
+- Docker Compose V2 (integrated in `docker compose` command)
+- Network utilities: `netcat`, `curl`, `iproute2`
+
+**Verification approach:**
+- Script checks Docker daemon running
+- Script verifies Docker Compose V2 available
+- Script checks network utilities installed
+- Script reports system resources (RAM, CPU)
+
+### 3. Repository Structure
+
+**Required directories:**
+```
+laboratori-cloud/
+├── labs/                  # Individual lab directories
+│   ├── lab-01-iam/
+│   ├── lab-02-network/
+│   ├── lab-03-compute/
+│   ├── lab-04-storage/
+│   └── lab-05-database/
+├── how-to-guides/         # Procedure-specific guides
+├── reference/             # Technical specifications
+└── README.md              # Main project documentation
+```
+
+**Rationale:** Clear separation between learning materials (labs), reusable procedures (how-to), and technical specs (reference).
+
+### 4. Environment Setup Scripts
+
+**Script 1: Environment Check (`scripts/check-env.sh`)**
+- Verifies Docker Engine version
+- Verifies Docker Compose V2 availability
+- Checks for required network utilities
+- Reports available system resources
+- Exits with clear error messages if requirements not met
+
+**Script 2: Environment Reset (`scripts/reset-env.sh`)**
+- Stops all running Docker containers
+- Removes all Docker networks
+- Removes all Docker volumes (with confirmation)
+- Provides clean slate for next lab
+
+**Script 3: Docker Compose Validation (`scripts/validate-compose.sh`)**
+- Runs `docker compose config` on specified compose file
+- Validates YAML syntax
+- Reports configuration errors before deployment
+
+### 5. README Structure
+
+**Required sections:**
+1. Project overview (what and why)
+2. Prerequisites (Docker, utilities)
+3. Quick start (clone, check environment)
+4. Lab overview (5 labs briefly described)
+5. Git workflow brief
+6. Troubleshooting pointers
+
+**Tone:** Direct, simple, technically accurate (per PRD requirements)
+
+---
+
+## Validation Architecture
+
+### Testing Approach for Phase 1
+
+Since this phase sets up infrastructure and tooling, validation focuses on:
+
+1. **Script Validation:** Each script must:
+   - Execute without errors on a properly configured system
+   - Provide clear error messages when requirements aren't met
+   - Be idempotent where applicable (reset-env.sh)
+   - Exit with appropriate status codes
+
+2. **Structure Validation:**
+   - All required directories exist
+   - README.md is accessible and complete
+   - Scripts are executable (`chmod +x`)
+
+3. **Documentation Validation:**
+   - README accurately describes setup process
+   - Setup instructions can be followed by a new student
+   - Prerequisites are clearly stated
+
+### "Done" Criteria
+
+**Success Criterion 1:** Studente può clonare la repository e trovare istruzioni chiare per configurare Docker Engine >= 24.0 e Compose V2
+- **Validation:** README contains clear Docker installation/verification instructions
+- **Test:** New user can clone repo and follow instructions successfully
+
+**Success Criterion 2:** Studente può eseguire script di verifica ambiente che controlla Docker, utility di rete, e risorse minime
+- **Validation:** `scripts/check-env.sh` exists and runs successfully
+- **Test:** Script reports all required components correctly
+
+**Success Criterion 3:** Studente può eseguire comando di reset completo ambiente (cleanup volumi, reti)
+- **Validation:** `scripts/reset-env.sh` exists and cleans all Docker artifacts
+- **Test:** After running, `docker ps` shows no containers, `docker network ls` shows only default networks
+
+**Success Criterion 4:** Ogni file docker-compose.yml può essere validato con `docker-compose config` prima dell'uso
+- **Validation:** `scripts/validate-compose.sh` exists and validates compose files
+- **Test:** Script catches YAML errors and configuration issues
+
+**Success Criterion 5:** Repository ha struttura chiara con cartelle `labs/`, `how-to-guides/`, `reference/`
+- **Validation:** All directories exist with appropriate placeholder files
+- **Test:** Directory structure matches planned layout
+
+---
+
+## Specific Ideas
+
+### Script Headers (for consistency)
+
+All scripts should include:
+```bash
+#!/bin/bash
+# Laboratori Cloud - [Script Purpose]
+# Part of: "Corso Soluzioni Cloud"
+#
+# Description: [What this script does]
+# Usage: [command] [options]
+```
+
+### README Template
+
+```markdown
+# Laboratori Cloud - Corso Soluzioni Cloud
+
+Simulazione pratica di servizi cloud usando Docker locale.
+
+## Prerequisiti
+
+- Docker Engine >= 24.0
+- Docker Compose V2
+- Utility: netcat, curl, iproute2
+
+## Quick Start
+
+1. Clona questa repository
+2. Esegui `./scripts/check-env.sh` per verificare l'ambiente
+3. Segui i laboratori in ordine
+
+## Laboratori
+
+1. **IAM & Sicurezza** - Utenti Linux, permessi Docker
+2. **Network & VPC** - Reti isolate, simulazione VPC
+3. **Compute & EC2** - Container con limiti risorse
+4. **Storage & S3** - Volumes Docker e MinIO
+5. **Database & RDS** - PostgreSQL in rete privata
+```
+
+### Conventional Commits Examples
+
+```
+feat(setup): add repository structure and initial README
+test(setup): add environment check script
+docs(setup): add Docker installation instructions
+chore(setup): make scripts executable
+feat(setup): add environment reset script
+```
+
+---
+
+## Deferred Ideas
+
+None — This phase establishes the foundation. All setup elements are required before labs can begin.
+
+---
+
+## Implementation Notes
+
+### Safety First Considerations
+
+- `reset-env.sh` should require confirmation before destructive operations
+- Scripts should not run as root unless absolutely necessary
+- Validation scripts should check for potential conflicts (port conflicts, existing containers)
+
+### Little Often Approach
+
+- Create one script at a time
+- Validate each script before moving to next
+- Commit after each working script
+
+### Double Check Verification
+
+- After setup, run `check-env.sh` to verify everything works
+- Test `reset-env.sh` on a clean system to ensure it doesn't break anything
+- Validate README instructions by following them literally
+
+---
+
+*Research complete for Phase 1: Setup & Git Foundation*
--- a/.planning/phases/01-setup-git-foundation/01-VALIDATION.md
+++ b/.planning/phases/01-setup-git-foundation/01-VALIDATION.md
@@ -0,0 +1,88 @@
+---
+phase: 1
+slug: setup-git-foundation
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-03-24
+---
+
+# Phase 1 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Bash script testing |
+| **Config file** | none — Wave 0 installs |
+| **Quick run command** | `./scripts/check-env.sh` |
+| **Full suite command** | `./scripts/check-env.sh && ./scripts/validate-compose.sh labs/lab-01-iam/docker-compose.yml 2>/dev/null || echo "No compose files yet"` |
+| **Estimated runtime** | ~5 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `./scripts/check-env.sh`
+- **After every plan wave:** Run full suite command
+- **Before `/gsd:verify-work`:** Full suite must be green
+- **Max feedback latency:** 10 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| 01-01-01 | 01 | 1 | SETUP-01 | script | `./scripts/check-env.sh` | ✅ W0 | ⬜ pending |
+| 01-01-02 | 01 | 1 | SETUP-02 | script | `./scripts/check-env.sh` | ✅ W0 | ⬜ pending |
+| 01-01-03 | 01 | 1 | SETUP-03 | script | `./scripts/check-env.sh` | ✅ W0 | ⬜ pending |
+| 01-01-04 | 01 | 1 | SETUP-04 | script | `./scripts/check-env.sh` | ✅ W0 | ⬜ pending |
+| 01-01-05 | 02 | 1 | SETUP-05 | script | `./scripts/reset-env.sh --dry-run` | ✅ W0 | ⬜ pending |
+| 01-02-01 | 02 | 1 | INF-05 | script | `./scripts/validate-compose.sh` | ✅ W0 | ⬜ pending |
+| 01-03-01 | 03 | 2 | GIT-04 | file | `test -f README.md` | ✅ W0 | ⬜ pending |
+| 01-03-02 | 03 | 2 | GIT-05 | dir | `test -d labs && test -d how-to-guides && test -d reference` | ✅ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `scripts/check-env.sh` — Verifies Docker Engine >= 24.0, Compose V2, network utilities
+- [ ] `scripts/validate-compose.sh` — Validates docker-compose.yml syntax
+- [ ] `scripts/reset-env.sh` — Cleans Docker containers, networks, volumes
+- [ ] `README.md` — Project overview and setup instructions
+- [ ] `labs/` directory placeholder
+- [ ] `how-to-guides/` directory placeholder
+- [ ] `reference/` directory placeholder
+
+*All scripts must be executable (chmod +x)*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| README clarity for new students | GIT-04 | Requires human judgment | Follow README instructions literally on fresh system |
+| Docker installation instructions accuracy | SETUP-01 | Depends on OS variations | Verify instructions for Ubuntu/Debian, macOS, Windows |
+
+*All core functionality has automated verification.*
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency < 10s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending
--- a/.planning/phases/01-setup-git-foundation/01-VERIFICATION.md
+++ b/.planning/phases/01-setup-git-foundation/01-VERIFICATION.md
@@ -0,0 +1,114 @@
+---
+phase: 01-setup-git-foundation
+verified: 2026-03-24T20:00:00Z
+status: passed
+score: 14/14 must-haves verified
+re_verification: false
+---
+
+# Phase 1: Setup & Git Foundation Verification Report
+
+**Phase Goal:** Repository Git strutturato con Conventional Commits, ambiente di sviluppo configurato, requisiti sistema documentati
+**Verified:** 2026-03-24T20:00:00Z
+**Status:** passed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| #   | Truth   | Status     | Evidence       |
+| --- | ------- | ---------- | -------------- |
+| 1   | Studente puo eseguire script che verifica Docker Engine >= 24.0 | VERIFIED | scripts/check-env.sh line 50: `docker --version` with version parsing |
+| 2   | Studente puo eseguire script che verifica Docker Compose V2 | VERIFIED | scripts/check-env.sh line 67: `docker compose version` check |
+| 3   | Studente puo eseguire script che verifica utility di rete | VERIFIED | scripts/check-env.sh lines 82-106: checks for nc/netcat, curl, ip |
+| 4   | Studente puo eseguire script che riporta risorse di sistema | VERIFIED | scripts/check-env.sh lines 113-149: reports RAM (meminfo/free) and CPU (nproc) |
+| 5   | Studente puo validare file docker-compose.yml con script | VERIFIED | scripts/validate-compose.sh line 81: `docker compose config` validation |
+| 6   | Studente puo eseguire cleanup completo ambiente | VERIFIED | scripts/reset-env.sh lines 133-210: stops containers, removes networks/volumes |
+| 7   | Studente puo clonare repository e trovare istruzioni chiare per configurare Docker | VERIFIED | README.md lines 14-42: Prerequisites with Docker >= 24.0, Compose V2, installation instructions |
+| 8   | Studente puo eseguire script di verifica ambiente dopo cloning | VERIFIED | README.md line 54: `./scripts/check-env.sh` in Quick Start |
+| 9   | Repository ha struttura chiara con cartelle labs/, how-to-guides/, reference/ | VERIFIED | All directories exist with 5 lab subdirectories |
+| 10  | README include quick start con comando check-env.sh | VERIFIED | README.md lines 45-59: Quick Start section with check-env.sh command |
+| 11  | README documenta 5 laboratori con brevi descrizioni | VERIFIED | README.md lines 61-94: All 5 labs described (IAM, Network, Compute, Storage, Database) |
+| 12  | README include istruzioni per Docker Engine >= 24.0 e Compose V2 | VERIFIED | README.md lines 18-20: Docker Engine >= 24.0, Compose V2 requirements |
+| 13  | README documenta risorse minime consigliate (RAM, CPU) | VERIFIED | README.md lines 22-26: RAM 16GB, CPU 4 cores, 20GB disk |
+| 14  | Lab READMEs have placeholder content (expected for Phase 1) | VERIFIED | All 5 lab directories have placeholder README.md with "Coming soon" notice |
+
+**Score:** 14/14 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected    | Status | Details |
+| -------- | ----------- | ------ | ------- |
+| scripts/check-env.sh | Verifica ambiente Docker | VERIFIED | 165 lines, contains docker version check, compose V2 check, network utilities, resource reporting |
+| scripts/validate-compose.sh | Validazione syntax docker-compose.yml | VERIFIED | 94 lines, contains `docker compose config` validation, usage message, error handling |
+| scripts/reset-env.sh | Cleanup Docker environment | VERIFIED | 232 lines, contains `docker rm`, `docker network rm`, `docker volume rm`, --dry-run flag |
+| README.md | Project overview and setup instructions | VERIFIED | 186 lines, contains all required sections (Prerequisites, Quick Start, Lab Overview, Git Workflow, Troubleshooting) |
+| labs/ directory | Directory for individual lab modules | VERIFIED | Exists with 5 subdirectories (lab-01-iam through lab-05-database) |
+| how-to-guides/ directory | Directory for procedure-specific guides | VERIFIED | Directory exists |
+| reference/ directory | Directory for technical specifications | VERIFIED | Directory exists |
+
+### Key Link Verification
+
+| From | To  | Via | Status | Details |
+| ---- | --- | --- | ------ | ------- |
+| scripts/check-env.sh | Docker Engine | docker --version command | WIRED | Line 50: `DOCKER_VERSION=$(docker --version | grep -oP '\d+\.\d+\.\d+' | head -1)` |
+| scripts/validate-compose.sh | docker-compose.yml | docker compose config parsing | WIRED | Line 81: `VALIDATION_OUTPUT=$(cd "$COMPOSE_DIR" && docker compose -f "$(basename "$COMPOSE_FILE")" config 2>&1)` |
+| scripts/reset-env.sh | Docker daemon | docker CLI cleanup commands | WIRED | Lines 162, 182, 202: `docker rm`, `docker network rm`, `docker volume rm` |
+| README.md | scripts/check-env.sh | Quick Start instructions | WIRED | Lines 54, 137: References to `./scripts/check-env.sh` |
+| README.md | Docker documentation | Prerequisites section | WIRED | Line 18: "Docker Engine >= 24.0 installato", Line 19: "Docker Compose V2" |
+| labs/ directory | Individual lab modules | Directory structure | WIRED | 5 lab subdirectories exist (lab-01-iam, lab-02-network, lab-03-compute, lab-04-storage, lab-05-database) |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+| ----------- | ---------- | ----------- | ------ | -------- |
+| GIT-04 | 01-02 | README include istruzioni cloning e setup iniziale | SATISFIED | README.md lines 45-59: Quick Start with git clone instructions and check-env.sh |
+| GIT-05 | 01-02 | Struttura repo chiara con cartelle labs/, how-to-guides/, reference/ | SATISFIED | All three directories exist, plus 5 lab subdirectories |
+| SETUP-01 | 01-01, 01-02 | Documentato requisito Docker Engine >= 24.0 e Compose V2 | SATISFIED | README.md lines 18-20, scripts/check-env.sh validates both |
+| SETUP-02 | 01-01 | Documentato requisito utility di rete (netcat, curl, iproute2) | SATISFIED | README.md line 20, scripts/check-env.sh lines 82-106 verify all |
+| SETUP-03 | 01-01 | Specificate risorse minime consigliate (RAM, CPU) | SATISFIED | README.md lines 22-26: RAM 16GB, CPU 4 cores, scripts/check-env.sh reports actual values |
+| SETUP-04 | 01-01 | Fornito script di verifica ambiente (check Docker, check versioni) | SATISFIED | scripts/check-env.sh exists (165 lines), validates Docker version, Compose V2, utilities |
+| SETUP-05 | 01-01 | Fornito comando di reset completo ambiente (cleanup volumi, reti) | SATISFIED | scripts/reset-env.sh exists (232 lines), stops containers, removes networks/volumes with --dry-run |
+| INF-05 | 01-01 | File docker-compose.yml validati con docker-compose config prima dell'uso | SATISFIED | scripts/validate-compose.sh exists (94 lines), uses `docker compose config` for validation |
+
+**All 8 requirement IDs accounted for and satisfied.**
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+| ---- | ---- | ------- | -------- | ------ |
+| N/A | N/A | None found | N/A | No TODO/FIXME/HACK/PLACEHOLDER comments in scripts, no empty returns, no console.log patterns |
+
+**Note:** Lab READMEs contain "Coming soon" placeholder text (lines 3 of each lab README.md). This is EXPECTED for Phase 1, which only created directory structure. Lab content is developed in later phases.
+
+### Human Verification Required
+
+### 1. Test check-env.sh on Fresh System
+
+**Test:** Run `./scripts/check-env.sh` on a system with Docker < 24.0
+**Expected:** Script should fail with clear error message indicating version requirement
+**Why human:** Cannot programmatically simulate different Docker versions without modifying test environment
+
+### 2. Test reset-env.sh Cleanup
+
+**Test:** Run `./scripts/reset-env.sh` with actual running containers and volumes
+**Expected:** Script should prompt for confirmation, then stop containers and remove networks/volumes
+**Why human:** Requires running Docker environment with actual containers to verify cleanup behavior
+
+### 3. Verify README Instructions From Scratch
+
+**Test:** Follow README.md Quick Start instructions literally on a fresh system
+**Expected:** All steps should work as written (git clone, ./scripts/check-env.sh)
+**Why human:** User experience cannot be fully automated (e.g., clarity of instructions, visual feedback)
+
+### Gaps Summary
+
+No gaps found. All must-haves verified, all artifacts exist and are substantive (not stubs), all key links are wired correctly. All 8 requirement IDs are satisfied with implementation evidence.
+
+**Phase 1 Status:** PASSED - All setup and Git foundation goals achieved.
+
+---
+
+_Verified: 2026-03-24T20:00:00Z_
+_Verifier: Claude (gsd-verifier)_