dockerfile-backend

Files (4)

• SKILL.md
• backend-dockerfile-anatomy.md · references/
• repo-evidence.md · references/
• system-deps-and-caching.md · references/

SKILL.md (first lines)

# Dockerfile for Python Backend Services

Multi-stage Dockerfile patterns for Python/FastAPI backend services, covering base image selection, system dependencies, layer caching, security hardening, and multi-mode entrypoints.

## When to use

- Containerizing Python backend services (FastAPI, Flask, Django)
- Optimizing Docker build times through effective layer caching
- Minimizing production image sizes with multi-stage builds
- Installing system dependencies for Kafka clients, PostgreSQL, or Kerberos authentication
- Implementing secure container images with non-root users
- Setting up multi-mode entrypoints (server/consumer/worker/cron from one image)
- Debugging production Dockerfile build failures or runtime issues

## Core conventions

### Base Image Selection: Slim vs Alpine

**Python slim (Debian-based)**: Use `python:3.11-slim` or `python:3.12-slim` for broader compatibility with compiled extensions (psycopg2, cryptography, numpy). Larger base (~150MB) but fewer build issues.

**Python alpine**: Use `python:3.10-alpine3.20` or `python:3.11-alpine` for minimal footprint (~50MB). Requires more build dependencies (g++, musl-dev, libffi-dev) and may have compatibility issues with some wheels.

**Recommendation**: Start with slim for faster development; switch to alpine only if image size is critical and you've verified all dependencies build correctly.

### Multi-Stage Builds: Builder + Runtime

**Builder stage**: Install all build tools, compile dependencies, create virtual environment. This stage can be large.

**Runtime stage**: Copy only the compiled venv and application code. Install minimal runtime-only dependencies.

**Why**: Keeps the final image small by excluding build tools (gcc, g++, git, build-essential) that are only needed during pip install.

**Key pattern**: Use `COPY --from=builder /opt/venv /opt/venv` to transfer the virtual environment from builder to runtime.

### System Dependencies for Python Backend Stacks

**PostgreSQL client**:
- Slim: `libpq-dev` (build), `libpq5` (runtime)
- Alpine: `postgresql-dev` (build), `libpq` (runtime)

**Kafka (confluent-kafka, kafka-python with librdkafka)**:
- Slim: `librdkafka-dev` (build + runtime), plus `libssl-dev zlib1g-dev liblz4-dev libzstd-dev` for compression
- Alpine: `librdkafka-dev` (build + runtime)

**Kerberos (for GSSAPI/Kafka SASL_GSSAPI)**:
- Slim: `libkrb5-dev krb5-user` (build), `krb5-user` (runtime)
- Alpine: `krb5-dev` (build), `krb5-libs` (runtime)

**Common build dependencies**:
- Slim: `build-essential gcc g++ make python3-dev libffi-dev libssl-dev pkg-config`
- Alpine: `gcc g++ make musl-dev libffi-dev openssl-dev`

**Always clean up**: `rm -rf /var/lib/apt/lists/*` (slim) or `rm -rf /var/cache/apk/*` (alpine) after installing to reduce layer size.

### Dependency Caching and Layer Optimization

**Copy dependency manifest FIRST**: `COPY requirements.txt .` or `COPY pyproject.toml .` before `COPY . .`. Docker caches layers; if only application code changes, dependencies won't reinstall.

**For requirements.txt projects**:
```dockerfile
COPY requirements/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
```

**For pyproject.toml projects**:
```dockerfile
COPY pyproject.toml .
RUN pip install --no-cache-dir ".[prod]"
COPY . .
```

**For Poetry projects**:
```dockerfile
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-dev --no-root
COPY . .
RUN poetry install --no-dev  # Install the project itself
```

**Use `--no-cache-dir`**: Skips pip's download cache, reducing image size by ~100-200MB.

### Virtual Environments in Docker

**Builder pattern**: Create venv in `/opt/venv`, activate it in builder, then copy to runtime stage.

**Why use venv in Docker**: Isolates dependencies from system Python; makes COPY from builder to runtime stage clean.

**Activation pattern**:
```dockerfile
RUN python -m venv /opt/venv
ENV VIRTUAL_ENV=/opt/venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
```

**Alternative**: Skip venv and install directly to system Python if using single-stage builds for simpler services.

### Security Hardening

**Non-root user**: Create and use a non-root user for running the application (especially important for k8s/Cloud Run production deployments).

**Remove .git directory**: After capturing commit SHA for versioning, remove .git to avoid leaking history/secrets: `RUN git rev-parse HEAD > gitsha && rm -rf .git`

**Set `PYTHONUNBUFFERED=1`**: Forces Python stdout/stderr to be unbuffered; critical for seeing logs in Docker/k8s.

**Set `PYTHONDONTWRITEBYTECODE=1`**: Prevents Python from writing .pyc files, reducing image size and avoiding permission issues.

**Use specific image tags**: Never use `:latest` in production; pin to `python:3.11-slim-bookworm` or `python:3.10.15-alpine3.20`.

### Multi-Mode Entrypoint Pattern

**Single image, multiple roles**: Use `entrypoint.py` that reads `MODE` env var and dispatches to different main functions (server, consumer, worker, cron).

**Why**: Deploy the same Docker image to multiple services by varying only env vars; simplifies CI/CD (one build, many deploys).

**Standard modes**: `server` → FastAPI/uvicorn/gunicorn, `consumer` → Kafka consumer, `worker` or `temporal_worker` → background task worker, `cron` → scheduled job.

**See the broader containerization-and-deployment skill for full entrypoint.py patterns.**

From ajyadav013/claude-kit, MIT.

More from ajyadav013/claude-kit