Docker & Kubernetes

[project]
name = "bookshelf"
version = "0.1.0"
description = "Bookshelf"
requires-python = ">=3.12"
dependencies = [
    "django==6.1.*",
    "django-tasks-db>=0.13.0",
    "gunicorn>=26.2.0",
    "psycopg[binary]>=3.3.6",
    "redis>=8.1.0",
    "uvicorn>=0.54.0",
    "uvicorn-worker>=0.4.0",
    "whitenoise>=6.12.0",
]

$ uv lock
Resolved 16 packages in 4ms
$ uv run python -W error manage.py check
System check identified no issues (0 silenced).

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]          # no default on purpose
DEBUG = os.environ.get("DJANGO_DEBUG", "0") == "1"
ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "localhost").split(",")
CSRF_TRUSTED_ORIGINS = [
    o for o in os.environ.get("DJANGO_CSRF_TRUSTED_ORIGINS", "").split(",") if o
]

if os.environ.get("POSTGRES_HOST"):
    DATABASES = {
        "default": {
            "ENGINE": "django.db.backends.postgresql",
            "HOST": os.environ["POSTGRES_HOST"],
            "PORT": os.environ.get("POSTGRES_PORT", "5432"),
            "NAME": os.environ.get("POSTGRES_DB", "bookshelf"),
            "USER": os.environ.get("POSTGRES_USER", "bookshelf"),
            "PASSWORD": os.environ.get("POSTGRES_PASSWORD", ""),
            "CONN_MAX_AGE": int(os.environ.get("DJANGO_CONN_MAX_AGE", "60")),
            "CONN_HEALTH_CHECKS": True,
        }
    }
else:  # local runs without a database server
    DATABASES = {
        "default": {
            "ENGINE": "django.db.backends.sqlite3",
            "NAME": os.environ.get("SQLITE_PATH", BASE_DIR / "db.sqlite3"),
        }
    }

if os.environ.get("REDIS_URL"):
    CACHES = {
        "default": {
            "BACKEND": "django.core.cache.backends.redis.RedisCache",
            "LOCATION": os.environ["REDIS_URL"],
        }
    }

TASKS = {
    "default": {
        "BACKEND": "django_tasks_db.DatabaseBackend",
        "QUEUES": ["default", "emails"],
    }
}

STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
STORAGES = {
    "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
    "staticfiles": {
        "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"
    },
}

# TLS ends at the ingress or load balancer, which sets X-Forwarded-Proto.
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SESSION_COOKIE_SECURE = not DEBUG
CSRF_COOKIE_SECURE = not DEBUG

# Containers log to stdout/stderr; the runtime collects the stream.
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "root": {"handlers": ["console"], "level": "INFO"},
}

$ DJANGO_SECRET_KEY=scratch-only-not-secret uv run python manage.py check --deploy
System check identified some issues:

WARNINGS:
?: (security.W004) You have not set a value for the SECURE_HSTS_SECONDS setting. ...
?: (security.W008) Your SECURE_SSL_REDIRECT setting is not set to True. ...
?: (security.W009) Your SECRET_KEY has less than 50 characters, less than 5 unique characters, or it's prefixed with 'django-insecure-' ...

System check identified 3 issues (0 silenced).

# syntax=docker/dockerfile:1

# ---- Stage 1: build the virtual environment and the static files ----
FROM python:3.13-slim-trixie AS builder

COPY --from=ghcr.io/astral-sh/uv:0.12.22 /uv /uvx /bin/

ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy \
    UV_NO_DEV=1 \
    UV_PYTHON_DOWNLOADS=0

WORKDIR /app

# Dependencies first: this layer is reused until uv.lock or pyproject.toml change.
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project

# Then the code.
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked

# collectstatic needs settings to import, not real secrets: a throw-away key
# exists only for this RUN and is not stored in the image's environment.
RUN DJANGO_SECRET_KEY=collectstatic-only \
    /app/.venv/bin/python manage.py collectstatic --noinput

# ---- Stage 2: the runtime image ----
FROM python:3.13-slim-trixie

ENV PATH="/app/.venv/bin:$PATH" \
    PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

RUN groupadd --system --gid 10001 bookshelf \
 && useradd --system --uid 10001 --gid bookshelf --no-create-home bookshelf

WORKDIR /app
COPY --from=builder --chown=root:root /app /app

USER 10001:10001
EXPOSE 8000

CMD ["gunicorn", "config.asgi:application", \
     "--worker-class", "uvicorn_worker.UvicornWorker", \
     "--bind", "0.0.0.0:8000", \
     "--workers", "2", \
     "--no-control-socket", \
     "--access-logfile", "-"]

$ UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_NO_DEV=1 UV_PYTHON_DOWNLOADS=0 uv sync --locked --no-install-project
...
 + whitenoise==6.12.0
$ UV_NO_DEV=1 uv sync --locked
Checked 15 packages in 0.97ms
$ DJANGO_SECRET_KEY=collectstatic-only .venv/bin/python manage.py collectstatic --noinput
130 static files copied to '<build context>/staticfiles', 390 post-processed.

.git
.venv
__pycache__/
*.py[cod]
.env
.env.*
db.sqlite3
staticfiles/
media/
.pytest_cache/
.coverage
compose*.yaml
k8s/
Dockerfile
.dockerignore
*.log

$ gunicorn config.asgi:application --worker-class uvicorn_worker.UvicornWorker \
    --bind 127.0.0.1:47671 --workers 2 --no-control-socket --access-logfile -
