laboratori-cloud/.planning/phases/01-setup-git-foundation/01-01-PLAN.md

---
phase: 01-setup-git-foundation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [scripts/check-env.sh, scripts/validate-compose.sh, scripts/reset-env.sh]
autonomous: true
requirements: [SETUP-01, SETUP-02, SETUP-03, SETUP-04, INF-05]
user_setup: []

must_haves:
  truths:
    - "Studente puo eseguire script che verifica Docker Engine >= 24.0"
    - "Studente puo eseguire script che verifica Docker Compose V2"
    - "Studente puo eseguire script che verifica utility di rete (netcat, curl, iproute2)"
    - "Studente puo eseguire script che riporta risorse di sistema (RAM, CPU)"
    - "Studente puo validare file docker-compose.yml con script"
    - "Studente puo eseguire cleanup completo ambiente (container, reti, volumi)"
  artifacts:
    - path: "scripts/check-env.sh"
      provides: "Verifica ambiente Docker (versione, utility, risorse)"
      min_lines: 80
      contains: ["docker.*version", "compose", "netcat|nc", "curl", "free|meminfo"]
    - path: "scripts/validate-compose.sh"
      provides: "Validazione syntax docker-compose.yml"
      min_lines: 30
      contains: ["docker compose config", "YAML"]
    - path: "scripts/reset-env.sh"
      provides: "Cleanup Docker environment"
      min_lines: 40
      contains: ["docker ps", "docker network", "docker volume", "rm"]
  key_links:
    - from: "scripts/check-env.sh"
      to: "Docker Engine"
      via: "docker --version command"
      pattern: "docker.*--version"
    - from: "scripts/validate-compose.sh"
      to: "docker-compose.yml"
      via: "docker compose config parsing"
      pattern: "docker compose config"
    - from: "scripts/reset-env.sh"
      to: "Docker daemon"
      via: "docker CLI cleanup commands"
      pattern: "docker.*rm"
---

<objective>
Create validation scripts that verify Docker environment requirements and provide cleanup utilities for lab workflows.

Purpose: Students need reliable tools to verify their Docker setup meets course requirements before starting labs, and a way to reset their environment between labs.
Output: Three executable bash scripts (check-env.sh, validate-compose.sh, reset-env.sh) with clear error messages and appropriate exit codes.
</objective>

<execution_context>
@/home/luca/.claude/get-shit-done/workflows/execute-plan.md
@/home/luca/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md
@.planning/phases/01-setup-git-foundation/01-RESEARCH.md
@.planning/phases/01-setup-git-foundation/01-VALIDATION.md
@CLAUDE.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create environment check script (check-env.sh)</name>
  <files>scripts/check-env.sh</files>
  <action>
Create bash script that verifies Docker environment meets course requirements. Script MUST include:

1. **Standard header** (per CLAUDE.md):
```bash
#!/bin/bash
# Laboratori Cloud - Environment Check Script
# Part of: "Corso Soluzioni Cloud"
#
# Description: Verifies Docker Engine >= 24.0, Compose V2, network utilities, and system resources
# Usage: ./scripts/check-env.sh
```

2. **Docker Engine version check:**
   - Run `docker --version` to get version
   - Parse major version number
   - Exit with error if < 24.0
   - Clear message: "ERROR: Docker Engine >= 24.0 required. Found: X.Y.Z"

3. **Docker Compose V2 check:**
   - Run `docker compose version` (V2 syntax, not `docker-compose`)
   - Exit with error if command not found
   - Clear message: "ERROR: Docker Compose V2 required. Use 'docker compose' not 'docker-compose'"

4. **Network utilities check:**
   - Check for `netcat` or `nc`
   - Check for `curl`
   - Check for `ip` (iproute2)
   - Exit with error listing missing utilities

5. **System resources check:**
   - Report available RAM (using `free -h` or `/proc/meminfo`)
   - Report CPU cores (using `nproc`)
   - Warn if RAM < 8GB (recommended: 16GB per RESEARCH.md)

6. **Exit codes:**
   - 0: All checks pass
   - 1: One or more checks fail
   - Clear color-coded output (green for pass, red for fail)

7. **Idempotency:** Script can be run multiple times without side effects

DO NOT use interactive prompts. DO NOT require root. DO NOT modify system state.
</action>
  <verify>
    <automated>./scripts/check-env.sh && echo "PASS" || echo "FAIL"</automated>
  </verify>
  <done>
  Script exits 0 when Docker >= 24.0, Compose V2, and all utilities present.
  Script exits 1 with clear error message when any requirement missing.
  Script reports RAM and CPU resources accurately.
  </done>
</task>

