laboratori-cloud/.planning/research/SUMMARY.md

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