Docker Packaging

Generate Docker configurations following project conventions. Supports multi-stage builds, uv-based Python images, and health checks.

When to Use

• Containerizing a new project
• Optimizing existing Docker images
• Setting up Docker Compose for development
• Adding health checks to containers
• Creating production-ready Docker configurations

Python Project Dockerfile

Multi-stage build with uv for dependency management:

# Stage 1: Build dependencies
FROM python:3.12-slim AS builder

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

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

COPY . .
RUN uv sync --frozen --no-dev

# Stage 2: Runtime
FROM python:3.12-slim AS runtime

RUN addgroup --system app && adduser --system --ingroup app app

COPY --from=builder /app /app
WORKDIR /app
ENV PATH="/app/.venv/bin:$PATH"

USER app
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1

CMD ["python", "-m", "app"]

Key conventions:

• Always multi-stage (build vs runtime)
• Use uv, never pip
• Copy pyproject.toml and uv.lock first for layer caching
• Slim base images
• Non-root user for production
• Health checks included

TypeScript/Bun Project Dockerfile

FROM oven/bun:1 AS builder

WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile

COPY . .
RUN bun run build

FROM oven/bun:1-slim AS runtime

WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

CMD ["bun", "run", "start"]

Go Project Dockerfile

FROM golang:1.22-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server

FROM scratch AS runtime

COPY --from=builder /app/server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

EXPOSE 8080
ENTRYPOINT ["/server"]

Docker Compose (Development)

# docker-compose.yml
services:
  app:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - .:/app
    environment:
      - DEBUG=1
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: dev-only
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 5s
      retries: 5
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

.dockerignore

Always create alongside Dockerfile:

.git
.github
.context
.rules
.claude
__pycache__
*.pyc
.venv
node_modules
.env
*.md
!README.md

Workflow

Step 1: Detect stack and entry point

Identify the application type, main entry point, exposed ports, and any services it depends on.

Step 2: Generate Dockerfile

Use the appropriate template. Add security hardening for production (non-root user, read-only filesystem).

Step 3: Generate .dockerignore

Exclude development files, secrets, and unnecessary build context.

Step 4: Generate docker-compose.yml (if needed)

Add dependent services (databases, caches, message queues) with health checks.

Step 5: Test

docker build -t app:test .
docker run --rm app:test

Additional Resources

• Reference: references/docker-security.md - Non-root users, secrets management, image scanning
• Reference: references/docker-optimization.md - Layer caching, image size reduction, BuildKit