Docker First Architecture

Docker-First & Image-First Architecture Skill

This skill defines the official architectural guidelines, containerization blueprints, and publishing standards across all services. It enforces a Docker-First and Image-First doctrine to guarantee infrastructure portability from serverless/PaaS edge environments to cloud container platforms (AWS ECS/EKS) and sovereign self-hosting.

1. Overview & Objective

Every service—regardless of language or framework—must be fully containerized, reproducible, and ready for container registry publication (<registry-user>/<image-name>).

Portability Roadmap

1. Phase 1 (Edge/PaaS): Edge/serverless frontends, containerized backends, managed/serverless PostgreSQL, container registry.
2. Phase 2 (Cloud Native): Cloud Infrastructure as Code (Terraform, ECS Fargate / EKS, Load Balancers, CloudFront, Container Registry).
3. Phase 3 (Sovereign Infrastructure): Self-Hosted Bare Metal / VPS (Docker Compose / Nomad / K3s, reverse proxy, automated backup sync).

2. Core Directives & Toolchain Standards

[!IMPORTANT] OPTIMAL TOOLCHAIN MANDATE: Always employ the fastest, most deterministic tools:

• Node.js / TypeScript: pnpm exclusively. Never use npm or legacy yarn.
• Python: uv exclusively (ghcr.io/astral-sh/uv:latest). Never use plain pip or slow virtualenv setups.
• Go: Static compilation (CGO_ENABLED=0, -ldflags="-w -s"). Never deploy dynamic glibc-dependent Go binaries.
• Static Frontends (Preact / Svelte / React): Multi-stage pnpm builder with nginx:alpine runner.

Mandatory Container Hardening Rules:

1. Multi-Stage Builds: Build tooling, SDKs, and source compilers MUST NEVER exist in the production runtime stage.
2. Non-Root Execution: Every runtime image MUST define and execute as an unprivileged user (nextjs, appuser, workeruser).
3. Healthcheck Directives: Every service image MUST include an active HEALTHCHECK probing its readiness endpoint.
4. Minimal Attack Surface: Base runtime stages on alpine:3.21, python:3.12-slim, or distroless.
5. Context Efficiency: Every project MUST contain a .dockerignore pruning node_modules, .git, test artifacts, and caches.
6. Automated Container Registry: Every repository SHOULD include a GitHub Actions workflow building and publishing images to a container registry (<registry-user>/<image-name>).

3. Technology Blueprints

Blueprint A: Next.js Standalone (Node 22 + pnpm)

• next.config.ts must set output: "standalone".
• Multi-stage build copies .next/standalone, .next/static, and public.
• Runs as nextjs:nodejs on port 3000.

Blueprint B: Static SPAs (Vite / Preact / Svelte + Nginx)

• Builds static assets to dist/ with pnpm build.
• Deploys into nginx:alpine.
• Custom nginx.conf handles SPA routing fallback (try_files $uri $uri/ /index.html;), gzip compression, and /health.

Blueprint C: Go API / Microservice

• golang:alpine builder with go mod download.
• Static compilation: CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /bin/server ..
• Runtime stage: alpine:3.21 with ca-certificates, tzdata, curl, running as appuser.

Blueprint D: Python AI / API Service (FastAPI + uv)

• Installs uv from ghcr.io/astral-sh/uv:latest.
• uv sync --frozen --no-dev --no-install-project with UV_COMPILE_BYTECODE=1.
• Runtime stage: python:3.12-slim with unprivileged appuser.

4. Verification & Testing Runbook

# 1. Validate Docker daemon is operational
docker info

# 2. Build image locally with Buildx
docker build -t <service-name>:local .

# 3. Test local container execution & healthcheck
docker run -d --name test-<service-name> -p <port>:<port> <service-name>:local
sleep 5
docker ps --filter name=test-<service-name>
curl -f http://localhost:<port>/health || exit 1
docker rm -f test-<service-name>

# 4. Verify Compose environment
docker compose up -d
docker compose ps
docker compose down