Docker Architect

Overview

Produce production-grade, secure, right-sized Docker images and Compose environments end-to-end: inventory → design → implement → test → CI. Prefer minimal, reproducible builds (multi-stage + BuildKit) and least-privilege runtime defaults.

Quick Start (always do this first)

1. Inventory the repo and existing container config:
   • Run

     python3 /home/bjorn/.codex/skills/docker-architect/scripts/docker_inventory.py --root .

2. Choose the target:
   • New containerization → follow “New build workflow”
   • Existing Dockerfiles/Compose → follow “Audit + refactor workflow”
3. Validate locally:

   • docker buildx version

   • docker buildx build ...

     (or

     docker build ...

     )

   • docker compose config

     and

     docker compose up --build

Template rendering example (edit variables per repo):

• python3 /home/bjorn/.codex/skills/docker-architect/scripts/render_template.py --template .dockerignore --out .dockerignore

• python3 /home/bjorn/.codex/skills/docker-architect/scripts/render_template.py --template compose/docker-compose.yml --out docker-compose.yml --var IMAGE_NAME=myapp:dev --var HOST_PORT=8000 --var CONTAINER_PORT=8000

• python3 /home/bjorn/.codex/skills/docker-architect/scripts/render_template.py --template compose/docker-compose.dev.yml --out docker-compose.dev.yml --var CONTAINER_PORT=8000 --var DEV_COMMAND='[\"python\",\"-m\",\"uvicorn\",\"myapp.api:app\",\"--host\",\"0.0.0.0\",\"--port\",\"8000\",\"--reload\"]'

Workflow Decision Tree

1. Scope:
   • Dev-only (fast iteration, source mounts, hot reload) → prefer

     docker-compose.dev.yml

   • Prod-like (immutable images, healthchecks, least privilege) → prefer

     docker-compose.yml

     +

     docker-compose.prod.yml

2. Artifact type:
   • Single service → one Dockerfile + optional compose for deps
   • Multi-service → compose with explicit networks/volumes and healthchecks
3. Publish target:
   • Local only → keep simple; optional CI smoke checks
   • Registry publish → add CI build/test/scan/push + provenance/SBOM (if available)

New build workflow (Dockerfile + .dockerignore + compose)

1. Pick a base strategy (see

   references/dockerfile_patterns.md

   ):
   • Multi-stage build; runtime image is minimal; build tools stay in builder stage.
   • Prefer slim/distroless where feasible; default to non-root user.
2. Add

   .dockerignore

   early (template in

   assets/templates/.dockerignore

   ).
3. Create a Dockerfile from templates:
   • Prefer

     assets/templates/python/Dockerfile.uv

     for modern Python/

     uv

   • Prefer

     assets/templates/node/Dockerfile.pnpm

     for Node + pnpm
   • Use

     python3 /home/bjorn/.codex/skills/docker-architect/scripts/render_template.py ...

     to render with variables.
4. Add a compose file for dependencies (DB/cache) and dev/prod profiles:
   • Start from

     assets/templates/compose/docker-compose.yml

     + an override (

     assets/templates/compose/docker-compose.dev.yml

     or

     assets/templates/compose/docker-compose.prod.yml

     )
   • Optional deps file:

     assets/templates/compose/docker-compose.deps.yml

5. Local validation:

   • bash /home/bjorn/.codex/skills/docker-architect/scripts/smoke_test_container.sh --help

   • Optional:

     --build-check

     (Docker build checks) and

     --pull

     (fresh base images)
   • For compose:

     bash /home/bjorn/.codex/skills/docker-architect/scripts/smoke_test_compose.sh --help

Audit + refactor workflow (existing Dockerfiles/Compose)

1. Inventory + static audit:

   • python3 /home/bjorn/.codex/skills/docker-architect/scripts/docker_audit.py --root .

2. Identify high-risk issues (see

   references/security_hardening.md

   ):
   • Secrets in image/build args, root/privileged runtime, overly broad mounts, host networking, “latest” tags, missing healthchecks.
3. Refactor incrementally:
   • Keep behavior stable, then tighten (non-root, read-only fs, drop caps, pin images, shrink layers).
4. Validate end-to-end:

   • docker buildx build ...

   • docker compose up --build

     and run the app’s normal test/health commands.
5. Produce a concise report (template in

   references/review_template.md

   ).

CI integration workflow (GitHub Actions default)

1. Start from

   assets/templates/ci/github-actions-docker-ci.yml

   .
   • For publish + SBOM/provenance to GHCR:

     assets/templates/ci/github-actions-docker-publish.yml

2. Ensure CI runs:

   • docker buildx build

     (cache enabled)

   • docker compose config

     (compose validation)
   • optional: build checks (

     docker build --check

     ) and scan/SBOM/provenance steps
3. Prefer pinned action versions and least-privilege permissions (see

   references/ci_github_actions.md

   ).

“Latest/correct” research rule (do not guess)

When “latest” matters (base images, distro versions, language runtimes, CVEs):

1. Use Exa to confirm current official guidance and tags (official sources preferred).
2. Use

   docker buildx imagetools inspect <image:tag>

   to confirm manifests/platforms.
3. If unsure, mark as

   UNVERIFIED

   and propose a safe default with a verification step.

Tooling leverage (when it helps)

• Exa: find current best practices, base image changes, CVE guidance, GitHub Actions deprecations.
• Context7: confirm framework-specific build outputs (e.g., Next.js, FastAPI, uvicorn/gunicorn, etc.).
• Zen: use

  zen.secaudit

  for a structured container/security audit and

  zen.analyze

  for architecture-sensitive compose design.
• gh_grep: search public repos for battle-tested patterns (entrypoints, healthchecks, buildx/bake, compose profiles).
• opensrc: inspect dependency internals when container behavior depends on packaging details.

Bundled resources

Scripts

• scripts/docker_inventory.py

  : detect stack + existing Docker/Compose files.

• scripts/docker_audit.py

  : heuristic linting of Dockerfiles/Compose for security/correctness.

• scripts/render_template.py

  : render templates with

  {{VARS}}

  into repo files.

• scripts/smoke_test_container.sh

  : build/run basic health check locally.

• scripts/smoke_test_compose.sh

  : validate + bring up compose and check health.

References (load as needed)

• references/dockerfile_patterns.md

  : BuildKit, caching, multi-stage, runtime hardening.

• references/compose_patterns.md

  : compose patterns, profiles, healthchecks, secrets/configs.

• references/security_hardening.md

  : least privilege, capabilities, read-only fs, supply chain.

• references/ci_github_actions.md

  : CI build/test/scan/publish patterns.

• references/review_template.md

  : audit report format and deliverables checklist.

Assets (templates)

Templates live under

assets/templates/

(Dockerfile variants, compose variants, CI workflow,

.dockerignore

,

docker-bake.hcl

).