From 244fe525dd3a3b8842e8901d586715d806ce481c Mon Sep 17 00:00:00 2001 From: Benny Date: Mon, 21 Sep 2026 22:57:26 -0400 Subject: [PATCH] docs: mark Phase 0 done, record D19 (auto-update, deferred) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/PLAN.md's Phase 0 section and its "Done when"/Verification entries still described the original Postgres+RLS, docker-compose, auto-redeploying design — none of which is what actually got built and deployed. Marks it done, states the two deliberate deviations plainly (SQLite not Postgres+RLS, manual redeploy not automatic), and separates what's actually verified (login persists a session, checked by scripts/smoke-test.sh after a real bug) from what nobody has tried yet (PWA home-screen install). docs/DECISIONS.md D19 records the auto-update investigation: the real fix for Unraid's own "not available" update-check badge (a third, independent place the D17 self-signed cert needed trusting — Unraid's PHP update checker doesn't share Docker's own certs.d), the structural reason "up to date" can't be fully trusted on this host even after that fix (CI builds on the same dockerd the app runs on, so the local :latest tag is always fresh regardless of whether the container was recreated from it), the failed first Watchtower attempt (stale image, wrong Docker API version) and why CI-triggers-a-redeploy was rejected again rather than reconsidered. "Deliberately deferred" gets three new entries: finishing Watchtower, migrating Gitea/CI to a dedicated VM (raised as the real fix for the root cause D19 kept running into), and persisting the accumulated host-local trust files across a reboot. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01R2ZKeWkZV7ehf7fivrAkkG --- deploy/README.md | 18 ++++++++++++--- docs/DECISIONS.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++ docs/PLAN.md | 41 ++++++++++++++++++++++++-------- 3 files changed, 106 insertions(+), 12 deletions(-) diff --git a/deploy/README.md b/deploy/README.md index 80fdc5c..892b5be 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -154,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 -CI) and the `import_inbox` USB-watch bind mount are both Phase 1+ concerns — nothing in the schema -uses them yet. +- Backups (`docs/PLAN.md` calls for a systemd timer running `restic` against `/data`, independent + of CI) and the `import_inbox` USB-watch bind mount — both Phase 1+ concerns, nothing in the + 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). diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index fdac4a5..f94a661 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -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. diff --git a/docs/PLAN.md b/docs/PLAN.md index f85e75e..c61afe3 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -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 -`/healthz` and OpenAPI, Alembic baseline (users/invites/sessions **with RLS policies from the first -migration**), SvelteKit static SPA shell with login, manifest + service worker + precache passing -Lighthouse installability, VAPID keypair, Caddy, compose, Gitea Actions green, image in the registry, -deployed. -*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. +**Phase 0 — Scaffolding.** ✅ **Done, with two deliberate deviations from this original description — +both recorded in `docs/DECISIONS.md`, not silent drift.** Monorepo, `uv`/`ruff`/`mypy --strict`, +FastAPI skeleton with `/healthz` and OpenAPI, Alembic baseline (users/invites/sessions), SvelteKit +static SPA shell with login, manifest + service worker, Caddy, Gitea Actions green, image in the +registry, deployed to a real Unraid host behind real HTTPS. + +- **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 -a redeployed container; `docker compose logs` shows migrations applied. +**Phase 0 — done, verified for real, not just assumed from CI going green:** `curl https://host/healthz` +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. -- 2.54.0