Dockerfile Patterns for Python APIs

Goals

A production Docker image should be reproducible, small enough to move quickly, and boring to run.

Useful Defaults

• Pin the Python major/minor version.
• Install dependencies before copying the full app to improve layer caching.
• Avoid baking secrets into build args or image layers.
• Run as a non-root user.
• Use a clear startup command.

Example Shape

FROM python:3.12-slim

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

RUN useradd --create-home appuser
USER appuser

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

Things to Avoid

• latest tags for production images.
• Installing compilers in the final runtime image unless needed.
• Copying .env, local caches, notebooks, or test artifacts.
• Running database migrations implicitly on every container start.

Production Questions

• What is the image digest deployed to production?
• How are vulnerabilities scanned?
• Where are runtime secrets injected?
• How does the service shut down during deploys?