Docker

Production-grade Docker containerization with security-first defaults.

---

Resource Detection & Adaptation

Before generating Dockerfiles/Compose, detect the environment:

# Detect host machine memory
sysctl -n hw.memsize 2>/dev/null | awk '{print $0/1024/1024/1024 " GB"}' || \
  grep MemTotal /proc/meminfo | awk '{print $2/1024/1024 " GB"}'

# Detect Docker allocated resources
docker info --format 'Memory: {{.MemTotal}}, CPUs: {{.NCPU}}'

# Detect available disk space
docker system df

Adapt configurations based on detection:

Detected Docker Memory	Profile	Build Memory	Container Limits
< 4GB	Constrained	1GB	256Mi
4-8GB	Minimal	2GB	512Mi
8-12GB	Standard	4GB	1Gi
> 12GB	Extended	8GB	2Gi

Agent Behavior

1. Detect Docker resources before generating compose.yaml
2. Adapt resource limits to available memory
3. Warn if build may fail due to insufficient resources
4. Calculate safe limits: docker_memory * 0.6 / container_count

Adaptive Compose Templates

Constrained (< 4GB Docker):

services:
  app:
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: '0.25'
    build:
      args:
        - BUILDKIT_STEP_LOG_MAX_SIZE=10000000

⚠️ Agent should warn: "Docker memory low. Multi-stage builds may fail."

Standard (4-8GB Docker):

services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
        reservations:
          memory: 256M

Extended (> 8GB Docker):

services:
  app:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'
        reservations:
          memory: 512M

Pre-Build Validation

Before running docker build, agent should verify:

# Check available memory
docker info --format '{{.MemTotal}}' | awk '{if ($1 < 4000000000) print "WARNING: Low memory"}'

If constrained: use --memory flag and warn user about potential build failures.

---

What This Skill Does

Analysis & Detection:

• Auto-detects runtime, framework, version, entrypoint (no questions)
• Scans .env files, classifies secrets vs build-args vs runtime config
• Detects native dependencies, generates correct build deps
• Identifies missing configs (Next.js standalone, health endpoints)

Generation:

• Creates multi-stage Dockerfiles customized to YOUR project structure
• Generates compose.yaml with security defaults (non-root, read-only, resource limits)
• Adds health endpoints if missing
• Fixes configuration issues (adds output: 'standalone' to Next.js, etc.)

Validation:

• Builds both dev and production targets before delivering
• Verifies health endpoints work
• Confirms non-root user in production
• Warns about any secrets that would leak into image
• Reports image size

Security:

• Never bakes secrets into images
• Non-root user by default
• Minimal attack surface (multi-stage builds)
• Pinned versions (no :latest)
• Security scan command included

What This Skill Does NOT Do

• Generate Kubernetes manifests (use dedicated k8s skill)
• Create Helm charts (use dedicated helm skill)
• Handle Bun/Deno (use dedicated skills)
• Copy templates blindly without customization

---

Before Implementation

Gather context to ensure successful implementation:

Source	Gather
Codebase	Package files, existing Dockerfile, .env patterns
Conversation	Dev vs production target, base image preferences
Skill References	Framework patterns, multi-stage builds, security
User Guidelines	Registry conventions, naming standards

---

Required Clarifications

Ask when not auto-detectable:

Question	When to Ask
Target environment	"Building for development or production?"
Base image preference	"Standard slim images or enterprise hardened?"
Existing Docker files	"Enhance existing Dockerfile or create new?"
Registry target	"Local only or pushing to registry?"

---

Detect Runtime

File Present	Runtime	Package Manager
requirements.txt, pyproject.toml, uv.lock	Python	pip/uv
pnpm-lock.yaml	Node.js	pnpm
yarn.lock	Node.js	yarn
package-lock.json	Node.js	npm

---

Auto-Detection (Do NOT ask - detect from files)

Python

What	Detect From
Python version	pyproject.toml (requires-python), .python-version, runtime.txt
Framework	Imports in code (from fastapi, from flask, import django)
Package manager	uv.lock → uv, poetry.lock → poetry, else pip
Native deps	Scan requirements: psycopg2, cryptography, numpy, pillow
App entrypoint	Find app = FastAPI(), app = Flask(), or manage.py

Node.js

What	Detect From
Node version	.nvmrc, .node-version, package.json (engines.node)
Framework	package.json dependencies (next, express, @nestjs/core)
Package manager	pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm
Output type	Next.js: check next.config.js for output: 'standalone'

Fix Issues Automatically

Issue	Action
Next.js missing output: 'standalone'	Add it to next.config.js
No health endpoint found	Create /health/live and /health/ready
Using uv but no uv.lock	Run uv lock first
pyproject.toml but no build system	Use uv pip install -r pyproject.toml

---

Workflow

