The Districtr CMS: a Wagtail service for content, users, and data admin

New top-level cms/ — a Django 5.2 / Wagtail 7 project sharing the
backend's Postgres, with every Django-owned table confined to an 'admin'
schema (search_path=admin,public + bootstrap_schema). It is the JWT
issuer (RS256 with kid headers over /.well-known/jwks.json), the CMS for
portal/place/static pages, the moderation surface for comment and map
submissions, and the admin for map modules and overlays.

Nothing routes to it yet: the frontend still authenticates against Auth0
and the backend still verifies Auth0's JWKS, so this is additive and
schema-confined. Deploy it to dev and exercise it there before the
cutover PR.

Shape: three roles (admin / partner / super_partner) as Django groups;
Team as the tenant boundary, scoping galleries, pages, and modules;
review scope derived from a team's portals and minted as the review_tags
claim PR3 enforces; legacy TipTap content converted to StreamField by
migrate_tiptap, wrapped in a reversible migration. 238 tests, and CI also
runs alembic against the same database to prove the managed=False
datastore mirrors still match the backend schema.

Reviewer: cms/README-less by design — start at config/settings/base.py
(the search_path pinning and SIMPLE_JWT block), then authapi/{jwks,
tokens,serializers,scopes,teams}.py, which is where the whole security
model lives. content/0003_import_legacy_content runs migrate_tiptap
during migrate and refuses to do so unattended without an owner mapping.

Author: nofurtherinformation

.github/workflows/test-cms.yml

@@ -0,0 +1,105 @@
+name: Test CMS
+
+on:
+  push:
+    paths: &paths
+      - "cms/**"
+      - ".github/workflows/test-cms.yml"
+      # The datastore mirror drift check depends on the backend schema:
+      - "backend/app/models.py"
+      - "backend/app/alembic/**"
+  # Also on PRs, so the suite runs against the MERGE RESULT rather than only
+  # the branch tip.
+  pull_request:
+    paths: *paths
+
+jobs:
+  container-job:
+    runs-on: ubuntu-latest
+
+    container: python:3.12.6
+
+    services:
+      postgres:
+        image: postgis/postgis:16-3.4
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      DJANGO_SETTINGS_MODULE: config.settings.dev
+      DJANGO_SECRET_KEY: test-only-secret-key
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: postgres
+      POSTGRES_SERVER: postgres
+      POSTGRES_PORT: 5432
+
+    steps:
+      - name: Checkout repo code
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt --no-cache-dir
+        working-directory: cms
+
+      - name: Django system checks
+        run: python manage.py check
+        working-directory: cms
+
+      - name: Bootstrap schema and migrate
+        run: |
+          python manage.py bootstrap_schema
+          python manage.py migrate --noinput
+        working-directory: cms
+
+      - name: Check for missing migrations
+        run: python manage.py makemigrations --check --dry-run
+        working-directory: cms
+
+      - name: Run tests
+        run: python manage.py test
+        working-directory: cms
+
+      # Drift guard: datastore mirrors the Alembic-owned `public` tables with
+      # managed=False models. Run the backend's migrations against the same
+      # database, then verify the mirrors still match the live schema.
+      - name: Install backend dependencies (for Alembic)
+        run: |
+          pip install -r requirements.txt --no-cache-dir
+        working-directory: backend
+
+      - name: Run backend (Alembic) migrations
+        run: alembic upgrade head
+        working-directory: backend
+        env:
+          DOMAIN: postgres
+          ENVIRONMENT: test
+          PROJECT_NAME: Districtr v2 backend
+          BACKEND_CORS_ORIGINS: "http://localhost,http://localhost:5173"
+          SECRET_KEY: mysupersecretkey
+          DATABASE_URL: postgresql+psycopg://postgres:postgres@postgres:5432/postgres
+          POSTGRES_SCHEME: postgresql+psycopg
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+          POSTGRES_SERVER: postgres
+          POSTGRES_PORT: 5432
+          AUTH_JWKS_URL: http://localhost:8001/.well-known/jwks.json
+          AUTH_AUDIENCE: http://localhost:8000/
+          AUTH_ISSUER: http://localhost:8001
+          AUTH_ALGORITHMS: RS256
+
+      - name: Check mirror drift
+        run: python manage.py check_mirror_drift
+        working-directory: cms

Makefile

@@ -1,7 +1,7 @@
 .PHONY: dev prod playwright
 
 dev:
-	docker-compose up db backend frontend
+	docker-compose up db backend frontend cms
 
 prod:
 	docker-compose up db backend frontend-prod

cms/.env.docker.example

