Kiosk guide never says HTTPS is required: plain http:// turns off the display's offline page cache #98

New Issue

2026-10-14T03:57:33Z

ekklesia-bot commented

2026-10-14 03:57:33 +00:00

What's missing

deploy/display-kiosk.md only ever shows https://<api-hostname>/display/... (lines 28, 31, 43, 75). It never says HTTPS is required, or what a display loses without it. Stage 0's real-machine acceptance ran a kiosk at http://192.168.68.75:3000/display/signage, a plain-HTTP LAN address, which is an easy setup to fall into for a church LAN or a test rig.

On such an origin the browser does not treat the page as a secure context. Two things the guide's outage table (line 110) and its "Offline cold start" note (lines 117–121) depend on are then missing:

Capability	`https://` or `localhost`	plain `http://` on a LAN address
Platform display service worker (caches the shell and module code, ADR 0043)	yes	no: `navigator.serviceWorker` is absent; `registerDisplayServiceWorker` quietly returns `false` (`surfaces/shell/src/display/offline-status.ts`)
Cache Storage (where Signage keeps image bytes, Signage ADR 0006)	yes	no: `window.caches` is undefined
IndexedDB	yes	yes

Verified in Chromium 151 over CDP: http://192.168.68.75:<port>/ gave isSecureContext:false, caches:false, serviceWorker:false; http://127.0.0.1:<port>/ gave all three true.

What a plain-HTTP display actually does

A running display survives an outage. Since Zayin/Signage 5f52334 (merged in Signage #18), Signage keeps image bytes in page memory when Cache Storage is missing, so the outage table's "keeps playing what it has cached" holds. Before that fix it did not, and the kiosk froze on one image.
A reload or reboot while the server is unreachable shows nothing useful. With no service worker, not even the shell page can be loaded from cache: the display page is served Cache-Control: no-store and its script no-cache (apps/api/src/display-host-assets.ts, module-display-routes.ts), so the browser's HTTP cache cannot stand in. As a result the screen gets the browser's own error page rather than the guide's "short message and retries on its own". Once the server is reachable it recovers when Chromium or systemd reloads it, but the guide's described behaviour doesn't apply.
Nothing tells the operator. The registration failure is deliberately silent (it's an enhancement), and the Display devices panel shows no hint.

Suggested change (docs)

In What the screen needs, add something like:

HTTPS. Open the display over https://. On plain http:// (other than localhost) the browser turns off the offline features a display relies on: the page and module code are not cached, so a screen restarted during an outage cannot come back until the server does. A screen that is already running still keeps playing through an outage.

Also consider:

A footnote on the outage table's "Machine reboots" row about the HTTP case.
Optionally, a pnpm doctor or Dashboard hint when EKKLESIA_IDENTITY_BASE_URL / the dashboard origin is http:// on a non-loopback host. That's a product decision, so it's not proposed as part of the doc change.

Out of scope / not checked

Whether http://<hostname> treated as secure through Chromium's --unsafely-treat-insecure-origin-as-secure flag is something the guide should mention as a test-rig workaround. It is not a production recommendation.

Found by Claude while investigating the Stage 0 offline-playback failure (found-by-claude).

## What's missing `deploy/display-kiosk.md` only ever shows `https://<api-hostname>/display/...` (lines 28, 31, 43, 75). It never says HTTPS is *required*, or what a display loses without it. Stage 0's real-machine acceptance ran a kiosk at `http://192.168.68.75:3000/display/signage`, a plain-HTTP LAN address, which is an easy setup to fall into for a church LAN or a test rig. On such an origin the browser does not treat the page as a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts). Two things the guide's outage table (line 110) and its "Offline cold start" note (lines 117–121) depend on are then **missing**: | Capability | `https://` or `localhost` | plain `http://` on a LAN address | |---|---|---| | Platform display service worker (caches the shell and module code, ADR 0043) | yes | **no**: `navigator.serviceWorker` is absent; `registerDisplayServiceWorker` quietly returns `false` (`surfaces/shell/src/display/offline-status.ts`) | | Cache Storage (where Signage keeps image bytes, Signage ADR 0006) | yes | **no**: `window.caches` is undefined | | IndexedDB | yes | yes | Verified in Chromium 151 over CDP: `http://192.168.68.75:<port>/` gave `isSecureContext:false, caches:false, serviceWorker:false`; `http://127.0.0.1:<port>/` gave all three `true`. ## What a plain-HTTP display actually does - **A running display survives an outage.** Since Zayin/Signage `5f52334` (merged in Signage #18), Signage keeps image bytes in page memory when Cache Storage is missing, so the outage table's "keeps playing what it has cached" holds. Before that fix it did not, and the kiosk froze on one image. - **A reload or reboot while the server is unreachable shows nothing useful.** With no service worker, not even the shell page can be loaded from cache: the display page is served `Cache-Control: no-store` and its script `no-cache` (`apps/api/src/display-host-assets.ts`, `module-display-routes.ts`), so the browser's HTTP cache cannot stand in. As a result the screen gets the browser's own error page rather than the guide's "short message and retries on its own". Once the server is reachable it recovers when Chromium or systemd reloads it, but the guide's described behaviour doesn't apply. - **Nothing tells the operator.** The registration failure is deliberately silent (it's an enhancement), and the Display devices panel shows no hint. ## Suggested change (docs) In **What the screen needs**, add something like: > **HTTPS.** Open the display over `https://`. On plain `http://` (other than `localhost`) the browser turns off the offline features a display relies on: the page and module code are not cached, so a screen restarted during an outage cannot come back until the server does. A screen that is already running still keeps playing through an outage. Also consider: - A footnote on the outage table's "Machine reboots" row about the HTTP case. - Optionally, a `pnpm doctor` or Dashboard hint when `EKKLESIA_IDENTITY_BASE_URL` / the dashboard origin is `http://` on a non-loopback host. That's a product decision, so it's not proposed as part of the doc change. ## Out of scope / not checked Whether `http://<hostname>` treated as secure through Chromium's `--unsafely-treat-insecure-origin-as-secure` flag is something the guide should mention as a test-rig workaround. It is not a production recommendation. --- _Found by Claude while investigating the Stage 0 offline-playback failure (`found-by-claude`)._

ekklesia-bot referenced this issue

2026-10-14 03:58:18 +00:00

docs(claude): file an issue for what you find outside the task #99

ekklesia-bot added the found-by-claude label 2026-10-14 04:05:26 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Zayin/Ekklesia#98