local-cloud

TDD-driven infrastructure for a local cloud stack: Floci as AWS emulator, local container registry, and k3s via k3d.

Modules

Module	Purpose	Tests
storage	Versioned S3 bucket	2
network	VPC + public subnet	1
iam	ECS task role + policy	1
dynamodb	State table	1
ecs	Fargate cluster + service	1
local env	Full stack integration	1

7 test runs. All passing. Via the Dagger pipeline: dagger call test-modules from pipeline/.

Stack

• Floci (port 4566) — 69 AWS services
• Local registry (port 5000)
• k3d local-cloud cluster (k3s v1.35.5)

Prerequisites

• OpenTofu >= 1.10
• Docker
• k3d
• distrobox (if running in container)

Usage

# Start the stack
./scripts/up.sh

# Run the full CI pipeline (Dagger Go module)
cd pipeline
dagger call fmt-check
dagger call validate-modules
dagger call test-modules
dagger call integration-plan

The Dagger pipeline at pipeline/ runs OpenTofu format check, schema validation, contract tests, and infrastructure plan — all inside isolated containers. Written in Go using the Dagger SDK v0.21.7.

Deployment to Real AWS

The modules are tested against Floci (an AWS emulator) but are provider-agnostic — they work with real AWS unchanged.

Prerequisites

• An AWS account with credentials (access key + secret key)
• AWS CLI configured (aws configure)

Setup

1. Copy the real AWS environment template:

   cp -r infrastructure/opentofu/environments/real-aws infrastructure/opentofu/environments/staging

2. Edit environments/staging/main.tf — uncomment the S3 backend section and set your state bucket name.

3. Plan against real AWS (credentials never touch your filesystem — passed as Dagger secrets):

   cd pipeline
   dagger call aws-plan \
     --aws-access-key=env:AWS_ACCESS_KEY_ID \
     --aws-secret-key=env:AWS_SECRET_ACCESS_KEY \
     --env=staging

4. Review the plan output. If it looks correct, apply:

   dagger call aws-apply \
     --aws-access-key=env:AWS_ACCESS_KEY_ID \
     --aws-secret-key=env:AWS_SECRET_ACCESS_KEY \
     --env=staging

Important: aws-apply is intentionally gated — it never runs automatically in CI. Plans are read-only; apply requires an explicit local dagger call with human confirmation.

How It Works

The pipeline functions accept AWS credentials as Dagger Secret objects — they are never written to disk, never logged, and never exposed in the container's environment to other processes. The same modules, the same tests, the same pipeline. Only the environment directory and provider config change.

Blog Series

The Philosophical Developer — local cloud chapters:

• Getting Started Guide
• Chapter 13 — Why Local Matters
• Chapter 14 — Code Your Infrastructure
• Chapter 15 — The Pipeline
• Chapter 16 — Deploy to the Local Cloud
• Chapter 17 — Observability
• Chapter 18 — Image Management & ECR