@@ -0,0 +1,32 @@
+# Districtr CMS (Wagtail) — local dev via docker-compose
+DJANGO_SETTINGS_MODULE=config.settings.dev
+DJANGO_SECRET_KEY=django-insecure-dev-only-key
+
+# Postgres (same database as the FastAPI backend; Django tables live in the
+# `admin` schema via search_path)
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=districtr
+POSTGRES_SERVER=db
+POSTGRES_PORT=5432
+
+WAGTAILADMIN_BASE_URL=http://localhost:8001
+DEFAULT_FROM_EMAIL=noreply@districtr.org
+
+# FastAPI backend (GeoPackage import + thumbnail triggers; compose-internal)
+BACKEND_API_URL=http://backend:8000
+
+# Object storage for GeoPackage and overlay uploads — mirrors the backend's
+# env contract (backend/app/core/config.py). Set ACCOUNT_ID for Cloudflare
+# R2, or AWS_S3_ENDPOINT for a custom S3 endpoint; leave both unset for
+# plain AWS S3.
+#AWS_ACCESS_KEY_ID=
+#AWS_SECRET_ACCESS_KEY=
+#R2_BUCKET_NAME=
+#ACCOUNT_ID=
+#AWS_S3_ENDPOINT=
+
+# Public base URL stored as Overlay.source for uploaded overlays — the CDN
+# fronting the bucket (https://tilesets1.cdn.districtr.org in prod). When
+# unset, the raw s3://bucket/key path is stored instead.
+#OVERLAY_PUBLIC_URL_BASE=

cms/Dockerfile

@@ -0,0 +1,20 @@
+# Production image for the Districtr CMS (Wagtail) on Fly.io
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    DJANGO_SETTINGS_MODULE=config.settings.production
+
+WORKDIR /districtr-cms
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# collectstatic needs settings to load; the real secret comes from Fly at runtime.
+RUN DJANGO_SECRET_KEY=build-only python manage.py collectstatic --noinput
+
+EXPOSE 8080
+
+CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8080", "--workers", "2", "--timeout", "60"]

cms/Dockerfile.dev

@@ -0,0 +1,14 @@
+# Dev image for the Districtr CMS (Wagtail); used by docker-compose.
+FROM python:3.12.7
+
+ENV PYTHONUNBUFFERED=1 \
+    DJANGO_SETTINGS_MODULE=config.settings.dev
+
+WORKDIR /districtr-cms
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

cms/authapi/__init__.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class AuthapiConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "authapi"

cms/authapi/apps.py

@@ -0,0 +1,56 @@
+"""
+JWK construction for the verifying key(s), including the RFC 7638 thumbprint
+used as `kid`.
+
+The FastAPI backend verifies our tokens with PyJWT's PyJWKClient, which
+selects the signing key by matching the JWT header's `kid` against the JWKS.
+SimpleJWT does not emit a `kid` header by default, so authapi.tokens adds
+one using the same thumbprint computed here.
+"""
+
+import base64
+import hashlib
+import json
+from functools import lru_cache
+
+from django.conf import settings
+from jwt.algorithms import RSAAlgorithm
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def jwk_from_public_pem(public_pem: str) -> dict:
+    """Build a JWK dict (with RFC 7638 `kid`) from an RSA public key PEM."""
+    public_key = RSAAlgorithm(RSAAlgorithm.SHA256).prepare_key(public_pem)
+    jwk = json.loads(RSAAlgorithm.to_jwk(public_key))
+    # RFC 7638: thumbprint over the lexicographically ordered required members.
+    canonical = json.dumps(
+        {"e": jwk["e"], "kty": jwk["kty"], "n": jwk["n"]},
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+    jwk["kid"] = _b64url(hashlib.sha256(canonical.encode("utf-8")).digest())
+    jwk["use"] = "sig"
+    jwk["alg"] = "RS256"
+    return jwk
+
+
+@lru_cache(maxsize=1)
+def current_jwk() -> dict:
+    """JWK for the active verifying key."""
+    return jwk_from_public_pem(settings.SIMPLE_JWT["VERIFYING_KEY"])
+
+
+def current_kid() -> str:
+    return current_jwk()["kid"]
+
+
+def all_jwks() -> list[dict]:
+    """Active key plus, during rotation, the next key (JWT_NEXT_VERIFYING_KEY)."""
+    keys = [current_jwk()]
+    next_pem = getattr(settings, "JWT_NEXT_VERIFYING_KEY", "")
+    if next_pem:
+        keys.append(jwk_from_public_pem(next_pem))
+    return keys