laboratori-cloud/.planning/phases/02-lab-01-iam-sicurezza/02-03-SUMMARY.md

phase, plan, title, subsystem, tags, provides, requires, affects, tech-stack, key-files, decisions, metrics, deviations

phase	plan	title	subsystem	tags	provides	requires	affects	tech-stack	key-files	decisions	metrics	deviations
02-lab-01-iam-sicurezza	03	Infrastructure Implementation (GREEN Phase)	Lab 01 - IAM & Sicurezza	docker infrastructure tdd green-phase security	artifact location description Dockerfile labs/lab-01-iam/Dockerfile Non-root container image definition artifact location description docker-compose.yml labs/lab-01-iam/docker-compose.yml Service orchestration with user directive artifact location description 04-verify-infrastructure.sh labs/lab-01-iam/tests/04-verify-infrastructure.sh Infrastructure verification script	plan artifacts 02-01 Test scripts from RED phase plan artifacts 02-02 Research findings on non-root containers	phase plans 02-lab-01-iam-sicurezza 02-04 02-05	added patterns Non-root container execution (USER directive in Dockerfile) User directive enforcement in docker-compose.yml TDD GREEN phase methodology	created modified path lines description labs/lab-01-iam/Dockerfile 61 Non-root container image with labuser (UID 1000) path lines description labs/lab-01-iam/docker-compose.yml 37 Service definition with user: 1000:1000 directive path lines description labs/lab-01-iam/tests/04-verify-infrastructure.sh 163 Infrastructure verification (6 tests) path description None No files modified	decision rationale alternatives Use Alpine 3.19 as base image Minimal, secure, standard for containers ubuntu:22.04 (rejected: too large) debian:bookworm (rejected: larger than alpine) decision rationale alternatives UID/GID 1000 for labuser Standard non-root user ID, avoids conflicts UID 1001+ (rejected: unnecessary complexity) decision rationale impact No resource limits in this phase INF-01 focuses on non-root execution, limits will be added in Lab 03 (Compute) Will be addressed in future phase	duration completed_date tasks_completed files_created total_lines 233 seconds (~4 minutes) 2026-03-24 3 3 261	None - plan executed exactly as written

Phase 2 Plan 03: Infrastructure Implementation (GREEN Phase) Summary

Create Docker infrastructure (Dockerfile and docker-compose.yml) that implements non-root container execution (INF-01). Following TDD methodology, infrastructure is created AFTER tests exist, and tests should now pass (GREEN phase.

What Was Built

1. Dockerfile (labs/lab-01-iam/Dockerfile)

Created a 61-line Dockerfile that implements non-root container execution:

• Base Image: Alpine 3.19 (minimal, secure)
• User Creation: Creates labuser with UID/GID 1000 using addgroup and adduser
• USER Directive: Switches to non-root user BEFORE any operations
• Verification: CMD demonstrates non-root execution with whoami, id, and other checks
• Labels: Metadata for documentation and traceability
• Test File: Creates and verifies write permissions in user's home directory

Key implementation follows INF-01 requirement strictly - no process runs as root.

2. Docker Compose Configuration (labs/lab-01-iam/docker-compose.yml)

Created a 37-line docker-compose.yml that enforces non-root execution:

• Service Definition: lab01-test builds from local Dockerfile
• User Directive: user: "1000:1000" enforces non-root execution
• Container Name: lab01-iam-test for easy reference in tests
• Healthcheck: Verifies non-root user with whoami | grep -q labuser
• No Ports Exposed: Security best practice - not needed for this lab
• Comments: Explains why no volumes/networks (future labs)

Follows Docker Compose V3.8 syntax and INF-01 compliance requirements.

3. Infrastructure Verification Script (labs/lab-01-iam/tests/04-verify-infrastructure.sh)

Created a 163-line bash script that validates all infrastructure requirements:

• Test 1: Validates docker-compose.yml syntax
• Test 2: Checks Dockerfile exists and has USER directive
• Test 3: Verifies docker-compose.yml has non-root user directive
• Test 4: Builds Docker image successfully
• Test 5: Verifies container runs as non-root (whoami check)
• Test 6: Starts docker-compose service and verifies execution

Result: 6/6 tests passed - GREEN phase complete.

Deviations from Plan

None - plan executed exactly as written. All TDD GREEN phase requirements satisfied.

Technical Implementation Details

Non-Root Container Pattern

The implementation follows Docker security best practices:

# Create non-root user
RUN addgroup -g 1000 labuser && \
    adduser -D -u 1000 -G labuser labuser

# Switch BEFORE any operations
USER labuser

# Verify in CMD
CMD ["sh", "-c", "whoami && ..."]

User Directive Enforcement

Docker Compose enforces non-root execution at runtime:

services:
  lab01-test:
    user: "1000:1000"  # UID:GID

This defense-in-depth approach ensures:

1. Dockerfile switches to non-root user
2. docker-compose.yml enforces it at runtime
3. Healthcheck verifies continuously
4. Tests validate automatically

Fixed Issues During Implementation

1. Docker Compose V2 Command: Updated docker-compose to docker compose (hyphen removed in V2)
2. Bash Arithmetic with set -e: Used helper functions inc_pass() and inc_fail() with || true to handle counter increments
3. Docker Build Context: Fixed build command to use -q . instead of -q Dockerfile

Verification Results

All 6 infrastructure tests passed:

[1/6] docker-compose.yml is valid YAML              PASS
[2/6] Dockerfile exists with USER directive          PASS
[3/6] docker-compose.yml user directive (1000:1000)  PASS
[4/6] Docker image builds successfully               PASS
[5/6] Container runs as non-root (labuser)           PASS
[6/6] docker-compose service verification            PASS

Requirements Satisfied

• LAB-01: Students can configure users and Docker permissions
• INF-01: No container runs as root (strictly enforced)
• TEST-01: Test-driven infrastructure methodology followed

Next Steps

Phase 2 Plan 04 will continue with documentation (Diátaxis framework):

• Tutorial: Step-by-step guide for running the lab
• How-to Guides: Specific procedures (cleanup, verification)
• Reference: Technical specifications (ports, commands)
• Explanation: Cloud parallelism concepts

Commits

• 317d94a: feat(02-03): create Dockerfile with non-root user
• c534d59: feat(02-03): create docker-compose.yml with user directive
• e4c497d: feat(02-03): create infrastructure verification script