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.