Immutable. This exact content is served forever at /api/v1/blob/88e950e73d1e018c.
--- name: docker-first-architecture description: >- Rules, architectures, multi-stage Dockerfile blueprints, and container-first workflows for all microservices, frontends, and backends targeting container registries, AWS ECS/EKS, and self-hosting. --- # 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 ```bash # 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 ```