[INFO] Starting gunicorn 26.2.0
[INFO] Using worker: uvicorn_worker.UvicornWorker
[INFO] Booting worker with pid: 33017
[INFO] Booting worker with pid: 33018
[INFO] Waiting for application startup.
[INFO] ASGI 'lifespan' protocol appears unsupported.
[INFO] Application startup complete.
$ curl -s -w ' [%{http_code}]\n' http://localhost:47671/livez
{"status": "alive"} [200]
$ curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://localhost:47671/static/admin/css/base.css
200 text/css; charset="utf-8"

name: bookshelf

x-django: &django
  build: .
  image: bookshelf:dev
  env_file:
    - path: .env
      required: true
  environment:
    POSTGRES_HOST: db
    REDIS_URL: redis://redis:6379/0
    DJANGO_ALLOWED_HOSTS: localhost,127.0.0.1

services:
  db:
    image: postgres:18
    env_file:
      - path: .env
        required: true
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s

  redis:
    image: redis:8-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

  migrate:
    <<: *django
    command: ["python", "manage.py", "migrate", "--noinput"]
    restart: "no"
    depends_on:
      db:
        condition: service_healthy

  web:
    <<: *django
    ports:
      - "8000:8000"
    depends_on:
      migrate:
        condition: service_completed_successfully
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "python", "-c",
             "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/livez', timeout=2)"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 10s

  worker:
    <<: *django
    command: ["python", "manage.py", "db_worker", "--queue-name", "*"]
    depends_on:
      migrate:
        condition: service_completed_successfully

volumes:
  pgdata:

# Copy to .env (never commit .env). Generate the key with:
#   python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
DJANGO_SECRET_KEY=change-me
POSTGRES_DB=bookshelf
POSTGRES_USER=bookshelf
POSTGRES_PASSWORD=change-me

$ cp .env.example .env    # then put real values in .env
$ docker compose config -q && echo valid
valid
$ docker compose up --build -d
$ docker compose ps
$ curl -s http://localhost:8000/readyz

  worker:
    build:
      context: /.../bookshelf
      dockerfile: Dockerfile
    command:
      - python
      - manage.py
      - db_worker
      - --queue-name
      - '*'
    depends_on:
      migrate:
        condition: service_completed_successfully
        required: true
    environment:
      DJANGO_ALLOWED_HOSTS: localhost,127.0.0.1
      DJANGO_SECRET_KEY: change-me
      POSTGRES_DB: bookshelf
      POSTGRES_HOST: db
      POSTGRES_PASSWORD: change-me
      POSTGRES_USER: bookshelf
      REDIS_URL: redis://redis:6379/0
    image: bookshelf:dev

from django.core.cache import cache
from django.db import connection
from django.http import JsonResponse
from django.views.decorators.cache import never_cache
from django.views.decorators.http import require_GET


@never_cache
@require_GET
def livez(request):
    """Liveness: the process answers. No database, no cache."""
    return JsonResponse({"status": "alive"})


@never_cache
@require_GET
def readyz(request):
    """Readiness: this pod can serve traffic right now."""
    checks = {}
    try:
        with connection.cursor() as cursor:
            cursor.execute("SELECT 1")
        checks["database"] = "ok"
    except Exception:
        checks["database"] = "unavailable"
    try:
        cache.set("readyz", "1", timeout=5)
        checks["cache"] = "ok" if cache.get("readyz") == "1" else "unavailable"
    except Exception:
        checks["cache"] = "unavailable"
    ok = all(v == "ok" for v in checks.values())
    return JsonResponse(
        {"status": "ready" if ok else "unavailable", "checks": checks},
        status=200 if ok else 503,
    )

from django.contrib import admin
from django.urls import path

from catalog import health

urlpatterns = [
    path("livez", health.livez, name="livez"),
    path("readyz", health.readyz, name="readyz"),
    path("admin/", admin.site.urls),
]

from unittest import mock

from django.db.utils import OperationalError
from django.test import TestCase, override_settings


@override_settings(ALLOWED_HOSTS=["testserver"])
class HealthTests(TestCase):
    def test_liveness_never_touches_the_database(self):
        with self.assertNumQueries(0):
            response = self.client.get("/livez")
        self.assertEqual(response.status_code, 200)
        self.assertEqual(response.json(), {"status": "alive"})
        self.assertIn("no-cache", response["Cache-Control"])

    def test_readiness_ok(self):
        response = self.client.get("/readyz")
        self.assertEqual(response.status_code, 200)
        self.assertEqual(response.json()["checks"], {"database": "ok", "cache": "ok"})

    def test_readiness_fails_when_database_is_down(self):
        with mock.patch(
            "catalog.health.connection.cursor",
            side_effect=OperationalError("connection refused"),
        ):
            response = self.client.get("/readyz")
        self.assertEqual(response.status_code, 503)
        self.assertEqual(response.json()["checks"]["database"], "unavailable")

    def test_probes_are_get_only(self):
        self.assertEqual(self.client.post("/livez").status_code, 405)

$ uv run python manage.py test catalog
Found 4 test(s).
System check identified no issues (0 silenced).
....
----------------------------------------------------------------------
Ran 4 tests in 0.038s

OK

$ curl -s -w ' [%{http_code}]\n' http://localhost:47671/readyz
{"status": "ready", "checks": {"database": "ok", "cache": "ok"}} [200]

$ SQLITE_PATH=/nonexistent/dir/db.sqlite3 gunicorn config.wsgi:application --no-control-socket --bind 127.0.0.1:47670 &
$ curl -s -w ' [%{http_code}]\n' http://127.0.0.1:47670/livez
{"status": "alive"} [200]
$ curl -s -w ' [%{http_code}]\n' http://127.0.0.1:47670/readyz
{"status": "unavailable", "checks": {"database": "unavailable", "cache": "ok"}} [503]