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

docs(02-02): complete Diátxis documentation plan

Browse Source
This commit is contained in:
Luca Sacchi Ricciardi
2026-03-24 22:28:02 +01:00
parent 77235820ac
commit a0c49366b5
4 changed files with 167 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
.planning/REQUIREMENTS.md
View File

@@ -9,7 +9,7 @@ Requirements per il rilascio iniziale. Ogni requisito mappa a una fase della roa
### Laboratori Core
- [ ] **LAB-01**: Studente può configurare utenti Linux, gruppi e permessi per accesso Docker socket (IAM simulation)
- [x] **LAB-01**: Studente può configurare utenti Linux, gruppi e permessi per accesso Docker socket (IAM simulation)
- [ ] **LAB-02**: Studente può creare reti Docker bridge isolate per simulare VPC/Subnets
- [ ] **LAB-03**: Studente può deploy container con limiti CPU/memoria e healthchecks (Compute simulation)
- [ ] **LAB-04**: Studente può configurare Docker volumes e MinIO per storage S3-compatible
@@ -17,11 +17,11 @@ Requirements per il rilascio iniziale. Ogni requisito mappa a una fase della roa
### Documentazione (Framework Diátaxis)
- [ ] **DOCT-01**: Ogni lab include Tutorial (guida passo-passo incrementale)
- [ ] **DOCT-02**: Ogni lab include How-to Guides (procedure specifiche slegate dal flusso)
- [ ] **DOCT-03**: Ogni lab include Reference (specifiche tecniche: docker-compose.yml, mappe IP, porte)
- [ ] **DOCT-04**: Ogni lab include Explanation (parallelismo Docker ↔ cloud service)
- [ ] **DOCT-05**: Tutorial seguono principio "little often" (piccoli step, frequente pratica)
- [x] **DOCT-01**: Ogni lab include Tutorial (guida passo-passo incrementale)
- [x] **DOCT-02**: Ogni lab include How-to Guides (procedure specifiche slegate dal flusso)
- [x] **DOCT-03**: Ogni lab include Reference (specifiche tecniche: docker-compose.yml, mappe IP, porte)
- [x] **DOCT-04**: Ogni lab include Explanation (parallelismo Docker ↔ cloud service)
- [x] **DOCT-05**: Tutorial seguono principio "little often" (piccoli step, frequente pratica)
### Testing & Qualità
@@ -49,10 +49,10 @@ Requirements per il rilascio iniziale. Ogni requisito mappa a una fase della roa
### Parallelismo Cloud ↔ Locale
- [ ] **PARA-01**: Ogni componente Docker è mappato al servizio cloud corrispondente nella Explanation
- [x] **PARA-01**: Ogni componente Docker è mappato al servizio cloud corrispondente nella Explanation
- [ ] **PARA-02**: Architettura locale usa nomenclatura cloud (VPC, subnet, security groups)
- [ ] **PARA-03**: Differenze tra locale e cloud sono documentate esplicitamente
- [ ] **PARA-04**: Comandi Docker equivalenti a comandi cloud sono mostrati a confronto
- [x] **PARA-03**: Differenze tra locale e cloud sono documentate esplicitamente
- [x] **PARA-04**: Comandi Docker equivalenti a comandi cloud sono mostrati a confronto
### Setup & Requisiti Utente
@@ -104,16 +104,16 @@ Quali fasi coprono quali requisiti. Aggiornato dopo creazione roadmap.
| Requirement | Phase | Status |
|-------------|-------|--------|
| LAB-01 | Phase 2 | Pending |
| LAB-01 | Phase 2 | Complete |
| LAB-02 | Phase 3 | Pending |
| LAB-03 | Phase 4 | Pending |
| LAB-04 | Phase 5 | Pending |
| LAB-05 | Phase 6 | Pending |
| DOCT-01 | Phase 2,3,4,5,6 | Pending |
| DOCT-02 | Phase 2,3,4,5,6,9 | Pending |
| DOCT-03 | Phase 2,3,4,5,6 | Pending |
| DOCT-04 | Phase 2,3,4,5,6 | Pending |
| DOCT-05 | Phase 2,3,4,5,6 | Pending |
| DOCT-01 | Phase 2,3,4,5,6 | Complete |
| DOCT-02 | Phase 2,3,4,5,6,9 | Complete |
| DOCT-03 | Phase 2,3,4,5,6 | Complete |
| DOCT-04 | Phase 2,3,4,5,6 | Complete |
| DOCT-05 | Phase 2,3,4,5,6 | Complete |
| TEST-01 | Phase 2,3,4,5,6 | Pending |
| TEST-02 | Phase 7,10 | Pending |
| TEST-03 | Phase 7,10 | Pending |
@@ -129,10 +129,10 @@ Quali fasi coprono quali requisiti. Aggiornato dopo creazione roadmap.
| GIT-03 | Phase 8 | Pending |
| GIT-04 | Phase 1 | Complete |
| GIT-05 | Phase 1,8 | Complete |
| PARA-01 | Phase 2,3,4,5,6,10 | Pending |
| PARA-01 | Phase 2,3,4,5,6,10 | Complete |
| PARA-02 | Phase 3,6,10 | Pending |
| PARA-03 | Phase 2,3,4,5,6,10 | Pending |
| PARA-04 | Phase 2,3,4,5,6,10 | Pending |
| PARA-03 | Phase 2,3,4,5,6,10 | Complete |
| PARA-04 | Phase 2,3,4,5,6,10 | Complete |
| SETUP-01 | Phase 1 | Complete |
| SETUP-02 | Phase 1 | Complete |
| SETUP-03 | Phase 1 | Complete |

