docs(phase-02): complete phase execution - Lab 01 IAM & Sicurezza
This commit is contained in:
Luca Sacchi Ricciardi
236
.planning/phases/01-setup-git-foundation/01-RESEARCH.md
Normal file
236
.planning/phases/01-setup-git-foundation/01-RESEARCH.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# Phase 1: Setup & Git Foundation - Research
|
||||
|
||||
**Researched:** 2026-03-24
|
||||
**Status:** Ready for planning
|
||||
|
||||
---
|
||||
|
||||
## Domain Analysis
|
||||
|
||||
### Context: Educational Cloud Lab Infrastructure
|
||||
|
||||
This phase establishes the foundation for a 5-lab course that simulates cloud services (IAM, Network, Compute, Storage, Database) using local Docker infrastructure. The project follows the **Diátaxis Framework** for documentation and uses **Test-Driven Infrastructure** (TDI) methodology.
|
||||
|
||||
### Target Audience
|
||||
|
||||
Students who have seen Azure superficially but lack practical experience. They need:
|
||||
- Clear, step-by-step instructions
|
||||
- Verification that their environment is correctly set up
|
||||
- Understanding of how local Docker maps to cloud services
|
||||
|
||||
---
|
||||
|
||||
## Technical Research
|
||||
|
||||
### 1. Git Workflow & Conventional Commits
|
||||
|
||||
**Standard:** [Conventional Commits Specification](https://www.conventionalcommits.org/)
|
||||
|
||||
**Why:** Provides clear, atomic commit history that guides students by example.
|
||||
|
||||
**Key commit types for this project:**
|
||||
- `feat:` - New features (labs, components, infrastructure)
|
||||
- `test:` - Test scripts and validation
|
||||
- `docs:` - Documentation (Tutorial, How-to, Reference, Explanation)
|
||||
- `chore:` - Setup, configuration, tooling
|
||||
- `fix:` - Bug fixes
|
||||
|
||||
**Implementation approach:**
|
||||
- Each lab developed on isolated branch (`lab-01-iam`, `lab-02-network`, etc.)
|
||||
- Merge to main only when complete and tested
|
||||
- Commit messages follow pattern: `<type>: <description>`
|
||||
|
||||
### 2. Docker Environment Requirements
|
||||
|
||||
**Required versions:**
|
||||
- Docker Engine >= 24.0
|
||||
- Docker Compose V2 (integrated in `docker compose` command)
|
||||
- Network utilities: `netcat`, `curl`, `iproute2`
|
||||
|
||||
**Verification approach:**
|
||||
- Script checks Docker daemon running
|
||||
- Script verifies Docker Compose V2 available
|
||||
- Script checks network utilities installed
|
||||
- Script reports system resources (RAM, CPU)
|
||||
|
||||
### 3. Repository Structure
|
||||
|
||||
**Required directories:**
|
||||
```
|
||||
laboratori-cloud/
|
||||
├── labs/ # Individual lab directories
|
||||
│ ├── lab-01-iam/
|
||||
│ ├── lab-02-network/
|
||||
│ ├── lab-03-compute/
|
||||
│ ├── lab-04-storage/
|
||||
│ └── lab-05-database/
|
||||
├── how-to-guides/ # Procedure-specific guides
|
||||
├── reference/ # Technical specifications
|
||||
└── README.md # Main project documentation
|
||||
```
|
||||
|
||||
**Rationale:** Clear separation between learning materials (labs), reusable procedures (how-to), and technical specs (reference).
|
||||
|
||||
### 4. Environment Setup Scripts
|
||||
|
||||
**Script 1: Environment Check (`scripts/check-env.sh`)**
|
||||
- Verifies Docker Engine version
|
||||
- Verifies Docker Compose V2 availability
|
||||
- Checks for required network utilities
|
||||
- Reports available system resources
|
||||
- Exits with clear error messages if requirements not met
|
||||
|
||||
**Script 2: Environment Reset (`scripts/reset-env.sh`)**
|
||||
- Stops all running Docker containers
|
||||
- Removes all Docker networks
|
||||
- Removes all Docker volumes (with confirmation)
|
||||
- Provides clean slate for next lab
|
||||
|
||||
**Script 3: Docker Compose Validation (`scripts/validate-compose.sh`)**
|
||||
- Runs `docker compose config` on specified compose file
|
||||
- Validates YAML syntax
|
||||
- Reports configuration errors before deployment
|
||||
|
||||
### 5. README Structure
|
||||
|
||||
**Required sections:**
|
||||
1. Project overview (what and why)
|
||||
2. Prerequisites (Docker, utilities)
|
||||
3. Quick start (clone, check environment)
|
||||
4. Lab overview (5 labs briefly described)
|
||||
5. Git workflow brief
|
||||
6. Troubleshooting pointers
|
||||
|
||||
**Tone:** Direct, simple, technically accurate (per PRD requirements)
|
||||
|
||||
---
|
||||
|
||||
## Validation Architecture
|
||||
|
||||
### Testing Approach for Phase 1
|
||||
|
||||
Since this phase sets up infrastructure and tooling, validation focuses on:
|
||||
|
||||
1. **Script Validation:** Each script must:
|
||||
- Execute without errors on a properly configured system
|
||||
- Provide clear error messages when requirements aren't met
|
||||
- Be idempotent where applicable (reset-env.sh)
|
||||
- Exit with appropriate status codes
|
||||
|
||||
2. **Structure Validation:**
|
||||
- All required directories exist
|
||||
- README.md is accessible and complete
|
||||
- Scripts are executable (`chmod +x`)
|
||||
|
||||
3. **Documentation Validation:**
|
||||
- README accurately describes setup process
|
||||
- Setup instructions can be followed by a new student
|
||||
- Prerequisites are clearly stated
|
||||
|
||||
### "Done" Criteria
|
||||
|
||||
**Success Criterion 1:** Studente può clonare la repository e trovare istruzioni chiare per configurare Docker Engine >= 24.0 e Compose V2
|
||||
- **Validation:** README contains clear Docker installation/verification instructions
|
||||
- **Test:** New user can clone repo and follow instructions successfully
|
||||
|
||||
**Success Criterion 2:** Studente può eseguire script di verifica ambiente che controlla Docker, utility di rete, e risorse minime
|
||||
- **Validation:** `scripts/check-env.sh` exists and runs successfully
|
||||
- **Test:** Script reports all required components correctly
|
||||
|
||||
**Success Criterion 3:** Studente può eseguire comando di reset completo ambiente (cleanup volumi, reti)
|
||||
- **Validation:** `scripts/reset-env.sh` exists and cleans all Docker artifacts
|
||||
- **Test:** After running, `docker ps` shows no containers, `docker network ls` shows only default networks
|
||||
|
||||
**Success Criterion 4:** Ogni file docker-compose.yml può essere validato con `docker-compose config` prima dell'uso
|
||||
- **Validation:** `scripts/validate-compose.sh` exists and validates compose files
|
||||
- **Test:** Script catches YAML errors and configuration issues
|
||||
|
||||
**Success Criterion 5:** Repository ha struttura chiara con cartelle `labs/`, `how-to-guides/`, `reference/`
|
||||
- **Validation:** All directories exist with appropriate placeholder files
|
||||
- **Test:** Directory structure matches planned layout
|
||||
|
||||
---
|
||||
|
||||
## Specific Ideas
|
||||
|
||||
### Script Headers (for consistency)
|
||||
|
||||
All scripts should include:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Laboratori Cloud - [Script Purpose]
|
||||
# Part of: "Corso Soluzioni Cloud"
|
||||
#
|
||||
# Description: [What this script does]
|
||||
# Usage: [command] [options]
|
||||
```
|
||||
|
||||
### README Template
|
||||
|
||||
```markdown
|
||||
# Laboratori Cloud - Corso Soluzioni Cloud
|
||||
|
||||
Simulazione pratica di servizi cloud usando Docker locale.
|
||||
|
||||
## Prerequisiti
|
||||
|
||||
- Docker Engine >= 24.0
|
||||
- Docker Compose V2
|
||||
- Utility: netcat, curl, iproute2
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Clona questa repository
|
||||
2. Esegui `./scripts/check-env.sh` per verificare l'ambiente
|
||||
3. Segui i laboratori in ordine
|
||||
|
||||
## Laboratori
|
||||
|
||||
1. **IAM & Sicurezza** - Utenti Linux, permessi Docker
|
||||
2. **Network & VPC** - Reti isolate, simulazione VPC
|
||||
3. **Compute & EC2** - Container con limiti risorse
|
||||
4. **Storage & S3** - Volumes Docker e MinIO
|
||||
5. **Database & RDS** - PostgreSQL in rete privata
|
||||
```
|
||||
|
||||
### Conventional Commits Examples
|
||||
|
||||
```
|
||||
feat(setup): add repository structure and initial README
|
||||
test(setup): add environment check script
|
||||
docs(setup): add Docker installation instructions
|
||||
chore(setup): make scripts executable
|
||||
feat(setup): add environment reset script
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
None — This phase establishes the foundation. All setup elements are required before labs can begin.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Safety First Considerations
|
||||
|
||||
- `reset-env.sh` should require confirmation before destructive operations
|
||||
- Scripts should not run as root unless absolutely necessary
|
||||
- Validation scripts should check for potential conflicts (port conflicts, existing containers)
|
||||
|
||||
### Little Often Approach
|
||||
|
||||
- Create one script at a time
|
||||
- Validate each script before moving to next
|
||||
- Commit after each working script
|
||||
|
||||
### Double Check Verification
|
||||
|
||||
- After setup, run `check-env.sh` to verify everything works
|
||||
- Test `reset-env.sh` on a clean system to ensure it doesn't break anything
|
||||
- Validate README instructions by following them literally
|
||||
|
||||
---
|
||||
|
||||
*Research complete for Phase 1: Setup & Git Foundation*
|
||||
Reference in New Issue
Block a user