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

• Detect Docker resources before generating compose.yaml

• Adapt resource limits to available memory

• Warn if build may fail due to insufficient resources

• 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:

• Read template to understand structure

• Customize paths, CMDs, and stages for actual project

• Generate Dockerfile with correct entrypoint (e.g., src.app.main:app )

• 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", ...]