Dockerfile

# ── Build stage ────────────────────────────────────────────────────────────
# We use a single lightweight stage because this project has no compiled
# dependencies or build artefacts.  A multi-stage build would be correct for
# a project that compiles C extensions or bundles static assets.

FROM python:3.12-slim

# ── Metadata ───────────────────────────────────────────────────────────────
LABEL maintainer="your-email@example.com"
LABEL description="HTTP/1.1 server built from scratch — pure Python, zero dependencies"
LABEL version="1.0"

# ── Security: run as a non-root user ───────────────────────────────────────
# Containers that run as root are a significant attack surface.  Creating a
# dedicated system user limits the blast radius if the process is ever
# compromised.  --no-create-home avoids creating an unnecessary home directory.
RUN addgroup --system appgroup \
    && adduser --system --ingroup appgroup --no-create-home appuser

# ── Filesystem layout ──────────────────────────────────────────────────────
WORKDIR /app

# Copy source files.  We copy *.py explicitly rather than using COPY . .
# to avoid accidentally including .env files, credentials, or other sensitive
# material that might exist in the build context.
COPY *.py ./

# www/ holds static files served at GET /about
COPY www/ ./www/

# Transfer ownership so the non-root user can read the files.
RUN chown -R appuser:appgroup /app

# ── Drop privileges ────────────────────────────────────────────────────────
USER appuser

# ── Network ────────────────────────────────────────────────────────────────
# EXPOSE is documentation only — it tells docker run / Compose which port to
# publish.  The actual bind happens in main.py via HOST/PORT constants.
EXPOSE 8080

# ── Health check ───────────────────────────────────────────────────────────
# Docker calls this command periodically.  If it returns non-zero three times
# in a row the container is marked "unhealthy" and orchestrators like
# Kubernetes / ECS can restart or replace it automatically.
#
# We use Python's stdlib urllib rather than curl because the slim image has
# no curl pre-installed — adding it would increase the image size for a
# one-liner we can replicate with stdlib.
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD python -c "\
import urllib.request, sys; \
req = urllib.request.urlopen('http://localhost:8080/health', timeout=4); \
sys.exit(0 if req.status == 200 else 1)"

# ── Entrypoint ─────────────────────────────────────────────────────────────
# Use exec form (JSON array) so the process receives signals directly rather
# than being wrapped in a shell.  This is what makes SIGTERM from
# 'docker stop' trigger our graceful shutdown handler in main.py.
CMD ["python", "main.py"]