# 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*