4
.planning/ROADMAP.md
View File

@@ -12,7 +12,7 @@
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Setup & Git Foundation | 2/2 | Complete | 2026-03-24 |
| 2. Lab 01 - IAM & Sicurezza | 1/3 | In Progress | 2026-03-24 |
| 2. Lab 01 - IAM & Sicurezza | 2/3 | In Progress| |
| 3. Lab 02 - Network & VPC | 0/3 | Not started | - |
| 4. Lab 03 - Compute & EC2 | 0/3 | Not started | - |
| 5. Lab 04 - Storage & S3 | 0/3 | Not started | - |
@@ -80,7 +80,7 @@
4. Lab include Tutorial passo-passo, How-to Guides, Reference, e Explanation (Framework Diátaxis completo)
5. Studente può eseguire comando di verifica finale ("double check") per validare il lavoro svolto
**Plans:** 3
**Plans:** 2/3 plans executed
- [x] [02-01-PLAN.md](.planning/phases/02-lab-01-iam-sicurezza/02-01-PLAN.md) — Create test infrastructure (Wave 0: test-01-user-creation.sh, test-02-docker-access.sh, 03-non-root-test.sh, 99-final-verification.sh, run-all-tests.sh) **COMPLETE** 2026-03-24
- [ ] [02-02-PLAN.md](.planning/phases/02-lab-01-iam-sicurezza/02-02-PLAN.md) — Create Diátaxis documentation (Tutorial: 3 parts, How-to Guides: 3 guides, Reference: 3 documents, Explanation: IAM parallels)

9
.planning/STATE.md
View File

@@ -3,14 +3,14 @@ gsd_state_version: 1.0
milestone: v1.0
milestone_name: milestone
current_phase: 2
current_plan: 02
current_plan: 02 - User Implementation (next)
status: executing
last_updated: "2026-03-24T21:20:29.000Z"
last_updated: "2026-03-24T21:27:52.266Z"
progress:
total_phases: 10
completed_phases: 1
total_plans: 26
completed_plans: 3
total_plans: 5
completed_plans: 4
---
# STATE: Laboratori Cloud - Corso Soluzioni Cloud
@@ -80,6 +80,7 @@ Repository structure creata, README.md completo con istruzioni setup e troublesh
| Fine granularity (10 phases) | Permette delivery incrementale e feedback frequente | Confermato in config.json |
| Phase 01-setup-git-foundation P01 | 180 | 3 tasks | 3 files |
| Phase 01 P02 | 3 | 2 tasks | 6 files |
| Phase 02-lab-01-iam-sicurezza P02 | 4 | 6 tasks | 10 files |
### Technical Context

142
.planning/phases/02-lab-01-iam-sicurezza/02-02-SUMMARY.md Normal file
View File

