feat: persistent-volume support via entrypoint chown + root info route

Two related changes that both ship in the container image:

1. docker-entrypoint.sh + Dockerfile: when /app/data is a freshly mounted
   persistent volume the platform hands the container a root-owned
   directory, which broke load_data() because the container was running
   as appuser. The new entrypoint runs as root just long enough to
   chown /app/data, then exec-drops to appuser via gosu before running
   the original uvicorn CMD. The chown is idempotent (no-op on warm
   starts where the directory is already correctly owned). Verified
   locally with a fresh root-owned docker volume.

2. New "/" route returning service metadata and useful pointers
   (openapi.json, docs, redoc, health, example lookup/pattern URLs,
   source repo). Replaces the previous {"detail":"Not Found"} on the
   bare hostname. Marked include_in_schema=False so it doesn't clutter
   the OpenAPI document.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bk86a

CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+### Added
+
+- **`/` root endpoint** returns service metadata and pointers to `/openapi.json`, `/docs`, `/redoc`, `/health`, and example `/lookup` and `/pattern` URLs. Replaces the previous `{"detail":"Not Found"}` response on the bare hostname. Marked `include_in_schema=False` so it doesn't clutter the OpenAPI document.
+- **Persistent-volume support** via a new `docker-entrypoint.sh`: container starts as root, `chown appuser:appuser /app/data` (idempotent — no-op on warm starts), then `exec gosu appuser "$@"` to drop privileges before uvicorn starts. `Dockerfile` installs `gosu` and replaces `USER appuser` with `ENTRYPOINT`. Lets a freshly-provisioned platform persistent volume (initially root-owned) be mounted at `/app/data` without breaking the SQLite cache build. Cold-start cache survives pod recreates and redeploys; subsequent restarts skip the GISCO TERCET re-download until the configured TTL expires.
+
 ### Documentation
 
 - **Performance re-baseline under multi-worker** (#68): `docs/performance.md` updated with the post-#68 numbers and a new rate-limit shared-storage verification subsection. Realistic-corpus knee at 35-40 RPS (vs ~30 single-worker), hot-key plateau at ~50 RPS, p99 at the old knee dropped from 4.5 s to 150 ms. Recommended operating point unchanged at 27 RPS — the win is headroom, not the operating point itself. The Redis sidecar shared-storage path is verified end-to-end: 130 anonymous requests against the published `120/minute` cap produced exactly 120 × `200` + 10 × `429`, ruling out per-worker counter divergence.

Dockerfile

@@ -2,6 +2,13 @@ FROM python:3.14-slim
 
 WORKDIR /app
 
+# gosu is used by docker-entrypoint.sh to drop privileges to appuser after
+# fixing ownership on the /app/data mount (no-op on warm starts; required
+# when the platform mounts a fresh root-owned persistent volume).
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends gosu \
+    && rm -rf /var/lib/apt/lists/*
+
 COPY requirements.lock ./requirements.lock
 RUN pip install --no-cache-dir -r requirements.lock
 
@@ -11,14 +18,15 @@ RUN useradd -r -s /bin/false appuser \
 
 COPY app/ ./app/
 COPY tercet_missing_codes.csv ./tercet_missing_codes.csv
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
 VOLUME ["/app/data"]
 
 EXPOSE 8000
 
-USER appuser
-
 HEALTHCHECK --interval=30s --timeout=5s --start-period=120s --retries=3 \
     CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
 
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
 CMD ["sh", "-c", "exec uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers ${PC2NUTS_WORKERS:-1}"]

app/main.py

@@ -290,6 +290,29 @@ def get_pattern(
     )
 
 
+@app.get(
+    "/",
+    summary="Service entry point",
+    include_in_schema=False,
+)
+def root(request: Request, response: Response):
+    response.headers["Cache-Control"] = f"public, max-age={settings.cache_max_age}"
+    base = str(request.base_url).rstrip("/")
+    return {
+        "service": "PostalCode2NUTS",
+        "version": __version__,
+        "links": {
+            "openapi": f"{base}/openapi.json",
+            "docs": f"{base}/docs" if settings.docs_enabled else None,
+            "redoc": f"{base}/redoc" if settings.docs_enabled else None,
+            "health": f"{base}/health",
+            "lookup_example": f"{base}/lookup?country=DE&postal_code=10115",
+            "pattern_example": f"{base}/pattern?country=DE",
+            "source": "https://github.com/bk86a/PostalCode2NUTS",
+        },
+    }
+
+
 @app.get(
     "/health",
     response_model=HealthResponse,

docker-entrypoint.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Drop privileges to appuser before running the CMD.
+#
+# We start the container as root so a freshly-mounted persistent volume at
+# /app/data (initially root-owned by the platform) can be chowned to appuser.
+# The chown is idempotent: a no-op on warm starts where the directory is
+# already correctly owned.
+set -e
+chown appuser:appuser /app/data
+exec gosu appuser "$@"