Docker Rocker

Production-grade Docker automation for Python FastAPI web API projects using multi-stage builds, UV package manager, and performance optimization strategies.

What This Skill Does

• Creates optimized multi-stage Dockerfiles (Builder → Runtime → Testing stages)
• Configures UV package manager for 50-70% faster dependency installation
• Implements layer caching strategies for rapid rebuilds
• Sets up non-root user security configurations
• Generates docker-compose files for development and production
• Optimizes for SQLModel/Neon database connections in containers
• Configures Pydantic settings for container environments

What This Skill Does NOT Do

• Manage Kubernetes deployments (use dedicated k8s skills)
• Handle cloud-specific container registries (AWS ECR, GCR, ACR)
• Configure reverse proxies (Nginx, Traefik)
• Manage container orchestration at scale
• Handle secrets management beyond environment variables

Before Implementation

Gather context to ensure successful implementation:

references/

Ensure all required context is gathered before implementing. Only ask user for THEIR specific requirements (domain expertise is in this skill).

Required Clarifications

Ask about USER's context before generating Dockerfiles:

Docker Deployment Stages

Stage Overview

Stage Selection Logic

What is the deployment target?

Production deployment?
  → Use Builder + Runtime stages
  → Minimal image, no dev dependencies

CI/CD pipeline?
  → Use Builder + Testing stage
  → Include pytest, dev dependencies

Local development?
  → Use Development stage
  → Volume mounts, hot-reload enabled

All of the above?
  → Generate complete multi-stage Dockerfile with all targets

Workflow

1. Analyze Project Structure

# Check for existing configurations
ls -la pyproject.toml uv.lock requirements*.txt Dockerfile docker-compose.yml

Identify:

• Package manager (UV if uv.lock exists, Poetry if poetry.lock, pip otherwise)
• Entry point (app/main.py, src/main.py, main.py)
• Dependencies requiring system packages

2. Select Dockerfile Template

Based on user's deployment target, use appropriate template from

assets/templates/

Dockerfile.production

Dockerfile.complete

Dockerfile.dev

Dockerfile.multistage

3. Configure Environment Variables

# Performance optimizations
ENV UV_LINK_MODE=copy \
    UV_COMPILE_BYTECODE=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# Application settings
ENV APP_MODULE=app.main:app \
    PORT=80

4. Optimize Layer Caching

Order Dockerfile instructions by change frequency:

1. Base image (rarely changes)
2. System dependencies (rarely changes)
3. Python dependencies (changes occasionally)
4. Application code (changes frequently)

5. Configure Database Connections

For Neon/PostgreSQL in containers:

# Use NullPool - let external pooler handle connections
from sqlalchemy.pool import NullPool

engine = create_async_engine(
    DATABASE_URL,
    poolclass=NullPool,
    pool_pre_ping=True,
)

6. Generate docker-compose

Create appropriate compose file for target environment.

7. Validate Build

# Build and verify
docker build --target runtime -t app:latest .
docker run --rm app:latest python -c "import app; print('OK')"

Quick Commands

docker build --target runtime -t app:prod .

docker build --target testing -t app:test .

docker run --rm app:test pytest -v

docker build --no-cache -t app:latest .

docker images app:latest

docker scout cves app:latest

Error Handling

uv: command not found

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

ModuleNotFoundError

Permission denied

--chown=app:app

Connection refused

OOM killed

Output Checklist

Before delivering Dockerfile, verify:

• Multi-stage build separates builder and runtime
• UV cache mounts configured for fast rebuilds

• UV_COMPILE_BYTECODE=1

  set for startup speed
• Non-root user created and used

• .dockerignore

  includes .venv, pycache, .git
• Layer order optimized (deps before code)
• Health check configured

• --proxy-headers

  flag for FastAPI behind load balancer
• Database connection uses NullPool for external pooling
• Secrets not hardcoded (use environment variables)

Reference Files

references/multi-stage-builds.md

references/optimization-strategies.md

references/fastapi-patterns.md

references/security-best-practices.md

references/database-connections.md

Asset Templates

assets/templates/Dockerfile.multistage

assets/templates/Dockerfile.production

assets/templates/Dockerfile.dev

assets/templates/docker-compose.yml

assets/templates/docker-compose.prod.yml

assets/templates/.dockerignore