257 lines
9.0 KiB
Markdown
257 lines
9.0 KiB
Markdown
---
|
|
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>
|