lucasacchi/laboratori-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(01): create phase 1 plan (2 plans, 2 waves)

Browse Source
This commit is contained in:
Luca Sacchi Ricciardi
2026-03-24 19:42:52 +01:00
parent e5af5162f9
commit 9229ffe19d
3 changed files with 519 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
.planning/phases/01-setup-git-foundation/01-01-PLAN.md Normal file
View File

@@ -0,0 +1,257 @@
---
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>

256
.planning/phases/01-setup-git-foundation/01-02-PLAN.md Normal file
View File

@@ -0,0 +1,256 @@
---
phase: 01-setup-git-foundation
plan: 02
type: execute
wave: 2
depends_on: [01-01]
files_modified: [README.md, labs/, how-to-guides/, reference/]
autonomous: true
requirements: [GIT-04, GIT-05, SETUP-05]
user_setup: []
must_haves:
truths:
- "Studente puo clonare repository e trovare istruzioni chiare per configurare Docker"
- "Studente puo eseguire script di verifica ambiente dopo cloning"
- "Repository ha struttura chiara con cartelle labs/, how-to-guides/, reference/"
- "README include quick start con comando check-env.sh"
- "README documenta 5 laboratori con brevi descrizioni"
- "README include istruzioni per Docker Engine >= 24.0 e Compose V2"
artifacts:
- path: "README.md"
provides: "Project overview and setup instructions"
min_lines: 60
contains: ["Docker Engine", "Compose V2", "check-env.sh", "Laboratori", "Quick Start"]
- path: "labs/"
provides: "Directory for individual lab modules"
type: "directory"
- path: "how-to-guides/"
provides: "Directory for procedure-specific guides"
type: "directory"
- path: "reference/"
provides: "Directory for technical specifications"
type: "directory"
key_links:
- from: "README.md"
to: "scripts/check-env.sh"
via: "Quick Start instructions"
pattern: "check-env\\.sh"
- from: "README.md"
to: "Docker documentation"
via: "Prerequisites section"
pattern: "Docker Engine.*24"
- from: "labs/ directory"
to: "Individual lab modules"
via: "Directory structure"
pattern: "lab-0[1-5]"
---
<objective>
Create repository structure with clear directory layout and comprehensive README documenting project, prerequisites, and quick start instructions.
Purpose: Students need to understand the project structure immediately after cloning and have clear guidance on setting up their Docker environment.
Output: Repository with labs/, how-to-guides/, reference/ directories and comprehensive README.md following Diátaxis principles (direct, simple tone).
</objective>
<execution_context>
@/home/luca/.claude/get-shit-done/workflows/execute-plan.md
@/home/luca/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 repository directory structure</name>
<files>labs/, labs/lab-01-iam/, labs/lab-02-network/, labs/lab-03-compute/, labs/lab-04-storage/, labs/lab-05-database/, how-to-guides/, reference/</files>
<action>
Create directory structure for the course following RESEARCH.md specification:
1. **Create labs/ directory** with subdirectories for each lab:
- labs/lab-01-iam/ (IAM & Sicurezza)
- labs/lab-02-network/ (Network & VPC)
- labs/lab-03-compute/ (Compute & EC2)
- labs/lab-04-storage/ (Storage & S3)
- labs/lab-05-database/ (Database & RDS)
2. **Create how-to-guides/ directory** for procedure-specific guides (e.g., "Come generare chiavi SSH", "Come ripulire volumi Docker")
3. **Create reference/ directory** for technical specifications (e.g., docker-compose.yml examples, IP mappings, port references)
4. **Add placeholder README.md in each lab directory** with:
```markdown
# Lab XX: [Lab Name]
Coming soon.
This lab will cover: [brief description]
```
DO NOT create any lab content yet — only directory structure and placeholder READMEs.
</action>
<verify>
<automated>test -d labs && test -d how-to-guides && test -d reference && test -d labs/lab-01-iam && test -d labs/lab-02-network && test -d labs/lab-03-compute && test -d labs/lab-04-storage && test -d labs/lab-05-database && echo "STRUCTURE_OK"</automated>
</verify>
<done>
All required directories exist (labs/, how-to-guides/, reference/).
All 5 lab subdirectories exist under labs/.
Each lab has a placeholder README.md.
</done>
</task>
<task type="auto">
<name>Task 2: Write comprehensive README.md</name>
<files>README.md</files>
<action>
Write project README.md following the template from RESEARCH.md and Diátaxis framework (direct, simple, technically accurate tone).
**Required sections:**
1. **Project Overview (What and Why):**
```markdown
# Laboratori Cloud - Corso Soluzioni Cloud
Simulazione pratica di servizi cloud usando Docker locale.
Questo corso ti insegna i concetti fondamentali del cloud (IAM, Network, Compute, Storage, Database)
attraverso laboratori pratici che usano Docker per simulare servizi AWS/Azure/GCP.
```
2. **Prerequisites:**
```markdown
## Prerequisiti
Prima di iniziare, assicurati di avere:
- Docker Engine >= 24.0 installato
- Docker Compose V2 (comando `docker compose`, non `docker-compose`)
- Utility di rete: netcat, curl, iproute2
### Risorse Minime Consigliate
- RAM: 16 GB (funziona con 8 GB, ma alcuni lab potrebbero essere lenti)
- CPU: 4 core
- Spazio disco: 20 GB liberi
```
3. **Quick Start:**
```markdown
## Quick Start
1. Clona questa repository:
```bash
git clone [repository-url]
cd laboratori-cloud
```
2. Verifica il tuo ambiente:
```bash
./scripts/check-env.sh
```
3. Se tutti i check passano, sei pronto per iniziare il primo laboratorio!
```
4. **Lab Overview (5 labs briefly described):**
```markdown
## Laboratori
1. **IAM & Sicurezza** - Configura utenti Linux, permessi Docker socket, capisci i paralleli IAM
2. **Network & VPC** - Crea reti Docker isolate che simulano VPC e Subnets cloud
3. **Compute & EC2** - Deploy container con limiti CPU/memoria e healthchecks
4. **Storage & S3** - Configura Docker Volumes e MinIO per storage S3-compatible
5. **Database & RDS** - Deploy PostgreSQL in rete privata con persistenza dati
```
5. **Git Workflow Brief:**
```markdown
## Git Workflow
Questo repository segue [Conventional Commits](https://www.conventionalcommits.org/).
Esempi di commit che troverai:
- `feat(lab-01): add user configuration script`
- `test(lab-02): add network isolation test`
- `docs(lab-03): add explanation for healthchecks`
Ogni laboratorio e sviluppato su un branch isolato (es. `lab-01-iam`) e
mergeggiato su `main` solo quando completo e testato.
```
6. **Troubleshooting Pointers:**
```markdown
## Troubleshooting
### Docker non parte
- Verifica che il demone Docker sia in esecuzione: `docker ps`
- Riavvia Docker: `sudo systemctl restart docker` (Linux)
### Script check-env.sh fallisce
- Verifica la versione di Docker: `docker --version` (deve essere >= 24.0)
- Verifica Compose V2: `docker compose version` (non `docker-compose`)
### Reset completo ambiente
- Per pulire tutto tra un lab e l'altro: `./scripts/reset-env.sh`
```
**Tone guidelines (per PRD requirements):**
- Direct and simple: avoid jargon where possible
- Technically accurate: don't oversimplify technical details
- Italian language: course is in Italian
- Action-oriented: tell students what to do, not what to think about
DO NOT include emojis in the README. DO NOT write placeholder text — all content must be complete and useful.
</action>
<verify>
<automated>grep -q "Docker Engine.*24" README.md && grep -q "check-env.sh" README.md && grep -q "Quick Start" README.md && grep -q "IAM.*Network.*Compute.*Storage.*Database" README.md && echo "README_COMPLETE"</automated>
</verify>
<done>
README.md exists with all required sections.
Prerequisites section documents Docker >= 24.0 and Compose V2.
Quick Start includes cloning instructions and check-env.sh command.
Lab overview describes all 5 labs.
Git workflow brief explains Conventional Commits.
Troubleshooting section covers common issues.
</done>
</task>
</tasks>
<verification>
After all tasks complete:
1. Verify directory structure: `ls -la labs/` shows 5 lab directories
2. Verify README completeness: All sections present and filled with useful content
3. Verify README accuracy: Instructions in README can be followed literally
4. Verify placeholder READMEs exist in each lab directory
5. Test Quick Start instructions by following them literally
Cross-verification:
- Directory structure validates GIT-05 (clear repo structure)
- README validates GIT-04 (cloning and setup instructions)
- README references scripts from Plan 01 (check-env.sh, reset-env.sh)
</verification>
<success_criteria>
1. Repository structure matches RESEARCH.md specification exactly
2. README.md can be followed by a new student to set up Docker environment
3. All 5 lab directories have placeholder READMEs
4. Quick Start instructions are accurate and complete
5. README follows Diátaxis tone guidelines (direct, simple, accurate)
</success_criteria>
<output>
After completion, create `.planning/phases/01-setup-git-foundation/01-02-SUMMARY.md` with:
- Directory structure created
- README.md sections and line counts
- Any deviations from RESEARCH.md template
- Verification results from following README instructions literally
</output>