Docker Rocker Skill | Agent Skills

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:

| Source | Gather | |--------|--------| | Codebase | Project structure, existing Dockerfile, pyproject.toml/requirements.txt, app entry point | | Conversation | Target deployment (dev/staging/prod), database connection requirements, special dependencies | | Skill References | Multi-stage patterns from references/, optimization strategies, security practices | | User Guidelines | Team Docker conventions, registry requirements, CI/CD integration needs |

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:

| Question | Purpose | |----------|---------| | Deployment target? | Dev (hot-reload) vs Production (optimized) vs CI/CD (testing) | | Package manager? | UV (recommended) vs pip vs Poetry | | Database type? | Neon PostgreSQL, local PostgreSQL, SQLite, other | | Special system deps? | Libraries requiring apt packages (Pillow, psycopg2, etc.) | | Port configuration? | Default 80 or custom port |

Docker Deployment Stages

Stage Overview

| Stage | Purpose | Base Image | Final Size | |-------|---------|------------|------------| | Builder | Install dependencies, compile packages | python:3.12-slim | ~400MB (discarded) | | Runtime | Production application | python:3.12-slim | ~150MB | | Testing | CI/CD test execution | extends Builder | ~450MB | | Development | Hot-reload for local dev | python:3.12-slim | ~300MB |

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

| Target | Template | |--------|----------| | Production only | Dockerfile.production | | With testing | Dockerfile.complete | | Development | Dockerfile.dev | | Full multi-stage | 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:

Base image (rarely changes)
System dependencies (rarely changes)
Python dependencies (changes occasionally)
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

| Task | Command | |------|---------| | Build production image | docker build --target runtime -t app:prod . | | Build test image | docker build --target testing -t app:test . | | Run tests in container | docker run --rm app:test pytest -v | | Build with no cache | docker build --no-cache -t app:latest . | | Check image size | docker images app:latest | | Scan for vulnerabilities | docker scout cves app:latest |

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | uv: command not found | UV not installed in image | Add COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv | | ModuleNotFoundError | Dependencies not in runtime | Verify COPY of .venv from builder | | Permission denied | Non-root user can't write | Use --chown=app:app on COPY | | Connection refused to DB | Network isolation | Use docker-compose networks or host.docker.internal | | OOM killed | Container memory limit | Increase memory limit or optimize workers | | Build cache not working | Layer order wrong | Reorder: deps before code |

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

| File | When to Read | |------|--------------| | references/multi-stage-builds.md | Understanding stage architecture and patterns | | references/optimization-strategies.md | Reducing image size and build time | | references/fastapi-patterns.md | FastAPI-specific Docker configurations | | references/security-best-practices.md | Container security hardening | | references/database-connections.md | SQLModel/Neon connection patterns in containers |

Asset Templates

| Template | Use Case | |----------|----------| | assets/templates/Dockerfile.multistage | Complete multi-stage (Builder + Runtime + Testing) | | assets/templates/Dockerfile.production | Production-only optimized build | | assets/templates/Dockerfile.dev | Development with hot-reload | | assets/templates/docker-compose.yml | Full development stack | | assets/templates/docker-compose.prod.yml | Production compose | | assets/templates/.dockerignore | Standard ignore patterns |

Agent Skills: Docker Rocker

Install this agent skill to your local

Skill Files