Merge pull request 'docs: mark Phase 0 done, record D19 (auto-update, deferred)' (#12 ) from docs/phase-0-wrapup into test/deploy-login-smoke-test

Reviewed-on: #12
docs: mark Phase 0 done, record D19 (auto-update, deferred)
2026-09-21 22:59:58 -04:00 · 2026-09-21 22:57:26 -04:00 · 2026-09-21 22:54:51 -04:00
4 changed files with 207 additions and 12 deletions
@@ -78,6 +78,30 @@ Nothing enforces the admin role yet — no admin-only endpoint exists — so tod
 invited account only in the role recorded on it. Invite management in a later phase is what starts
 reading it.
 ## Verify login actually works, not just that the API responds
 `GET /api/v1/healthz` proves the process is up. It does **not** prove a real login works, because
 the session cookie is set with `Secure` in production (`apps/api/velodrome/api/v1/auth.py`) —
 browsers silently refuse to store a `Secure` cookie unless the request was actually served over
 HTTPS. Test through a plain-HTTP address (an IP, a bare port, skipping the reverse proxy) and
 `/auth/login` still returns 200 with a valid response body; the cookie is just quietly dropped, so
 the very next request looks unauthenticated. From a browser this looks exactly like "I logged in
 and it bounced me straight back to the login screen," with nothing that looks like an error. This
 happened on the very first real deployment.
 `scripts/smoke-test.sh` exists so this is caught by running a command, not by refreshing a browser
 tab:
 ```sh
 scripts/smoke-test.sh https://bike.bbergle.com you@example.com yourpassword
 ```
 It logs in, confirms a session cookie was actually stored (not just sent), then makes an
 authenticated follow-up request and confirms it succeeds and returns the right account. Run it
 after every real deploy, against the actual public URL your users will use — testing against a
 plain-HTTP IP will (correctly) tell you nothing about whether login works for anyone using the real
 domain.
 ## Environment variables
 All read by `apps/api/velodrome/config.py` (prefix `VELODROME_`) — the app and Alembic both read
@@ -130,8 +154,20 @@ It does **not** SSH into the host and recreate the running container — rolling
 Unraid (pulling it and clicking "Apply" on the container, or via Unraid's own update-checking) is
 left as a manual/Unraid-side step, not something CI does unattended.
 Unraid's own "check for updates" is **not a reliable signal for this container specifically** — see
 `docs/DECISIONS.md` D19. Because Gitea Actions builds on this same host's `dockerd`, every CI run
 keeps the local `:latest` tag fresh regardless of whether the *running container* was ever
 recreated from it, so the checker can say "up to date" while the running container is genuinely
 stale. Don't wait for that badge; recreate deliberately after a merge you know should ship.
 ## What's not here yet
-Backups (`docs/PLAN.md` calls for a systemd timer running `restic` against `/data`, independent of
+- Backups (`docs/PLAN.md` calls for a systemd timer running `restic` against `/data`, independent
-CI) and the `import_inbox` USB-watch bind mount are both Phase 1+ concerns — nothing in the schema
+  of CI) and the `import_inbox` USB-watch bind mount — both Phase 1+ concerns, nothing in the
-uses them yet.
+  schema uses them yet.
 - An auto-updater for the running container (attempted with Watchtower, deferred — D19).
 - Persisting the host-local trust material from D17/D19 (`/etc/hosts`, `certs.d`, the CA bundle
  entry) across a reboot — currently lost on restart, deliberately left that way pending a
  decision about editing `/boot/config/go` (D19).
 - Migrating Gitea + its Actions runners off this Unraid host onto a dedicated VM — the root cause
  behind several of the fixes above, raised as a real future decision, not started (D19).
@@ -358,8 +358,67 @@ the deployed image has to carry.
 ---
 ### D19 — Auto-update: attempted, deferred; Unraid's own update checker needed a separate fix
 **The immediate bug:** Unraid's Docker "check for updates" reported `not available` for `velodrome`
 after D17's registry move. Root cause, found by reading the actual PHP source
 (`dynamix.docker.manager`'s `DockerClient.php`): it queries the registry's manifest API directly
 over `curl` from PHP, which is a completely different trust path from `dockerd`'s own — it doesn't
 read Docker's `/etc/docker/certs.d` at all, only the OS-wide CA bundle. **Fixed** by also adding the
 D17 self-signed cert to `/usr/local/share/ca-certificates/` and running `update-ca-certificates` on
 the Unraid host — a third, independent place this cert now needs to be trusted (alongside
 `certs.d` and the `/etc/hosts` entry from D17), and like those two, not yet persisted across a
 reboot (`/boot/config/go` again — same deliberate non-decision as D17).
 **A second, structural problem this exposed, not fixed:** even with the checker itself working,
 "up to date" on this host doesn't reliably mean the *running container* matches the registry.
 Gitea Actions builds directly on this same host's `dockerd` (DooD), which means every CI build also
 leaves its own result sitting in the **local image cache** tagged `:latest` — so the local-vs-remote
 digest comparison Unraid's checker does is comparing the registry against a tag that CI keeps fresh
 on its own, independent of whether the `velodrome` *container* was ever recreated from it. Confirmed
 directly: the checker reported "up to date" while the running container's actual manifest digest
 (read via `docker inspect`) provably differed from the registry's current `Docker-Content-Digest`.
 This is a consequence of building CI on the same host as the app runs, not a bug to patch around —
 see the Gitea-to-VM item below.
 **Attempted: Watchtower**, label-scoped (`WATCHTOWER_LABEL_ENABLE=true` + a
 `com.centurylinklabs.watchtower.enable=true` label on `velodrome` only, specifically so it can never
 touch any of the ~40 other containers on this host) with the CA bundle mounted in for the same
 registry-trust reason as above. **Failed on the first attempt** — `containrrr/watchtower`'s
 published image talks a Docker API version (1.25) too old for this host's `dockerd`, a stale-image
 problem, not a design problem. Not yet retried with a maintained fork. The `velodrome` container
 does carry the watch-enable label already (added when it was recreated to pick up D18's CLI), so
 turning this on later is "run the right watchtower image," not "redesign anything."
 **Why not have CI redeploy the container directly** (it already has host `dockerd` access via DooD):
 considered and explicitly rejected, again — see D16/D17's reasoning, which this doesn't change.
 Turning every merge to `main` into an unattended production change on a personal server is a bigger
 step than "install an auto-updater," and wasn't asked for.
 **Until this is finished:** redeploying after a merge is `docker pull` + recreate, same as any
 manual deploy — `deploy/README.md`'s "Publishing the image" section.
 ---
 ## Deliberately deferred
 - **Finish the Watchtower auto-updater** (D19) — retry with a maintained image; `velodrome` is
  already labeled for it.
 - **Migrate Gitea + its Actions runners to a dedicated VM**, off the Unraid host the app itself
  runs on. Raised explicitly (not yet started) after D17/D19 both turned out to be fighting the
  same root cause from different angles: CI sharing a `dockerd` with ~40 unrelated production
  containers means every registry-trust fix and every update-check quirk this session hit was more
  contained, and more repeatable to reason about, than it should have needed to be. A dedicated VM
  removes that coupling entirely — CI's own Docker config becomes free to change without any
  blast-radius conversation about Plex or Vaultwarden ever again. Real migration work (new VM,
  moving Gitea's and both runners' appdata, re-pointing `192.168.0.3`, updating every reference to
  it across this repo and this session's own tooling), not a quick fix — a deliberate choice to do
  later, not an oversight now.
 - **Persist the D17/D19 host-local trust files across a reboot** (`/etc/hosts`, `certs.d`, the CA
  bundle addition) via `/boot/config/go`. Left un-persisted through both decisions specifically
  because editing anything under `/boot` was raised as a real concern mid-session — worth revisiting
  together once, for all three at once, rather than as three separate asks.
 - **Routing** (Valhalla/Photon/Overpass) — Phase 5, optional. Several GB of RAM for something
  Komoot already does well.
 - **Local LLM ride summaries** (Ollama) — Phase 4, behind a compose profile.
@@ -529,13 +529,31 @@ These are the payoff for self-hosting — things Strava structurally cannot do.
 Estimates assume one developer working evenings and weekends.
-**Phase 0 — Scaffolding (2 weeks).** Monorepo, `uv`/`ruff`/`mypy --strict`, FastAPI skeleton with
+**Phase 0 — Scaffolding.** ✅ **Done, with two deliberate deviations from this original description —
-`/healthz` and OpenAPI, Alembic baseline (users/invites/sessions **with RLS policies from the first
+both recorded in `docs/DECISIONS.md`, not silent drift.** Monorepo, `uv`/`ruff`/`mypy --strict`,
-migration**), SvelteKit static SPA shell with login, manifest + service worker + precache passing
+FastAPI skeleton with `/healthz` and OpenAPI, Alembic baseline (users/invites/sessions), SvelteKit
-Lighthouse installability, VAPID keypair, Caddy, compose, Gitea Actions green, image in the registry,
+static SPA shell with login, manifest + service worker, Caddy, Gitea Actions green, image in the
-deployed.
+registry, deployed to a real Unraid host behind real HTTPS.
-*Done when:* you log in at the real URL, add it to your iPhone home screen, it launches standalone —
+
-and a push to `main` rebuilds and redeploys it.
+- **SQLite, not Postgres+RLS.** D15 reversed D4 mid-Phase-0, after the RLS version was already
  shipped and merged. Isolation is now enforced entirely at the repository layer (`db.py`'s
  `Scope`), not database RLS. See D15 for the full cost/benefit record.
 - **CI builds and pushes on every push to `main`, but does not auto-redeploy the running
  container.** D16/D17 made this deliberate: the runner shares this Unraid host's own `dockerd`
  (DooD), and an unattended redeploy of a container on a personal server with no human gate was
  judged the wrong default. A push to `main` gets you a new image in the registry within minutes;
  getting it onto the running container is still a manual step (`deploy/README.md`). An
  auto-updater (Watchtower or similar) was attempted and deferred — see "Deliberately deferred"
  in `docs/DECISIONS.md`.
 - **VAPID/push notifications were never started.** Correctly so — per this doc's own PWA-decision
  table, that's gated behind standalone-mode detection and belongs to a later phase, not Phase 0.
 *Done when — status:* Logging in at the real URL (`https://bike.bbergle.com`) and seeing an
 authenticated view of your own account is **verified**, including the session actually persisting
 (`scripts/smoke-test.sh`, added after a real Secure-cookie-over-HTTP bug on the first deploy — see
 that script's header comment). **Not yet tried:** adding it to an iPhone home screen and confirming
 a standalone launch — nobody has actually done this yet, so it isn't checked off, even though the
 manifest and service worker are in place.
 **Phase 1 — Zero-touch ride history (6–8 weeks).** Ingestion core (all three dedupe layers, course
 discrimination, quarantine); **the Bryton cloud poller as the primary path**, polling every 15 min with
@@ -654,8 +672,13 @@ because if the project stalls right after it, it has still succeeded.
 activity reaches Bryton's cloud with the phone switched off. Then plug it in over USB and `ls -R` the
 mounted volume to confirm the actual `.fit` path.
-**Phase 0:** `curl https://host/healthz` returns 200; push to `main` produces a new registry image and
+**Phase 0 — done, verified for real, not just assumed from CI going green:** `curl https://host/healthz`
-a redeployed container; `docker compose logs` shows migrations applied.
+returns 200; a push to `main` produces a new registry image (`docs/DECISIONS.md` D17's release
 workflow) — redeploying the running container from it is a manual step (D16/D17), not automatic;
 `docker exec velodrome velodrome create-admin` bootstraps the first user (D18); logging in at the
 real HTTPS URL and staying logged in on the next request is checked by `scripts/smoke-test.sh`, not
 eyeballed in a browser, after that exact failure mode (a `Secure` cookie silently dropped when
 tested over plain HTTP) actually happened on the first deploy.
 **Phase 1 — ingestion:**
 - Upload a real Rider 650 `.fit` → activity appears with correct distance, elevation, and map track.
@@ -0,0 +1,77 @@
 #!/usr/bin/env bash
 # Post-deploy smoke test: proves a login -> authenticated request round trip actually works
 # against a REAL deployed instance, over the network, the way a browser sees it.
 #
 # Exists because pytest (real SQLite, no mocks — see CLAUDE.md) proves the API logic is
 # correct in isolation, but can't catch topology-specific failures. Concretely: a session
 # cookie is set with `Secure` in production (velodrome/api/v1/auth.py), which browsers
 # silently refuse to store unless the request was actually served over HTTPS. Hit the app via
 # a plain-HTTP address (an IP, a port, skipping the reverse proxy) and `/auth/login` still
 # returns 200 with valid credentials, and the cookie header is still sent — it's just quietly
 # dropped, so the very next request looks unauthenticated. From a browser this looks exactly
 # like "I logged in and it bounced me straight back to the login screen," with no error
 # anywhere. Caught for real the first time this got deployed; this script exists so it's
 # caught by running a command, not by refreshing a browser tab.
 #
 # Usage:
 #   scripts/smoke-test.sh <base_url> <email> <password>
 #   scripts/smoke-test.sh https://bike.bbergle.com you@example.com yourpassword
 #
 # Doesn't create the account — bootstrap one first with
 # `docker exec -it velodrome velodrome create-admin --email you@example.com`, then reuse
 # those credentials here (or keep a small dedicated account around just for this).
 set -euo pipefail
 BASE_URL="${1:?usage: smoke-test.sh <base_url> <email> <password>}"
 EMAIL="${2:?usage: smoke-test.sh <base_url> <email> <password>}"
 PASSWORD="${3:?usage: smoke-test.sh <base_url> <email> <password>}"
 BASE_URL="${BASE_URL%/}"
 COOKIEJAR="$(mktemp)"
 LOGIN_BODY="$(mktemp)"
 ME_BODY="$(mktemp)"
 trap 'rm -f "$COOKIEJAR" "$LOGIN_BODY" "$ME_BODY"' EXIT
 echo "-> logging in as $EMAIL at $BASE_URL"
 LOGIN_STATUS=$(curl -s -o "$LOGIN_BODY" -w '%{http_code}' \
  -c "$COOKIEJAR" \
  -X POST "$BASE_URL/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}")
 if [ "$LOGIN_STATUS" != "200" ]; then
  echo "FAIL: login returned $LOGIN_STATUS, expected 200"
  cat "$LOGIN_BODY"
  exit 1
 fi
 echo "   login: 200 OK"
 if ! grep -q "_session" "$COOKIEJAR" 2>/dev/null; then
  echo "FAIL: login succeeded but no session cookie was actually stored by the client."
  echo "      Almost certainly a Secure-cookie-over-HTTP mismatch — see the comment at the"
  echo "      top of this script. Are you testing via HTTPS through the real reverse proxy,"
  echo "      or a plain-HTTP address (an IP, a bare port)?"
  exit 1
 fi
 echo "   session cookie: stored"
 echo "-> confirming the session actually authenticates a follow-up request"
 ME_STATUS=$(curl -s -o "$ME_BODY" -w '%{http_code}' -b "$COOKIEJAR" "$BASE_URL/api/v1/auth/me")
 if [ "$ME_STATUS" != "200" ]; then
  echo "FAIL: /auth/me returned $ME_STATUS after a successful login — the session isn't"
  echo "      persisting. This is exactly the 'logs in, bounces back to the login screen'"
  echo "      symptom a browser would show."
  cat "$ME_BODY"
  exit 1
 fi
 ME_EMAIL=$(python3 -c "import json,sys; print(json.load(open(sys.argv[1]))['email'])" "$ME_BODY" 2>/dev/null || echo "?")
 if [ "$ME_EMAIL" != "$EMAIL" ]; then
  echo "FAIL: /auth/me returned a different account ($ME_EMAIL) than the one that logged in ($EMAIL)."
  exit 1
 fi
 echo "   /auth/me: 200 OK, confirmed as $ME_EMAIL"
 echo "PASS: login -> authenticated request round trip works end to end at $BASE_URL"