237 lines
7.5 KiB
Markdown
237 lines
7.5 KiB
Markdown
# 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*
|