docker

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

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

```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.

---

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

• 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

---

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 |

---

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?" |

---

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

---

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 |

---

```

1. SCAN PROJECT

- Detect runtime, framework, version, entrypoint

- Find dependency files, native deps

- Locate existing Docker files (don't blindly overwrite)

↓

1. ANALYZE ENVIRONMENT

- Scan all .env* files

- Classify: SECRET (never bake) / BUILD_ARG / RUNTIME

- Flag security issues

↓

1. FIX CONFIGURATION

- Add Next.js output: 'standalone' if missing

- Create health endpoints if missing

- Generate .env.example with safe placeholders

↓

1. GENERATE FILES

- Dockerfile (customized CMD, paths, build deps)

- .dockerignore (excludes .env, secrets)

- compose.yaml (with security defaults)

↓

1. 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

↓

1. 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)

---

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

---

```

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 .

```

---

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

```

---

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

});

```

---

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

---

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

---

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

```dockerfile

# Template says:

CMD ["uvicorn", "app.main:app", ...]

# Agent detects app at src/api/main.py, generates:

CMD ["uvicorn", "src.api.main:app", ...]

```