Dockerfile

# ============================================================
# Dockerfile — Multi-stage build
# ============================================================
# Stage 1: builder (installs deps in a clean layer)
# Stage 2: runtime (copies only what's needed — smaller image)
#
# Why multi-stage?
#   - Build tools (gcc, pip) don't end up in the final image
#   - Final image is smaller and has a smaller attack surface
#   - Standard practice at every major tech company
# ============================================================

# ── Stage 1: Builder ─────────────────────────────────────────
FROM python:3.12-slim AS builder

WORKDIR /build

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements first (Docker layer caching — only re-runs pip
# install if requirements.txt changes, not on every code change)
COPY requirements.txt .
RUN pip install --upgrade pip \
    && pip install --no-cache-dir --prefix=/install -r requirements.txt


# ── Stage 2: Runtime ─────────────────────────────────────────
FROM python:3.12-slim AS runtime

# Non-root user for security (FAANG security requirement)
RUN groupadd -r appuser && useradd -r -g appuser appuser

WORKDIR /app

# Copy installed packages from builder stage
COPY --from=builder /install /usr/local

# Copy application source
COPY . .

# Set ownership
RUN chown -R appuser:appuser /app

USER appuser

# Environment defaults (override in docker-compose.yml or K8s secrets)
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    REDIS_URL=redis://redis:6379/0 \
    APP_PORT=8000 \
    WORKERS=8

# Expose API port
EXPOSE 8000

# Health check (Docker will mark container unhealthy if this fails)
HEALTHCHECK --interval=10s --timeout=5s --start-period=15s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/live')" || exit 1

# ── Targets ──────────────────────────────────────────────────
# API server (default)
CMD ["uvicorn", "api.main:app", \
     "--host", "0.0.0.0", \
     "--port", "8000", \
     "--workers", "1", \
     "--log-level", "info"]