Skip to content
Skills Library
DevOps & cloud · Building & coding

dockerfile-backend

/dockerfile-backend

Multi-stage Dockerfiles for Python/FastAPI backends — builder vs runtime, slim vs alpine, system deps, layer caching, non-root users. Use when containerizing or optimizing Python backend images.

Repository
claude-kit ↗
Licence
MIT
Last repository change
07.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 07.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Multi-stage Dockerfiles for Python/FastAPI backends — builder vs runtime, slim vs alpine, system deps, layer caching, non-root users. Use when containerizing or optimizing Python backend images.

Original author description

Multi-stage Dockerfiles for Python/FastAPI backends — builder vs runtime, slim vs alpine, system deps, layer caching, non-root users. Use when containerizing or optimizing Python backend images.

How it works

  1. When to use
  2. Core conventions
  3. Skeleton / example
  4. Anti-patterns to avoid
  5. References
Original SKILL.md headings · 363 lines, 1,539 words
SKILL.md preview
---
name: dockerfile-backend
description: Multi-stage Dockerfiles for Python/FastAPI backends — builder vs runtime, slim vs alpine, system deps, layer caching, non-root users. Use when containerizing or optimizing Python backend images.
---

# 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.**

### Gunicorn + Uvicorn for FastAPI

**Production pattern**: Use gunicorn with uvicorn workers (ASGI support).

**Example CMD**:
```dockerfile
CMD ["gunicorn", "app.main:app", \
     "--worker-class", "uvicorn.workers.UvicornWorker", \
     "--workers", "4", \
     "--bind", "0.0.0.0:8000", \
     "--timeout", "120", \
     "--graceful-timeout", "30", \
     "--access-logfile", "-"]
```

**For entrypoint.py pattern**: Use `ENTRYPOINT ["python", "entrypoint.py"]` instead of CMD.

### Health Checks

**Add HEALTHCHECK to Dockerfile** (optional but recommended for k8s/ECS):
```dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl --fail http://localhost:8000/health || exit 1
```

**Install curl in runtime stage**: `apt-get install -y curl` (slim) or `apk add curl` (alpine).

**Alternative**: Use k8s liveness/readiness probes instead of Dockerfile HEALTHCHECK.

## Skeleton / example

### Multi-Stage Slim Dockerfile (PostgreSQL + Kafka + Kerberos)

```dockerfile
ARG PYTHON_VERSION=3.11-slim-bookworm

# Builder stage
FROM python:$PYTHON_VERSION AS builder

ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

# Install build dependencies
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        build-essential \
        gcc \
        g++ \
        make \
        python3-dev \
        libpq-dev \
        librdkafka-dev \
        libkrb5-dev \
        libffi-dev \
        libssl-dev \
        pkg-config \
        zlib1g-dev \
        liblz4-dev \
        libzstd-dev \
        git \
        curl && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /srv/app

# Copy dependency manifest first for layer caching
COPY requirements/requirements.txt .

# Create and activate virtual environment
RUN python -m venv /opt/venv
ENV VIRTUAL_ENV=/opt/venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

# Install dependencies
RUN pip install --upgrade --no-cache-dir pip wheel setuptools && \
    pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Capture git SHA and remove .git for security
RUN git rev-parse HEAD > gitsha && rm -rf .git

# Runtime stage
FROM python:$PYTHON_VERSION

ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

# Install runtime-only dependencies
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        libpq5 \
        librdkafka-dev \
        krb5-user \
        postgresql-client \
        vim \
        curl && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /srv/app

# Copy virtual environment and application from builder
COPY --from=builder /srv/app .
COPY --from=builder /opt/venv /opt/venv

ENV VIRTUAL_ENV=/opt/venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

# Create non-root user (optional but recommended)
RUN groupadd --gid 1000 appuser && \
    useradd --uid 1000 --gid appuser --shell /bin/bash --create-home appuser && \
    mkdir -p /var/log/app && \
    chown -R appuser:appuser /srv/app /var/log/app

USER appuser

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl --fail http://localhost:8000/health || exit 1

ENTRYPOINT ["python", "entrypoint.py"]
```

### Multi-Stage Alpine Dockerfile (Minimal Footprint)

```dockerfile
ARG PYTHON_VERSION=3.10.15-alpine3.20

# Builder stage
FROM python:${PYTHON_VERSION} AS builder

ENV PYTHONUNBUFFERED=1

RUN apk update && apk upgrade && \
    apk add --no-cache \
        curl \
        git \
        gcc \
        g++ \
        musl-dev \
        libffi-dev \
        openssl-dev \
        librdkafka-dev \
        postgresql-dev && \
    rm -rf /var/cache/apk/*

WORKDIR /srv/app

COPY ./requirements/requirements.txt .

# Create virtual environment
RUN python -m venv /opt/venv
ENV VIRTUAL_ENV=/opt/venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

RUN pip install --upgrade --no-cache-dir pip wheel setuptools && \
    pip install --no-cache-dir -r requirements.txt

COPY . .
RUN git rev-parse HEAD > gitsha && rm -rf .git

# Runtime stage
FROM python:${PYTHON_VERSION}

ENV PYTHONUNBUFFERED=1

RUN apk update && apk upgrade && \
    apk add --no-cache \
        vim \
        librdkafka-dev \
        libpq \
        curl && \
    rm -rf /var/cache/apk/*

WORKDIR /srv/app
COPY --from=builder /srv/app .
COPY --from=builder /opt/venv /opt/venv

ENV VIRTUAL_ENV=/opt/venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

EXPOSE 80

RUN mkdir -p /var/log/app && chmod 777 /var/log/app

ENTRYPOINT ["python", "entrypoint.py"]
```

