configure-dockerfile

---
name: configure-dockerfile
description: Dockerfile standards: Alpine/slim base, non-root user, multi-stage builds. Use when creating a Dockerfile, hardening security, or auditing image size.
license: MIT
---

# /configure:dockerfile

Check and configure Dockerfile against project standards with emphasis on **minimal images**, **non-root users**, and **multi-stage builds**.

## When to Use This Skill

| Use this skill when... | Use another approach when... |
|------------------------|------------------------------|
| Checking Dockerfile compliance with standards | Just viewing Dockerfile (use Read tool) |
| Creating Dockerfile from template | Dockerfile already follows all standards |
| Validating image size, security, multi-stage builds | Need container runtime config (use `/configure:container`) |
| Setting up minimal Alpine/slim-based images | Project uses specialized base images (custom requirements) |
| Ensuring non-root user configuration | Debugging container issues (check logs, inspect runtime) |

## Context

- Dockerfiles: !`find . -maxdepth 1 \( -name 'Dockerfile' -o -name 'Dockerfile.*' -o -name '*.Dockerfile' \)`
- Dockerignore: !`find . -maxdepth 1 -name \'.dockerignore\'`
- Project type: !`find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \) -print -quit`
- Base images: !`find . -maxdepth 1 \( -name 'Dockerfile' -o -name 'Dockerfile.*' -o -name '*.Dockerfile' \) -exec grep -hm5 '^FROM' {} +`

## Parameters

Parse from command arguments:

- `--check-only`: Report compliance status without modifications
- `--fix`: Apply fixes automatically without prompting
- `--type <type>`: Override project type detection (frontend, python, go, rust)

## Execution

Execute this Dockerfile compliance check:

### Step 1: Detect project type and Dockerfiles

1. Find Dockerfile(s) in project root
2. Detect project type from context (package.json, pyproject.toml, go.mod, Cargo.toml)
3. Parse Dockerfile to analyze current configuration
4. Apply `--type` override if provided

### Step 2: Verify latest base image versions

Before flagging outdated base images, use WebSearch or WebFetch to verify latest versions:

1. **Node.js Alpine**: Check Docker Hub for latest LTS Alpine tags
2. **Python slim**: Check Docker Hub for latest slim tags
3. **nginx Alpine**: Check Docker Hub for latest Alpine tags
4. **Go Alpine**: Check Docker Hub for latest Alpine tags
5. **Rust Alpine**: Check Docker Hub for latest Alpine tags

### Step 3: Analyze compliance

Check the Dockerfile against these standards:

**Frontend (Node.js) Standards:**

| Check | Standard | Severity |
|-------|----------|----------|
| Build base | `node:24-alpine` (LTS) | WARN if other |
| Runtime base | `nginx:1.30-alpine` | WARN if other |
| Multi-stage | Required | FAIL if missing |
| HEALTHCHECK | Required | FAIL if missing |
| Non-root user | Required | FAIL if missing |
| Build caching | `--mount=type=cache` recommended | INFO |
| OCI Labels | Required for GHCR integration | WARN if missing |

**Python Service Standards:**

| Check | Standard | Severity |
|-------|----------|----------|
| Base image | `python:3.14-slim` | WARN if other |
| Multi-stage | Required for production | FAIL if missing |
| HEALTHCHECK | Required | FAIL if missing |
| Non-root user | Required | FAIL if missing |
| OCI Labels | Required for GHCR integration | WARN if missing |

**OCI Container Labels:**

| Label | Purpose | Severity |
|-------|---------|----------|
| `org.opencontainers.image.source` | Links to repository | WARN if missing |
| `org.opencontainers.image.description` | Package description | WARN if missing |
| `org.opencontainers.image.licenses` | SPDX license identifier | WARN if missing |
| `org.opencontainers.image.version` | Semantic version (via ARG) | INFO if missing |
| `org.opencontainers.image.revision` | Git commit SHA (via ARG) | INFO if missing |

### Step 4: Report results

Print a compliance report:

