feat(trmnl): deploy the headless dashboard renderer #483
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: konairius/homelab#483
Reference in New Issue
Block a user
Phase 4. Screenshots the HA e-ink dashboard, dithers it to 16 greys, and hands it to Terminus — which the panel then polls.
Pairs with homeassistant#210 (the dashboard itself).
Runs standalone, not as an add-on
Upstream ships this as an HA add-on; ours is a plain HA container with no Supervisor. Standalone works because the app prefers
HOME_ASSISTANT_URL/ACCESS_TOKENenv vars over/data/options.jsonand authenticates with an ordinary long-lived token.SUPERVISOR_TOKENis deliberately left unset — it only flips an internalisAddOnflag and would switch the app to add-on behaviour.The direction of travel is backwards from what you'd assume
With the
byos-hanamiwebhook inuridelivery mode the renderer does not push image bytes. It POSTs a URL pointing at its own/output/<file>endpoint, and Terminus fetches the image back from it.That's why this lives in the
trmnlnamespace: the fetch is intra-namespace and already permitted bydefault-deny-ingress. Splitting the two across namespaces would have needed a new policy for a dependency that's easy to miss until screens silently stop updating.Fully declarative — no clicks
Schedules are a JSON file at
/data/schedules.jsonthat the app re-reads every 60 s, so the entire schedule is reviewable in git rather than typed into the app's web UI:An init container splices the BYOS tokens into the ConfigMap template with
jq, notsed— the tokens are JWTs going into a JSON string, andsedcorrupts on any character it treats as special. Verified with a token containing/,+and&.Render interval is 1 min, deliberately ahead of the device poll, so the panel never fetches a half-written image.
No HTTP in the init container, on purpose. The app exposes an
/api/byos/loginproxy that trades a Terminus username+password for these tokens — but that would mean shipping the Terminus password into the cluster and making every pod start depend on a network call. Stock Terminus disables session expiry and issues effectively permanent tokens, so they're minted once out of band and kept in OpenBao. The password never enters the cluster.Reachability — fixed after review
The first revision pointed
HOME_ASSISTANT_URLathttp://ha.renner.uno:8123, which is unusable from inside a pod. That name is served by thehome-assistant-bgpLoadBalancer and is not backed by an Ingress, so CoreDNS'sk8s_gatewaydelegation doesn't intercept it — a pod gets the real external address (10.2.99.87) and hairpins off the LB. This cluster has hit exactly that before with exactly that Service;openbao/rotation/home-assistant.yamlsays so outright.Now uses
home-assistant-bgp.home-assistant.svc.cluster.local:8123(verified live: ClusterIP10.96.79.213, 8123/TCP), plus a companion CNP ingress rule — thehome-assistantnamespace's default-deny had no rule admittingtrmnlpods on 8123, so the URL fix alone would still have been dropped. Scoped to the renderer's pod label rather than the whole namespace, since Terminus shares that namespace and has no business reaching HA.Four things that would fail quietly
/datais required. The app picks its data directory by testing whether/dataexists — with nothing mounted it silently falls back to/app/datainside the container, so schedules and rendered output vanish on restart.Verified against the running systems
model_idis the integer 1, not the name"v2".GET /api/screensreturnsmodel_idas a number, andGET /api/modelsgives TRMNL X asid: 1. Upstream's example valueog_1bitmatches no model on this server (the 2-bit OG model here isid 11, name og_plus). The earlier "unverified" caveat is resolved — a wrong value here would have meant a 422 on every push and a permanently blank panel./healthis part of the image's published contract — its Dockerfile declaresHEALTHCHECK ... curl -f http://localhost:10000/health. Hence HTTP probes here, whereterminus.yamluses TCP-only.--no-sandbox --disable-setuid-sandbox --no-zygote --disable-dev-shm-usagein its ownPUPPETEER_ARGS. That last flag is also why no/dev/shmemptyDir is mounted.homelab/apps/trmnl/rendererholdsHA_ACCESS_TOKEN(dedicated token, verified200against the HA API),BYOS_ACCESS_TOKENandBYOS_REFRESH_TOKEN(verified200against Terminus/api/models).The image is arch-suffixed (
trmnl-ha-amd64) because upstream publishes no multi-arch manifest. Pinned and not enrolled in image automation — a bad bump surfaces as a corrupted or blank panel rather than a failed rollout. Rationale recorded in the image-automation README alongside Terminus's.🤖 Generated with Claude Code
Phase 4. Screenshots the Home Assistant e-ink dashboard, dithers it to 16 greys and hands it to Terminus, which the panel then polls. Upstream ships this as a Home Assistant add-on. Ours is a plain HA container with no Supervisor, so it runs standalone — viable because the app prefers HOME_ASSISTANT_URL/ACCESS_TOKEN env vars over /data/options.json and authenticates with an ordinary long-lived token. SUPERVISOR_TOKEN is deliberately left unset: it only flips an internal isAddOn flag and would switch the app to add-on behaviour. The non-obvious part is the direction of travel. With the byos-hanami webhook in `uri` delivery mode the renderer does NOT push image bytes — it POSTs a URL pointing at its own /output/<file> endpoint and TERMINUS FETCHES THE IMAGE BACK. That is why this lives in the trmnl namespace: the fetch is intra-namespace and already permitted by default-deny-ingress. Splitting the two across namespaces would have needed a new policy for a dependency that is easy to miss. Fully declarative, no clicks. Schedules are a JSON file at /data/schedules.json which the app re-reads every 60s, so the whole schedule — viewport 1872x1404, floyd-steinberg at bitDepth 4, the trmnl-eink theme, the dashboard path — is reviewable in git rather than typed into the app's web UI. An init container splices the BYOS tokens into the ConfigMap template with jq; jq rather than sed because the tokens are JWTs going into a JSON string and sed would corrupt on any character it treats as special (verified with a token containing / + &). No HTTP in the init container on purpose. The app exposes a /api/byos/login proxy that trades a Terminus username+password for these tokens, but using it would mean shipping the Terminus PASSWORD into the cluster and making every pod start depend on a network call. Stock Terminus disables session expiry and issues effectively permanent tokens, so they are minted once out of band and kept in OpenBao; the password never enters the cluster. Three things that are load-bearing and would fail quietly otherwise: * The PVC at /data is REQUIRED. The app picks its data directory by testing whether /data exists — with nothing mounted it silently falls back to /app/data in the container, so schedules and rendered output vanish on restart and the panel goes blank. * The Service is ClusterIP with NO Ingress. The app's web UI on this port has no authentication whatsoever, per upstream, so it must not be routable from the LAN. * The memory limit is 2Gi, not the 512Mi upstream's troubleshooting note suggests. The app's own watchdog restarts it past 900MB but only measures its OWN rss — Chromium is a separate process, and it is rendering a 1872x1404 page. The image is arch-suffixed (trmnl-ha-amd64); upstream publishes no multi-arch manifest. Pinned and not enrolled in image automation, since a bad bump here surfaces as a corrupted or blank panel rather than a failed rollout — rationale recorded in the image-automation README alongside Terminus's. PREREQUISITE: homelab/apps/trmnl/renderer must be seeded in OpenBao with HA_ACCESS_TOKEN, BYOS_ACCESS_TOKEN and BYOS_REFRESH_TOKEN before this merges, or the ExternalSecret never syncs, the init container blocks, and the trmnl Kustomization fails its wait. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>🤖 Automated review — model
CLI default(complexity: complex), commit7e2a439b9e9a5193b3537ffc72c8bd42251c161e.Summary
Adds the standalone TRMNL/Home-Assistant screenshot renderer to the
trmnlnamespace: a Deployment (jq-based init container templatingschedules.json, Chromium-based renderer container), its PVC, and an ExternalSecret for the HA/BYOS tokens. The manifests are unusually well commented and internally consistent (Service/webhook URLs, ExternalSecret key names, and container env all line up correctly). However, the renderer is pointed at Home Assistant's public/LAN hostname, which this repo's own prior work already documented as unreachable from inside the cluster — as written, the renderer cannot reach HA at all.🔴 Blocking
kubernetes/apps/trmnl/renderer.yaml:271—HOME_ASSISTANT_URLis set tohttp://ha.renner.uno:8123. That hostname is served by thehome-assistant-bgpLoadBalancer Service withexternalTrafficPolicy: Local(kubernetes/apps/home-assistant/bgp-service.yaml), advertised over Cilium BGP to the LAN — it is not backed by an Ingress, so CoreDNS'sk8s_gatewaydelegation does not intercept it (kubernetes/infrastructure/coredns-config/configmap.yaml:8-14, "Names not backed by an in-cluster Ingress fall through ... to the UDM ... which serves the split-horizon renner.uno zone"). A pod resolvingha.renner.unotherefore gets the real external LB IP (10.2.99.87), not an in-cluster address.This repo has already hit exactly this failure mode for this exact Service:
kubernetes/infrastructure/openbao/rotation/home-assistant.yaml:17-22runs a CronJob that also needs to reach HA from a pod, and its comment states outright: "Reachability: HA :8123 ... via the home-assistant-bgp Service ClusterIP ... The public name is unusable from a pod (ingress-LB hairpin)." That job usesws://home-assistant-bgp.home-assistant.svc.cluster.local:8123/api/websocketinstead. The identical language ("hairpins off the ... LB from a pod") recurs ingitea/networkpolicy.yaml,woodpecker/networkpolicy.yaml, andhome-assistant-ns.yaml:349— this is an established, repeatedly-confirmed constraint of this cluster, not a hypothetical.As written, the renderer's every screenshot attempt will fail to connect to HA — the schedule will fire every minute and error, and the panel will never get real content. This is the core function of the PR.
Fixing the hostname isn't sufficient on its own, either:
kubernetes/infrastructure/network-policies/home-assistant-ns.yaml'sdefault-deny-ingress(lines 1-197) has no rule permittingtrmnl-namespace pods to reach HA on:8123— the only port-8123 ingress rule ishome-assistant-rotator-ingress, scoped toopenbao/secret-rotatorpods specifically (lines 356-374). Switching tohome-assistant-bgp.home-assistant.svc.cluster.local:8123needs a companion ingress rule in that file (matching the rotator's shape, scoped to the renderer's pod label) before traffic would actually get through.🟡 Suggestions
model_id: "v2"field in the BYOS config (renderer.yaml:156) is called out in the PR description as unverified against Terminus's actual API contract (name vs. numeric id). Worth resolving before merge if this is quick to check against the running Terminus instance, since a 422 here would be another quiet failure mode alongside the HA-reachability one above.🟢 Nits
kubernetes/infrastructure/post-crds/velero-schedules.yaml:296-298— thetrmnl-dailySchedule's comment enumerates the PVCs it covers ("terminus-data ... and terminus-valkey-data") but wasn't updated to mention the newtrmnl-renderer-dataPVC. Functionally it's still backed up (the schedule selectsincludedNamespaces: [trmnl]+ all PVCs minus the CNPG-labelled one, so the new PVC is included automatically), but the comment now undersells what's covered.Tests
No automated coverage exists for this path —
kubernetes/e2e-test.shdoesn't referencetrmnlorhome-assistantat all, so nothing in CI would have caught the HA-reachability issue above; it would only surface at runtime (render schedule firing and failing every minute, or the panel staying blank). Given the PR body already documents three other "fails quietly" modes it planned for, it'd be worth adding a fourth note (and ideally a gatus check or similar, matching the pattern used elsewhere in this repo for LB-hairpin-prone paths) once the HOME_ASSISTANT_URL fix lands.Recommendation
Request changes — 1 blocking issue.
🤖 Automated review — model
CLI default(complexity: complex), commitb6ada58b7ade5cb40a7e47515864fa425bd0eca6.Summary
Adds the standalone TRMNL/HA headless renderer (Deployment + ConfigMap + PVC + ExternalSecret + Service) to the
trmnlnamespace, plus the supporting CiliumNetworkPolicy (renderer → HA:8123), an image-automation exclusion, and a comment update noting the new PVC rides the existing namespace-wide Velero schedule. I traced the intra-namespace (Terminus ↔ renderer) and cross-namespace (renderer → Home Assistant) network paths against the actualCiliumNetworkPolicyobjects already in the repo, cross-checked Service/ConfigMap/Secret names end-to-end, and diffed the securityContext/probe/resource choices against the siblingterminus.yamlDeployment for consistency. No blocking issues found — the design holds together and matches what the PR body claims. A few points are worth a second look before or shortly after merge, mostly around assumptions about the third-party image's runtime behaviour that this repo can't verify statically.🟡 Suggestions
kubernetes/apps/trmnl/renderer.yaml:307-320—livenessProbe/readinessProbehitGET /healthon the renderer. That's an assumption about the upstreamtrmnl-ha-amd64image's route set that isn't verified anywhere in the diff or repo. Contrast withkubernetes/apps/trmnl/terminus.yaml:91-94, where the same author deliberately used TCP-only probes with the comment "Terminus exposes no documented health endpoint... Tighten to an HTTP GET once the route set is confirmed against the running app." If/healthdoesn't exist (or 404s while the app is otherwise up), the liveness probe willCrashLoopBackOffthe renderer repeatedly — a much noisier failure than the "fails quietly" risks the PR body calls out for the other three gotchas. Worth confirming against the running container's logs/routes on first deploy, or falling back to a TCP probe liketerminus.yamldoes until confirmed.kubernetes/apps/trmnl/renderer.yaml:333-336— the renderer container runs withallowPrivilegeEscalation: falseandcapabilities: drop: ["ALL"]. Headless Chromium (which this image wraps, per the PR description) commonly needs either--no-sandboxbaked into its launch flags or extra capabilities to start its own sandbox under a restrictedsecurityContext; a hard failure here would show up as the app process staying up while every render fails, or the process crashing outright. Not something I can confirm from the checkout — worth watching pod logs after first render cycle.model_id: the body's "Unverified" section saysmodel_id: "v2"and flags uncertainty about whether Terminus wants a name or a numeric id there. The actual ConfigMap (kubernetes/apps/trmnl/renderer.yaml:116-121) ships"model_id": 1(integer) with a comment claiming this was already confirmed against the running server (GET /api/screens). If that confirmation is accurate the "Unverified" caveat in the PR description is stale and should be dropped so a future reader doesn't re-litigate a question the code already answered; if it's not accurate, the code comment is overclaiming. Worth a quick pass to reconcile the two before merge.🟢 Nits
None beyond the above — the manifest is unusually well-commented and the two cross-file claims I could check (network policy reachability, PVC inclusion in the Velero namespace-wide schedule) both held up against the actual policy/schedule objects.
Tests
No test suite applies to Kubernetes manifests in this repo beyond
.woodpecker/ci-manifests-test.yml'skustomize-buildstep, which validates that every kustomization tree still builds statically (resource references resolve, YAML is well-formed) — it doesn't touch a cluster or exercise runtime behavior. I wasn't able to runkubectl kustomizelocally in this sandbox to double-check the build (command was blocked by the environment's permission gate), so I verified the wiring by hand instead:kustomization.yamllists both new files, theService/ConfigMap/Secretnames referenced by theDeploymentall exist with matching names, and the new PVC (trmnl-renderer-data) has nocnpg.io/clusterlabel so it's correctly swept into the existing namespace-widetrmnl-dailyVelero schedule without needing an edit there. The runtime-only risks (health endpoint path, Chromium sandboxing under the restricted securityContext, whether Terminus's BYOS endpoint actually accepts this payload shape) are inherently untestable from a static checkout and are the PR's own explicitly-flagged unknowns; that's a reasonable scope boundary given the "prerequisite: seed OpenBao first" gate already blocks accidental rollout.Recommendation
Looks reasonable — no blocking issues; comments above are optional.
🤖 Automated review — model
CLI default(complexity: complex), commita79a5417e3c5b7df7f10d6ad60d2bd0fb19072e0.Summary
Adds the TRMNL headless renderer (Deployment, ConfigMap-templated schedule, PVC, ExternalSecret) plus the supporting network policy and backup-schedule wiring. The manifests are careful and internally consistent — I cross-checked every cross-file claim (Terminus's Service port, the HA pod's real container port, the
trmnlnamespace's default-deny-ingress, the absence of any default-deny-egress intrmnl, the velero PVC selector, thealpine-jqimage precedent, and theCiliumNetworkPolicyscoping pattern used elsewhere inhome-assistant-ns.yaml) and all of them check out against the actual checked-out state. One real gap: the "fully declarative, no clicks" schedule-editing story doesn't hold together as described.🔴 Blocking
kubernetes/apps/trmnl/renderer.yaml:112-114(ConfigMap comment) claims: "The app re-reads schedules.json every 60 s, so edits here take effect without a restart once the init container has rewritten it." This is not how it will behave. Therender-scheduleinit container (lines 225-259) only runs when the pod is created or restarted — it does not re-run when thetrmnl-renderer-scheduleConfigMap changes. This repo's own Reloader deployment (kubernetes/infrastructure/reloader/helmrelease.yaml:5-7) states explicitly that it "Acts ONLY on workloads carrying its annotations… it never blanket-reloads un-annotated resources," and thetrmnl-rendererDeployment carries noconfigmap.reloader.stakater.com/reload(or equivalent) annotation. There's also noconfigMapGeneratorinkubernetes/apps/trmnl/kustomization.yaml:1-21to hash-suffix the ConfigMap and force a rollout on change — it's a plain resource, so Flux will update the ConfigMap object in place without touching the Deployment.Net effect: editing
schedules.template.jsonin git (e.g. changingdashboard_path,cron, orinterval_minutes) will silently not take effect until someone manually restarts thetrmnl-rendererpod. That directly undercuts the PR's stated design goal ("fully declarative — no clicks… entire schedule is reviewable in git") and is exactly the class of quiet failure the rest of this PR is unusually careful to call out (compare the "Four things that would fail quietly" section in the PR body, which doesn't mention this one).Fix: add
configmap.reloader.stakater.com/reload: trmnl-renderer-scheduleto the Deployment'smetadata.annotations(mirroring the existingsecret.reloader.stakater.com/reloadpattern onhome-assistant's Deployment), or correct the comment to say a manual/triggered pod restart is required after a schedule edit.🟡 Suggestions
kubernetes/apps/trmnl/renderer.yaml:129-130: the schedule template sets both"cron": "* * * * *"and"interval_minutes": 1. If the renderer treats these as two independent triggers rather than cron being authoritative when set, this could double-fire renders every minute. Not verifiable from this repo (app internals aren't vendored here) — worth a quick check against the running instance's logs after this deploys, same diligence already applied elsewhere in this PR tomodel_idand/health.🟢 Nits
None beyond the above.
Tests
No automated tests apply here (this is a pure Kubernetes-manifest change in a GitOps repo; correctness is verified by reading manifests against the live cluster state, which is what this review did). The PR body documents that the author verified several externally-dependent facts against running systems (OpenBao secrets present, HA token returns 200, BYOS tokens valid against Terminus,
model_idsemantics,/healthroute) — these aren't independently checkable from the checkout and are taken on trust given the specificity of the verification described. Everything that is checkable from the repo (service names/ports, network policy scoping, PVC backup coverage, image-automation opt-out rationale, ConfigMap/volume mount wiring) was verified directly and is correct.Recommendation
Request changes — 1 blocking issue.