---
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]"
---
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).
@/home/luca/.claude/get-shit-done/workflows/execute-plan.md
@/home/luca/get-shit-done/templates/summary.md
@.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
Task 1: Create repository directory structure
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/
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.
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"
All required directories exist (labs/, how-to-guides/, reference/).
All 5 lab subdirectories exist under labs/.
Each lab has a placeholder README.md.
Task 2: Write comprehensive README.md
README.md
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.
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"
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.
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)
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)