@@ -0,0 +1,142 @@
---
phase: 02-lab-01-iam-sicurezza
plan: 02
subsystem: [documentation, iam, docker, linux]
tags: [diataxis, tutorials, how-to-guides, reference, explanation, iam, docker-permissions]
# Dependency graph
requires:
- phase: 02-lab-01-iam-sicurezza/01
provides: [test infrastructure, test scripts for IAM validation]
provides:
- Complete Diátaxis documentation for Lab 01 IAM & Sicurezza
- Tutorials covering Linux user creation, Docker group permissions, and non-root container verification
- How-to guides for common IAM procedures
- Reference documents with technical specifications
- Explanation document mapping Docker concepts to AWS IAM
affects: [02-lab-01-iam-sicurezza/03, all future labs requiring IAM documentation]
# Tech tracking
tech-stack:
added: [Diátaxis framework documentation]
patterns: [4-quadrant documentation structure, tutorial-driven learning, reference tables for cloud parallels]
key-files:
created: [labs/lab-01-iam/tutorial/*.md, labs/lab-01-iam/how-to-guides/*.md, labs/lab-01-iam/reference/*.md, labs/lab-01-iam/explanation/*.md]
modified: []
key-decisions:
- "Italian language for all documentation (as per CLAUDE.md)"
- "No emojis in documentation (as per plan requirements)"
- "Direct, simple language with step-by-step verification"
- "IAM parallels prominently featured in tutorials and explanation"
patterns-established:
- "Pattern 1: Each tutorial follows 'little often' principle with small incremental steps"
- "Pattern 2: Every tutorial has troubleshooting section"
- "Pattern 3: Cross-references between related documents"
- "Pattern 4: Side-by-side comparison tables for local/cloud concepts"
requirements-completed: [LAB-01, DOCT-01, DOCT-02, DOCT-03, DOCT-04, DOCT-05, PARA-01, PARA-03, PARA-04]
# Metrics
duration: 4min
completed: 2026-03-24
---
# Phase 2 Plan 02: Diátaxis Documentation Summary
**Complete Diátaxis framework documentation for Lab 01 IAM & Sicurezza with 10 files covering tutorials, how-to guides, reference specs, and IAM parallelism explanations**
## Performance
- **Duration:** 4 min
- **Started:** 2026-03-24T21:23:26Z
- **Completed:** 2026-03-24T21:27:15Z
- **Tasks:** 6
- **Files modified:** 10
## Accomplishments
- Created 3 tutorial documents following step-by-step "little often" principle
- Created 3 how-to guides for common IAM procedures
- Created 3 reference documents with technical specifications and tables
- Created 1 explanation document mapping Docker concepts to AWS IAM
- All documentation in Italian without emojis as per project guidelines
- All files include cross-references to related content
## Task Commits
Each task was committed atomically:
1. **Task 1: Create Tutorial - Part 1: Linux Users** - `b130b1c` (feat)
2. **Task 2: Create Tutorial - Part 2: Docker Group Permissions** - `b031f58` (feat)
3. **Task 3: Create Tutorial - Part 3: Verification and Non-Root Containers** - `7bd6111` (feat)
4. **Task 4: Create How-to Guides** - `c759270` (feat)
5. **Task 5: Create Reference Documents** - `cc3a28f` (feat)
6. **Task 6: Create Explanation Document (IAM Parallels)** - `7723582` (feat)
**Plan metadata:** TBD (docs: complete plan)
## Files Created/Modified
### Tutorials (3 files)
- `labs/lab-01-iam/tutorial/01-create-linux-users.md` - Step-by-step user creation guide with verification
- `labs/lab-01-iam/tutorial/02-docker-group-permissions.md` - Docker group permissions with IAM parallels
- `labs/lab-01-iam/tutorial/03-verify-iam-setup.md` - Verification and non-root container execution
### How-to Guides (3 files)
- `labs/lab-01-iam/how-to-guides/add-user-to-docker-group.md` - Quick guide for adding users to docker group
- `labs/lab-01-iam/how-to-guides/verify-non-root-container.md` - Multiple methods to verify non-root execution
- `labs/lab-01-iam/how-to-guides/reset-docker-permissions.md` - Complete permission reset guide with troubleshooting
### Reference Documents (3 files)
- `labs/lab-01-iam/reference/docker-socket-permissions.md` - Docker socket technical specifications
- `labs/lab-01-iam/reference/linux-users-groups.md` - Linux user management reference
- `labs/lab-01-iam/reference/iam-parallels.md` - Quick reference table for IAM parallelism
### Explanation (1 file)
- `labs/lab-01-iam/explanation/docker-iam-parallels.md` - Conceptual mapping between Docker and AWS IAM with practical examples
## Decisions Made
- Italian language used throughout all documentation (as per CLAUDE.md requirements)
- No emojis used in any documentation (as per plan specifications)
- Each tutorial includes troubleshooting section for common issues
- Cross-references included between related documents (tutorial → how-to → reference → explanation)
- IAM parallels prominently featured to meet PARA-01, PARA-03, PARA-04 requirements
- "Little often" principle applied with small incremental steps and verification
## Deviations from Plan
None - plan executed exactly as written. All 6 tasks completed without deviations:
- Task 1: Tutorial part 1 created with 162 lines (60+ required)
- Task 2: Tutorial part 2 created with 180 lines (60+ required) and IAM parallels
- Task 3: Tutorial part 3 created with 232 lines (40+ required) and INF-01 coverage
- Task 4: 3 how-to guides created with 20 sections total (9+ required)
- Task 5: 3 reference documents created with 15+ tables
- Task 6: Explanation document created with 361 lines (80+ required) and AWS IAM coverage
All verification tests passed. No auto-fixes were needed.
## Issues Encountered
None - all tasks executed smoothly without issues.
## User Setup Required
None - no external service configuration required. All documentation is self-contained within the repository.
## Next Phase Readiness
- Diátaxis documentation complete and ready for student use
- All 4 quadrants (Tutorial, How-to, Reference, Explanation) implemented
- Test infrastructure from plan 02-01 integrates with documentation
- Ready for plan 02-03 (implementation phase - GREEN phase to make tests pass)
The documentation establishes the foundation for students to learn IAM concepts through local Docker/Linux user management, with clear parallels to AWS IAM for knowledge transfer to cloud environments.
---
*Phase: 02-lab-01-iam-sicurezza*
*Plan: 02*
*Completed: 2026-03-24*