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:

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

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

Error Handling

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

Asset Templates