```
Dockerfile Compliance Report
================================
Project Type: <type> (detected)
Dockerfile: ./Dockerfile (found)

Configuration Checks:
  Build base      <image>           [PASS|WARN]
  Runtime base    <image>           [PASS|WARN]
  Multi-stage     <N> stages        [PASS|FAIL]
  HEALTHCHECK     <present|missing> [PASS|FAIL]
  Non-root user   <present|missing> [PASS|FAIL]
  Build caching   <enabled|missing> [PASS|INFO]

OCI Labels Checks:
  image.source       <present|missing> [PASS|WARN]
  image.description  <present|missing> [PASS|WARN]
  image.licenses     <present|missing> [PASS|WARN]

Recommendations:
  <list specific fixes needed>
```

If `--check-only`, stop here.

### Step 5: Apply fixes (if requested)

If `--fix` flag is set or user confirms:

1. **Missing Dockerfile**: Create from standard template (see Standard Templates below)
2. **Missing HEALTHCHECK**: Add standard healthcheck
3. **Missing multi-stage**: Suggest restructure (manual fix needed)
4. **Outdated base images**: Update FROM lines
5. **Missing OCI labels**: Add LABEL instructions

### Step 6: Update standards tracking

Update `.project-standards.yaml`:

```yaml
components:
  dockerfile: "2025.1"
```

## Standard Templates

### Frontend (Node/Vite/nginx)

```dockerfile
FROM node:24-alpine AS build

ARG SENTRY_AUTH_TOKEN
ARG VITE_SENTRY_DSN

WORKDIR /app

COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm npm ci

COPY . .
RUN --mount=type=cache,target=/root/.npm \
    --mount=type=cache,target=/app/node_modules/.vite \
    npm run build

FROM nginx:1.30-alpine

# OCI labels for GHCR integration
LABEL org.opencontainers.image.source="https://github.com/OWNER/REPO" \
      org.opencontainers.image.description="Production frontend application" \
      org.opencontainers.image.licenses="MIT" \
      org.opencontainers.image.vendor="Your Organization"

# Dynamic labels via build args
ARG VERSION=dev
ARG BUILD_DATE
ARG VCS_REF
LABEL org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.created="${BUILD_DATE}" \
      org.opencontainers.image.revision="${VCS_REF}"

COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx/default.conf.template /etc/nginx/templates/

EXPOSE 80

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost/health || exit 1
```

### Python Service

```dockerfile
FROM python:3.14-slim AS builder

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen --no-dev

FROM python:3.14-slim

# OCI labels for GHCR integration
LABEL org.opencontainers.image.source="https://github.com/OWNER/REPO" \
      org.opencontainers.image.description="Production Python API server" \
      org.opencontainers.image.licenses="MIT" \
      org.opencontainers.image.vendor="Your Organization"

ARG VERSION=dev
ARG BUILD_DATE
ARG VCS_REF
LABEL org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.created="${BUILD_DATE}" \
      org.opencontainers.image.revision="${VCS_REF}"

RUN useradd --create-home appuser
USER appuser
WORKDIR /app

COPY --from=builder /app/.venv /app/.venv
COPY --chown=appuser:appuser . .

ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Check Dockerfile exists | `find . -maxdepth 1 \( -name 'Dockerfile' -o -name 'Dockerfile.*' \) 2>/dev/null` |
| Validate multi-stage build | `grep -c '^FROM' Dockerfile 2>/dev/null` |
| Check for non-root user | `grep -E '^USER [^root]' Dockerfile 2>/dev/null` |
| Check base image | `grep '^FROM' Dockerfile \| head -1` |
| Quick compliance check | `/configure:dockerfile --check-only` |
| Auto-fix issues | `/configure:dockerfile --fix` |

## Flags

| Flag | Description |
|------|-------------|
| `--check-only` | Report status without offering fixes |
| `--fix` | Apply fixes automatically |
| `--type <type>` | Override project type (frontend, python) |

## Notes

- Node 24 is current Active LTS (Node 22 in maintenance)
- nginx:1.30-alpine preferred over debian variant
- HEALTHCHECK is critical for Kubernetes liveness probes
- Build caching significantly improves CI/CD speed
- Non-root user is mandatory for production containers

## See Also

- `/configure:container` - Comprehensive container infrastructure
- `/configure:skaffold` - Kubernetes development configuration
- `/configure:all` - Run all compliance checks
- `container-development` skill - Container best practices