Docker

Production-grade Docker containerization with security-first defaults.

Resource Detection & Adaptation

Before generating Dockerfiles/Compose, detect the environment:

bash

# 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):

yaml

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

yaml

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

Extended (> 8GB Docker):

yaml

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

Pre-Build Validation

Before running

docker build

, agent should verify:

bash

# 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

bash

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)

dockerfile

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

Graceful Shutdown (FastAPI)

python

@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

dockerfile

# 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)

javascript

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:

dockerfile

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

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

docker

NPX Install

Tags

SKILL.md Content

Docker

Resource Detection & Adaptation

Agent Behavior

Adaptive Compose Templates

Pre-Build Validation

What This Skill Does

What This Skill Does NOT Do

Before Implementation

Required Clarifications

Detect Runtime

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

Python

Node.js

Fix Issues Automatically

Workflow

Base Image Decision Matrix

Stage Structure

Build Commands

Python Patterns

Framework CMD

Cache Mount (uv/pip)

Graceful Shutdown (FastAPI)

Node.js Patterns

Framework Build

Cache Mounts

Graceful Shutdown (Node.js)

Security Checklist

Output Files

Reference Files

Always Read First

Framework-Specific

Optional

Templates (Reference Patterns)