docs: mark Phase 0 done, record D19 (auto-update, deferred)
CI / Repo hygiene (pull_request) Successful in 2s
CI / Web (lint, typecheck, build) (pull_request) Successful in 13s
CI / Migrations reversible (pull_request) Successful in 6s
CI / API (lint, types, tests) (pull_request) Successful in 54s

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R2ZKeWkZV7ehf7fivrAkkG
This commit is contained in:
2026-09-21 22:57:26 -04:00
co-authored by Claude Sonnet 5
parent 8c88748f50
commit 244fe525dd
3 changed files with 106 additions and 12 deletions
+59
View File
@@ -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.