### Single-Stage Slim Dockerfile (Simpler Services)

```dockerfile
FROM python:3.12-slim

ENV PYTHONUNBUFFERED=1

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    libpq-dev && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Copy dependency manifest first
COPY pyproject.toml .
RUN pip install --no-cache-dir ".[prod]"

# Copy application code
COPY . .
ENV PYTHONPATH=/app

EXPOSE 8000

CMD ["gunicorn", "app.main:app", \
     "--worker-class", "uvicorn.workers.UvicornWorker", \
     "--workers", "4", \
     "--bind", "0.0.0.0:8000", \
     "--timeout", "120", \
     "--graceful-timeout", "30", \
     "--access-logfile", "-"]
```

## Anti-patterns to avoid

- **Installing build tools in the runtime stage** — use multi-stage builds; only runtime deps in the final stage (e.g., `libpq5` not `libpq-dev`).
- **Copying application code before dependencies** — breaks Docker layer caching; copy `requirements.txt` or `pyproject.toml` first, install, then copy code.
- **Not cleaning up package manager caches** — always `rm -rf /var/lib/apt/lists/*` (slim) or `rm -rf /var/cache/apk/*` (alpine) after `apt-get install` or `apk add`.
- **Using `:latest` tags in production** — pin to specific Python version tags like `3.11-slim-bookworm` or `3.10.15-alpine3.20`.
- **Forgetting `PYTHONUNBUFFERED=1`** — logs buffer in Docker; set this env var for immediate stdout/stderr output.
- **Not using `--no-cache-dir` with pip** — leaves ~100-200MB of pip cache in the image; always use `pip install --no-cache-dir`.
- **Running as root in production** — create a non-root user (especially important for k8s security policies).
- **Hardcoding secrets or credentials in Dockerfile** — always use env vars or secret managers; never `ENV API_KEY=<secret>` or `ARG` for runtime secrets.
- **Installing unnecessary packages** — audit your runtime stage; remove vim/curl/git if not needed (except for debugging images).
- **Not separating dev and prod requirements** — use `requirements/requirements.txt` for prod, `requirements/dev-requirements.txt` for local dev; never install pytest/black/mypy in production images.

## References

- [backend-dockerfile-anatomy.md](./references/backend-dockerfile-anatomy.md) — Detailed breakdown of each Dockerfile layer and why it's structured that way
- [system-deps-and-caching.md](./references/system-deps-and-caching.md) — System dependency patterns for Kafka, PostgreSQL, Kerberos; layer caching strategies
- [repo-evidence.md](./references/repo-evidence.md) — Real-world Dockerfile patterns from production services (genericized)
- [containerization-and-deployment skill](../containerization-and-deployment/SKILL.md) — Broader context: entrypoint.py MODE dispatch, docker-compose, Cloud Run deployment, secrets handling
Files in this package (4)
  • SKILL.md 13 KB
  • references/backend-dockerfile-anatomy.md 14 KB
  • references/repo-evidence.md 11 KB
  • references/system-deps-and-caching.md 11 KB

Versions

The database has no other skills named dockerfile-backend.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 0a14a7e20c98 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100configure-dockerfile
    Dockerfile standards: Alpine/slim base, non-root user, multi-stage builds. Use when creating a Dockerfile, hardening security, or auditing image size.
  • 90container-development
    Container development — Docker, multi-stage builds, Skaffold, non-root users, Alpine/slim images, security hardening. Use when working with Docker, Dockerfiles, docker-compose, or container security.
  • 100dockerfile-patterns
    Use when the user asks about writing, optimizing, or debugging Dockerfiles, containerizing applications, or building Docker images with docker build. Covers multi-stage builds, layer caching, base image selection, security hardening, and language-specific patterns for Python,…
  • 100containerization
    Packages an application into a container image that is small, reproducible, and safe to run — Dockerfiles, layer caching, multi-stage builds, non-root users, and runtime configuration. Use this whenever the user is writing a Dockerfile, mentions Docker or OCI images, image size…
  • 100docker-build-strategies
    Use this skill when writing, reviewing, or optimizing Dockerfiles, even if the user just says their image is too large, their build is slow, or they need to harden a container for production. Covers multi-stage builds, layer caching, .dockerignore, non-root users, and image size optimization.
  • 100dockerfile-frontend
    Multi-stage Dockerfile patterns for React/Vite/TypeScript frontends — node:alpine build, lockfile caching, build-time VITE_* vars, nginx SPA fallback, envsubst config. Use when containerizing static frontends.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.