laboratori-cloud/.planning/phases/01-setup-git-foundation/01-RESEARCH.md

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

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:

#!/bin/bash
# Laboratori Cloud - [Script Purpose]
# Part of: "Corso Soluzioni Cloud"
#
# Description: [What this script does]
# Usage: [command] [options]

README Template

# 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