1. SCAN PROJECT
   - Detect runtime, framework, version, entrypoint
   - Find dependency files, native deps
   - Locate existing Docker files (don't blindly overwrite)
         ↓
2. ANALYZE ENVIRONMENT
   - Scan all .env* files
   - Classify: SECRET (never bake) / BUILD_ARG / RUNTIME
   - Flag security issues
         ↓
3. FIX CONFIGURATION
   - Add Next.js `output: 'standalone'` if missing
   - Create health endpoints if missing
   - Generate .env.example with safe placeholders
         ↓
4. GENERATE FILES
   - Dockerfile (customized CMD, paths, build deps)
   - .dockerignore (excludes .env, secrets)
   - compose.yaml (with security defaults)
         ↓
5. VALIDATE & TEST
   - docker build --target dev -t app:dev .
   - docker build --target production -t app:prod .
   - Test health endpoints
   - Verify non-root user
   - Report image size
         ↓
6. DELIVER WITH CONTEXT
   - All files with explanations
   - Security scan command
   - Any warnings about secrets
   - Rollback instructions if replacing existing

Only ask if genuinely ambiguous (e.g., multiple apps in monorepo, conflicting configs)

---

Base Image Decision Matrix

Choice	When to Use	Tradeoffs
Slim {runtime}:X-slim	General production (default)	Works everywhere, no auth
DHI dhi.io/{runtime}:X	SOC2/HIPAA, enterprise	Requires docker login dhi.io
Alpine {runtime}:X-alpine	Smallest size	musl issues with native deps

Default: Slim (works everywhere without authentication)

---

Stage Structure

deps/base  → Install dependencies (cached layer)
    ↓
builder    → Build/compile application
    ↓
dev        → Hot-reload, volume mounts (--target dev)
    ↓
production → Minimal DHI runtime (--target production)

Build Commands

docker build --target dev -t myapp:dev .
docker build --target production -t myapp:prod .

---

Python Patterns

Framework CMD

Framework	Development	Production
FastAPI	uvicorn app.main:app --reload	uvicorn app.main:app --workers 4
Flask	flask run --debug	gunicorn -w 4 app:app
Django	python manage.py runserver	gunicorn -w 4 project.wsgi

Cache Mount (uv/pip)

RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=cache,target=/root/.cache/pip \
    uv pip install -r requirements.txt

Graceful Shutdown (FastAPI)

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield  # startup
    # shutdown logic here

---

Node.js Patterns

Framework Build

Framework	Build	Output
Next.js	next build	.next/standalone
Express	tsc	dist/
NestJS	nest build	dist/

Cache Mounts

# pnpm
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
    pnpm install --frozen-lockfile

# npm
RUN --mount=type=cache,target=/root/.npm npm ci

# yarn
RUN --mount=type=cache,target=/usr/local/share/.cache/yarn \
    yarn install --frozen-lockfile

Graceful Shutdown (Node.js)

process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
});

---

Security Checklist

Before delivering, verify:

• Non-root USER in production stage
• No secrets in Dockerfile or image layers
• .dockerignore excludes .env, .git, secrets
• Multi-stage separates build tools from runtime
• DHI or hardened base image used
• HEALTHCHECK instruction defined
• No package install in production stage
• Secrets via runtime env vars or mounted files

---

Output Files

File	Purpose
Dockerfile	Multi-stage, multi-target build
.dockerignore	Exclude sensitive/unnecessary files
compose.yaml	Local development stack
health.py / health endpoint	Framework-specific health checks

---

Reference Files

Always Read First

File	Purpose
references/env-analysis.md	CRITICAL: Secret detection, .env classification
references/production-checklist.md	CRITICAL: Validation before delivery

Framework-Specific

File	When to Read
references/python/fastapi.md	FastAPI: uvicorn, lifespan
references/python/flask.md	Flask: gunicorn, blueprints
references/python/django.md	Django: gunicorn, middleware
references/python/native-deps.md	Detect psycopg2, cryptography, etc.
references/node/nextjs.md	Next.js: standalone, ISR
references/node/package-managers.md	npm/yarn/pnpm caching

Optional

File	When to Read
references/docker-hardened-images.md	If user needs enterprise security (DHI)
references/multi-stage-builds.md	Complex build patterns

Templates (Reference Patterns)

Templates in templates/ are reference patterns, not copy-paste files.

Agent must:

1. Read template to understand structure
2. Customize paths, CMDs, and stages for actual project
3. Generate Dockerfile with correct entrypoint (e.g., src.app.main:app)
4. Never output placeholder comments like "# Replace based on framework"

Example customization:

# Template says:
CMD ["uvicorn", "app.main:app", ...]

# Agent detects app at src/api/main.py, generates:
CMD ["uvicorn", "src.api.main:app", ...]