docs: complete project research

.planning/research/SUMMARY.md

@@ -0,0 +1,206 @@
+# Project Research Summary
+
+**Project:** Laboratori Cloud - Corso Soluzioni Cloud
+**Domain:** Educational platform for cloud with practical Docker-based labs
+**Researched:** 2026-03-24
+**Confidence:** HIGH
+
+## Executive Summary
+
+This is an educational platform for teaching cloud concepts through local Docker-based laboratories, eliminating cloud costs while maintaining professional-grade learning outcomes. Expert-built cloud education platforms use sandbox environments with clear service mappings, explicit troubleshooting guidance, and structured skill progression. The recommended approach combines Docker's container isolation with a rigorous pedagogical framework (Diátaxis) and test-driven infrastructure methodology.
+
+The research indicates that successful cloud labs require: (1) zero-cost local environments using Docker to simulate AWS services, (2) explicit Docker-to-cloud service mappings (Docker Networks → VPC, MinIO → S3, PostgreSQL → RDS), (3) comprehensive documentation following the Diátaxis framework (Tutorial, How-to, Reference, Explanation) for every lab, and (4) test-driven infrastructure where students write validation scripts before implementing solutions. The key differentiator is the "safety-first" approach that teaches security best practices as core habits rather than afterthoughts.
+
+Critical risks include data loss from improper volume configuration, OOM killer crashes from missing resource limits, and security vulnerabilities from running containers as root. These are mitigated through mandatory named volumes, enforced CPU/memory limits, and non-root user directives in all lab configurations. The most significant pedagogical risk is students failing to understand the cloud parallels, which is addressed through explicit Explanation documents mapping every Docker component to its AWS equivalent.
+
+## Key Findings
+
+### Recommended Stack
+
+**Core technologies:**
+- Docker Engine 28.0+ and Docker Compose V2.36.2+ — Container orchestration foundation, standard market choice with native isolation and rootless support
+- PostgreSQL 18.x or MySQL 9.x — Relational database simulating RDS/Aurora with ACID compliance
+- MinIO RELEASE.2025+ — S3-compatible object storage with 100% API compatibility for local simulation
+- Docker Bridge Networks + iptables — Network isolation simulating VPC/Subnets with NAT and firewall rules
+
+**Critical stack decisions:**
+- Avoid Docker Compose V1 (deprecated) — use V2 integrated syntax
+- Always use named volumes (not bind mounts) for data persistence
+- Enforce resource limits via `deploy.resources.limits` in all services
+- Use non-root users via `user:` directive or Dockerfile USER command
+
+### Expected Features
+
+**Must have (table stakes):**
+- Step-by-step instructions with exact commands — students need unambiguous guidance
+- Working test environment — Docker Compose must start without errors
+- Work verification via test scripts — automated validation (curl, nc, docker ps)
+- Explicit cloud ↔ local parallels — every Docker concept maps to AWS service
+- Basic troubleshooting guides — common errors and solutions
+- Clear prerequisites — Docker versions, OS requirements, minimum resources
+- Environment restoration — reset/cleanup commands for each lab
+- Estimated completion time — 1-3 hours per lab typical
+
+**Should have (competitive differentiators):**
+- ZERO cloud costs — only local Docker, no AWS/Azure accounts
+- Safety-first excellence — least privilege, network isolation, resource limits taught as core habits
+- Complete Diátaxis framework — Tutorial + How-to + Reference + Explanation for EVERY lab
+- Test-Driven Infrastructure (TDI) — RED→GREEN→REFACTOR methodology for infrastructure
+- Designed incrementality — Labs 1-5 build progressively to complete system
+- "Little often" approach — small concepts, frequent practice to avoid overwhelm
+- Explicit Double Check — pre-commit checklists for each laboratory
+- 1:1 architecture mapping — Docker Networks → VPC, MinIO → S3, PostgreSQL → RDS
+- Included test scripts — students learn to validate their own work
+- Professional Git workflow — Conventional Commits, per-lab branches
+
+**Defer (v2+):**
+- Official solutions — add after student requests for self-verification
+- Auto-correction scripts — helpful but not essential for learning
+- Optional challenge labs — for advanced students who find core too easy
+- Multi-cloud versions — AWS focus first, Azure/GCP parallels later
+- Pre-configured VM — only if setup issues become widespread
+
+### Architecture Approach
+
+**Major components:**
+1. Docker Engine — Container lifecycle, image management, network isolation
+2. Docker Compose — Multi-container orchestration per lab, service dependencies
+3. Bridge Networks — VPC/Subnet simulation with network isolation and DNS resolution
+4. Named Volumes — Persistent data storage (DB, Object Storage) with data isolation
+5. Test Containers — Network connectivity verification and service health checks
+6. Student Workspace — Git repo, lab documentation, test scripts
+
+**Key architectural patterns:**
+- Network isolation via multiple bridge networks simulating VPC public/private subnets
+- Resource limits enforcing CPU/memory quotas matching cloud instance sizes
+- Healthcheck directives ensuring service readiness before dependencies start
+- Volume initialization with seed data for database labs
+- Test container pattern for isolation and connectivity verification
+
+**Critical anti-patterns to avoid:**
+- Default bridge network (no isolation, poor DNS)
+- Running as root (security vulnerability, violates cloud best practices)
+- Exposing all ports to host (port conflicts, security exposure)
+- Anonymous volumes (difficult management, can't backup easily)
+- No resource limits (unrealistic behavior, no quota simulation)
+
+### Critical Pitfalls
+
+1. **Data loss on container restart** — Always use named Docker volumes with explicit declarations in top-level `volumes:` section; teach volume lifecycle and persistence early
+
+2. **Networking confusion (localhost vs container names)** — Teach Docker's internal DNS resolution first; always use service names for inter-container communication; create network diagrams showing container isolation
+
+3. **OOM killer (resource exhaustion)** — Always set `mem_limit` and CPU limits in docker-compose; monitor with `docker stats`; recommend 16GB RAM minimum for host
+
+4. **Running as root** — Always specify `user:` directive in docker-compose or Dockerfile; teach Linux permission basics alongside Docker; never use `--privileged` flag
+
+5. **Port conflicts and binding issues** — Use non-standard ports in examples (5433 instead of 5432); teach students to check port usage; document all port mappings; provide conflict detection scripts
+
+6. **depends_on without readiness checks** — Implement healthchecks for all services; use restart policies with delays; teach difference between "running" and "healthy"
+
+7. **Orphaned resources (disk space exhaustion)** — Teach cleanup commands in every lab; provide cleanup scripts; use `--rm` flag for one-off containers; explain volume lifecycle
+
+## Implications for Roadmap
+
+Based on research, suggested phase structure:
+
+### Phase 1: Lab 01 - IAM & Security
+**Rationale:** Foundation for all subsequent labs; introduces Docker basics, Linux permissions, volume concepts, and security-first mindset that prevents critical pitfalls #1, #3, #4
+**Delivers:** Docker environment setup, user permissions basics, named volume introduction, cleanup procedures
+**Addresses:** Table stakes (step-by-step instructions, working environment, troubleshooting, prerequisites)
+**Avoids:** Data loss on restart, running as root, orphaned resources, permission errors
+**Features:** Framework Diátaxis (4 docs), test scripts with TDI methodology, Git workflow, cloud parallels (Linux users → IAM Users)
+
+### Phase 2: Lab 02 - Network
+**Rationale:** Core cloud concept (VPC) and critical prerequisite for Labs 3-5; addresses networking confusion (pitfall #2) and port conflicts (pitfall #5)
+**Delivers:** Docker bridge networks, VPC/subnet simulation, DNS resolution, network isolation, port mapping
+**Uses:** Docker Bridge Networks, iptables for NAT/firewall simulation
+**Implements:** Network isolation pattern, test container pattern for connectivity verification
+**Avoids:** Networking confusion, port conflicts, default bridge network anti-pattern
+**Features:** Network diagrams, isolation verification tests, routing table explanations
+
+### Phase 3: Lab 03 - Compute
+**Rationale:** Simulates EC2/VM with resource limits; introduces healthchecks preventing pitfall #6; builds on Lab 2 networking
+**Delivers:** Containers with CPU/memory limits, healthcheck implementation, service dependencies
+**Uses:** Resource limits pattern, healthcheck pattern
+**Implements:** Compute quota simulation, service readiness verification
+**Avoids:** OOM killer, depends_on without readiness checks, no resource limits
+**Features:** Resource monitoring with docker stats, healthcheck test scripts
+
+### Phase 4: Lab 04 - Storage
+**Rationale:** Simulates S3 (MinIO) + Block Storage (Volumes); volume persistence is critical (pitfall #1); independent from Lab 3 but depends on Lab 2 networking
+**Delivers:** MinIO S3-compatible storage, named volume management, volume initialization with seed data
+**Uses:** Docker Volumes, MinIO for S3 simulation
+**Implements:** Volume initialization pattern, object storage access patterns
+**Avoids:** Data loss from missing volumes, anonymous volumes, tmpfs for persistent data
+**Features:** S3 API compatibility demonstration, volume persistence verification tests
+
+### Phase 5: Lab 05 - Database
+**Rationale:** Culmination integrating all concepts (Network + Storage + Compute); simulates RDS in private network; demonstrates multi-tier architecture
+**Delivers:** PostgreSQL/MySQL in isolated network, application-to-database connections, cross-network communication, data persistence
+**Uses:** PostgreSQL/MySQL, named volumes, private networks from Lab 2
+**Implements:** Multi-tier architecture, complete VPC simulation with public/private subnets
+**Avoids:** Networking confusion, depends_on without readiness, data loss
+**Features:** Complete cloud architecture (VPC + RDS + S3), comprehensive integration tests
+
+### Phase Ordering Rationale
+
+- **Lab 1 first** because it establishes foundational security practices and Docker basics that all subsequent labs depend on; skipping this would cause permission errors and security issues throughout
+- **Lab 2 before Labs 3-5** because network isolation is a prerequisite for realistic compute, storage, and database simulation; cloud services depend on VPC networking
+- **Lab 3 before Lab 5** because compute patterns (healthchecks, resource limits) are needed for database-dependent applications
+- **Lab 4 before Lab 5** because storage persistence concepts are needed for database data persistence
+- **Lab 5 last** because it integrates all previous concepts (Network + Compute + Storage) into a complete multi-tier cloud architecture
+
+### Research Flags
+
+**Phases likely needing deeper research during planning:**
+- **Phase 2 (Network):** Complex iptables rules for NAT Gateway simulation may require targeted research during implementation
+- **Phase 5 (Database):** Database initialization timing and cross-network connection pooling may need validation research
+
+**Phases with standard patterns (skip research-phase):**
+- **Phase 1 (IAM):** Well-documented Docker security patterns, standard Linux permission practices
+- **Phase 3 (Compute):** Established resource limit patterns in Docker Compose, standard healthcheck implementations
+- **Phase 4 (Storage):** MinIO documentation is comprehensive, Docker volume patterns are standard
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | HIGH | All technologies verified against official documentation (Docker Engine v28, Compose V2, PostgreSQL 18, MinIO RELEASE.2025) |
+| Features | MEDIUM | Based on competitor analysis and educational best practices; some assumptions about student needs validated through industry patterns |
+| Architecture | HIGH | Docker networking, storage, and orchestration patterns well-documented; architectural decisions backed by official sources |
+| Pitfalls | HIGH | All pitfalls verified against official Docker documentation and common educational patterns in container-based training |
+
+**Overall confidence:** HIGH
+
+### Gaps to Address
+
+- **Student feedback data:** No access to real student feedback on cloud lab effectiveness; will need to validate through beta testing
+- **Multi-cloud parallels:** Research focused on AWS; Azure/GCP parallels not deeply researched but can be added in v2 as requested
+- **Learning effectiveness measurement:** No academic studies available on Docker-based vs cloud-based learning outcomes; assumes equivalence based on service mapping
+- **VM pre-configurata specifics:** Not researched in detail; can address if student setup issues become widespread (deferred to v1.x)
+
+## Sources
+
+### Primary (HIGH confidence)
+- Docker Engine v28 Release Notes — https://docs.docker.com/engine/release-notes/28.0/
+- Docker Compose Documentation — https://docs.docker.com/compose/
+- Docker Bridge Networks — https://docs.docker.com/network/bridge/
+- Docker Storage Documentation — https://docs.docker.com/storage/volumes/
+- MinIO Linux Documentation — https://min.io/docs/minio/linux/index.html
+- PostgreSQL Documentation — https://www.postgresql.org/docs/
+- Docker Rootless Mode — https://docs.docker.com/engine/security/rootless/
+- Docker Security Documentation — https://docs.docker.com/engine/security/
+
+### Secondary (MEDIUM confidence)
+- AWS Skill Builder, Azure Lab Services, KodeKloud, A Cloud Guru — Competitor feature analysis
+- Educational best practices in cloud training platforms
+- Container-based training course patterns
+- Cloud lab environment design patterns
+
+### Tertiary (LOW confidence)
+- None used — all findings based on HIGH or MEDIUM confidence sources
+
+---
+*Research completed: 2026-03-24*
+*Ready for roadmap: yes*