GRI-1876: deployment note, one server behind a reverse proxy, many campuses #105

Merged
vivy merged 1 commit from docs/GRI-1876-deployment-note into dev 2026-11-10 05:37:53 +00:00
Member

Summary

GRI-1876 / signage #28: rewrites plan/operations/deployment.md as the real
deployment note the product owner deploys from alone — one server on the
main campus behind his reverse proxy, clients on several campuses over
wss://. Every command was checked against the code in dev; most were run
for real on this build host (server booted against a real Postgres,
first-user setup, login, media/URL upload, playlist create/assign, and the
PDF refusal all verified end to end).

Covers, with real config and commands: server install (Compose + systemd,
the actual config.toml keys and their env overrides), the reverse proxy
(nginx/Caddy/Traefik, the WebSocket upgrade headers, and why
[enrolment] trusted_proxies is not optional), first-user setup and login
(including the Secure-cookie-needs-HTTPS gotcha), client rollout (the
.deb, pointing it at a server, device admission order), campus IP rules,
content (URL works today, PDF does not yet), playlists, and
backup/upgrade/health.

Two real gaps turned up while verifying, handled rather than hidden:

  • Fixed: scripts/package-client-deb.sh built and shipped
    renderer_spike — crates/client/Cargo.toml's own [[bin]] comment
    already names grimoirix-signage-client (the real client) as the binary
    the .deb should install. Now builds and packages the real binary;
    verified by extracting the rebuilt .deb and running it — it reports its
    real start-up error instead of starting the Phase 0 spike.
    packaging/client-deb/control.in's description updated to match.
  • Filed, not fixed here: #104 —
    POST /media refuses every PDF (unsupported_media_type), blocking this
    note's own "done when". The note documents the URL content path (works
    today) and flags PDF as pending #104.
  • Flagged, not merged here: device approval and campus IP auto-approve
    are only wired to a frontend mock today (USE_MOCK = true). The real
    routes are in PR #103
    (signage #13, open, by nyssa). The note gives the direct-SQL path that
    works today, plus the exact REST calls to switch to once #103 lands —
    read from that branch's real code, not guessed.

Also fixed a stale claim in packaging/server/README.md ("the server does
not connect to Postgres yet, forge #9 still open") — #9 closed a while ago.

Test plan

  • ./scripts/local-gates.sh — every gate passed (fmt, clippy, test incl.
    --doc, cargo deny, frontend check + build).
  • Built the real client binary and the fixed .deb; extracted and ran
    it — reports the real "no server is configured" error.
  • Built the server binary; ran it against a real disposable Postgres on
    this host; verified /health, POST /setup, POST /session,
    POST /media/url, POST /media with a PDF (refused as documented)
    and a PNG (accepted), POST /playlists, PUT /playlists/{id}/items.
  • docker compose config renders the Compose file cleanly (daemon
    access still not available on this host/account — same limitation the
    previous version of this doc already noted).
  • Real docker compose up end to end — needs docker group membership
    on this host (flagged to Aetherius previously, still open).
## Summary GRI-1876 / signage #28: rewrites `plan/operations/deployment.md` as the real deployment note the product owner deploys from alone — one server on the main campus behind his reverse proxy, clients on several campuses over `wss://`. Every command was checked against the code in `dev`; most were run for real on this build host (server booted against a real Postgres, first-user setup, login, media/URL upload, playlist create/assign, and the PDF refusal all verified end to end). Covers, with real config and commands: server install (Compose + systemd, the actual `config.toml` keys and their env overrides), the reverse proxy (nginx/Caddy/Traefik, the `WebSocket` upgrade headers, and why `[enrolment] trusted_proxies` is not optional), first-user setup and login (including the `Secure`-cookie-needs-HTTPS gotcha), client rollout (the `.deb`, pointing it at a server, device admission order), campus IP rules, content (URL works today, PDF does not yet), playlists, and backup/upgrade/health. Two real gaps turned up while verifying, handled rather than hidden: - **Fixed:** `scripts/package-client-deb.sh` built and shipped `renderer_spike` — `crates/client/Cargo.toml`'s own `[[bin]]` comment already names `grimoirix-signage-client` (the real client) as the binary the `.deb` should install. Now builds and packages the real binary; verified by extracting the rebuilt `.deb` and running it — it reports its real start-up error instead of starting the Phase 0 spike. `packaging/client-deb/control.in`'s description updated to match. - **Filed, not fixed here:** [#104](https://git.grimoirix.org/Grimoirix/grimoire-of-digital-signage/issues/104) — `POST /media` refuses every PDF (`unsupported_media_type`), blocking this note's own "done when". The note documents the URL content path (works today) and flags PDF as pending #104. - **Flagged, not merged here:** device approval and campus IP auto-approve are only wired to a frontend mock today (`USE_MOCK = true`). The real routes are in [PR #103](https://git.grimoirix.org/Grimoirix/grimoire-of-digital-signage/pulls/103) (signage #13, open, by `nyssa`). The note gives the direct-SQL path that works today, plus the exact REST calls to switch to once #103 lands — read from that branch's real code, not guessed. Also fixed a stale claim in `packaging/server/README.md` ("the server does not connect to Postgres yet, forge #9 still open") — #9 closed a while ago. ## Test plan - [x] `./scripts/local-gates.sh` — every gate passed (fmt, clippy, test incl. `--doc`, `cargo deny`, frontend `check` + `build`). - [x] Built the real client binary and the fixed `.deb`; extracted and ran it — reports the real "no server is configured" error. - [x] Built the server binary; ran it against a real disposable Postgres on this host; verified `/health`, `POST /setup`, `POST /session`, `POST /media/url`, `POST /media` with a PDF (refused as documented) and a PNG (accepted), `POST /playlists`, `PUT /playlists/{id}/items`. - [x] `docker compose config` renders the Compose file cleanly (daemon access still not available on this host/account — same limitation the previous version of this doc already noted). - [ ] Real `docker compose up` end to end — needs `docker` group membership on this host (flagged to Aetherius previously, still open).
GRI-1876: deployment note, one server behind a reverse proxy, many campuses
Some checks failed
CI / the pre-push hook (pull_request) Successful in 5s
CI / cargo fmt (pull_request) Successful in 5s
CI / cargo deny (pull_request) Successful in 44s
CI / cargo deny advisories (pull_request) Failing after 44s
CI / repository boundary (pull_request) Successful in 6s
CI / cargo clippy (pull_request) Successful in 9m50s
CI / cargo test (pull_request) Successful in 11m1s
CI / frontend-web (pull_request) Successful in 9m44s
CI / CI (pull_request) Successful in 3s
CI / Notify gate failed (pull_request) Has been skipped
f45b8a13d0
vivy merged commit 2cfb83a0a0 into dev 2026-11-10 05:37:53 +00:00
vivy deleted branch docs/GRI-1876-deployment-note 2026-11-10 05:37:53 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grimoirix/grimoire-of-digital-signage!105
No description provided.