<task type="auto">
  <name>Task 2: Create compose validation script (validate-compose.sh)</name>
  <files>scripts/validate-compose.sh</files>
  <action>
Create bash script that validates docker-compose.yml files before deployment. Script MUST include:

1. **Standard header:**
```bash
#!/bin/bash
# Laboratori Cloud - Docker Compose Validation Script
# Part of: "Corso Soluzioni Cloud"
#
# Description: Validates docker-compose.yml syntax using 'docker compose config'
# Usage: ./scripts/validate-compose.sh [path-to-compose-file]
```

2. **Argument handling:**
   - Accept path to compose file as first argument
   - If no argument, show usage message and exit 1
   - If file doesn't exist, exit 1 with clear error

3. **Validation logic:**
   - Run `docker compose -f [file] config` to parse YAML
   - Exit 0 if config valid (YAML parses successfully)
   - Exit 1 if config invalid (syntax errors, invalid directives)

4. **Error reporting:**
   - Show docker compose error output on failure
   - Clear message: "ERROR: docker-compose.yml validation failed"

5. **Edge cases:**
   - Handle relative paths correctly
   - Handle missing file gracefully
   - Suppress docker compose verbose output unless error

DO NOT deploy containers. DO NOT pull images. Validation only.
</action>
  <verify>
    <automated>./scripts/validate-compose.sh /dev/null 2>&1 | grep -i "usage\|error" && echo "USAGE_SHOWN" || true</automated>
  </verify>
  <done>
  Script shows usage when called without arguments.
  Script exits 1 when given non-existent file.
  Script exits 1 when given invalid YAML compose file.
  Script exits 0 when given valid docker-compose.yml.
  </done>
</task>

<task type="auto">
  <name>Task 3: Create environment reset script (reset-env.sh)</name>
  <files>scripts/reset-env.sh</files>
  <action>
Create bash script that cleans Docker environment between labs. Script MUST include:

1. **Standard header:**
```bash
#!/bin/bash
# Laboratori Cloud - Environment Reset Script
# Part of: "Corso Soluzioni Cloud"
#
# Description: Stops all containers, removes all networks and volumes (with confirmation)
# Usage: ./scripts/reset-env.sh [--dry-run]
```

2. **Safety features (per CLAUDE.md "Safety First"):**
   - Default: Require user confirmation before destructive operations
   - Support `--dry-run` flag to show what would be deleted without actually deleting
   - Clear warning: "WARNING: This will stop ALL containers and remove ALL networks and volumes"

3. **Cleanup operations in order:**
   - Stop all running containers (`docker stop $(docker ps -q)`)
   - Remove all containers (`docker rm $(docker ps -aq)`)
   - Remove all user-created networks (`docker network ls -q` filter out bridge/host/none)
   - Remove all volumes (with confirmation, separate from networks)
   - Show count of objects removed

4. **Exit codes:**
   - 0: Cleanup completed successfully
   - 1: User cancelled or error occurred

5. **Idempotency:** Can be run safely on already-clean environment

6. **Output:**
   - Show progress for each operation
   - Clear summary of what was removed
   - No error if nothing to remove

DO NOT remove Docker default networks (bridge, host, none). DO NOT remove Docker images.
</action>
  <verify>
    <automated>./scripts/reset-env.sh --dry-run</automated>
  </verify>
  <done>
  --dry-run flag shows what would be deleted without deleting.
  Default mode requires user confirmation.
  Script removes all containers, networks, and volumes when confirmed.
  Script preserves default Docker networks (bridge, host, none).
  Script exits 0 on successful cleanup.
  </done>
</task>

</tasks>

<verification>
After all tasks complete:
1. Run `./scripts/check-env.sh` — should report all requirements met
2. Run `./scripts/validate-compose.sh` without arguments — should show usage
3. Run `./scripts/reset-env.sh --dry-run` — should show what would be cleaned
4. Verify all scripts are executable (`ls -l scripts/`)
5. Verify scripts have standard headers per CLAUDE.md

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)
</verification>

<success_criteria>
1. All three scripts exist in scripts/ directory and are executable
2. check-env.sh accurately detects Docker Engine >= 24.0, Compose V2, and network utilities
3. validate-compose.sh catches YAML syntax errors in docker-compose.yml files
4. reset-env.sh provides safe cleanup with --dry-run flag
5. All scripts follow CLAUDE.md standards (headers, error messages, exit codes)
</success_criteria>

<output>
After completion, create `.planning/phases/01-setup-git-foundation/01-01-SUMMARY.md` with:
- Scripts created with line counts and key features
- Test results from each script
- Any deviations from RESEARCH.md specification
</output>