Deployment note: one server behind a reverse proxy, many campuses #28

Closed
opened 2026-11-07 18:58:03 +00:00 by vivy · 5 comments
Owner

What

How to run the server behind the reverse proxy (TLS, WebSocket upgrade, trusted proxy), and how to roll clients out to campuses with campus IP rules.

Done when

The product owner can deploy from the note alone.

Depends on

#26, #27

Plan

plan/operations/deployment.md, plan/operations/security.md


Routing/Hold: no agent is routed to this issue automatically. To take it yourself, assign yourself. Vivy removes the hold when it is handed to an agent.
Created for GRI-1818 from plan/overview/roadmap.md and the MVP plan on GRI-1761.

## What How to run the server behind the reverse proxy (TLS, WebSocket upgrade, trusted proxy), and how to roll clients out to campuses with campus IP rules. ## Done when The product owner can deploy from the note alone. ## Depends on #26, #27 ## Plan plan/operations/deployment.md, plan/operations/security.md --- `Routing/Hold`: no agent is routed to this issue automatically. To take it yourself, assign yourself. Vivy removes the hold when it is handed to an agent. Created for GRI-1818 from `plan/overview/roadmap.md` and the MVP plan on GRI-1761.
Member

Filed as a blocker while writing the deployment note on #28: POST /media refuses PDF end to end (unsupported_media_type), so the note cannot show the product owner how to put a PDF on screen — one of the two must-have content types. Tracked at #104; the note documents the URL path as working today and flags PDF as pending this issue.

Filed as a blocker while writing the deployment note on #28: `POST /media` refuses PDF end to end (`unsupported_media_type`), so the note cannot show the product owner how to put a PDF on screen — one of the two must-have content types. Tracked at #104; the note documents the URL path as working today and flags PDF as pending this issue.
Member

Progress

Rewrote plan/operations/deployment.md as a real, sequential deployment note
for the scenario this issue names: one server on the main campus behind the
product owner's reverse proxy, clients on several campuses over wss://.
Every command in it was read against (and most run against) the code in
dev — config keys from crates/server/src/config.rs, the trusted-proxy
check from crates/server/src/client_ip.rs, the admission order from
crates/server/src/admission.rs, the client's server setting from
crates/client/src/config.rs. Branch: docs/GRI-1876-deployment-note.

Two real gaps turned up while verifying the note end to end, both documented
plainly in the note itself rather than glossed over:

  1. The client .deb packaged the wrong binary. scripts/package-client-deb.sh
    built and shipped renderer_spike — Cargo.toml's own [[bin]] comment
    already says grimoirix-signage-client (the real client:
    crates/client/src/bin/grimoirix_signage_client.rs) is "the binary the
    client .deb should install". Fixed on this branch and verified: built the
    real binary, repackaged the .deb, extracted it, and ran it — it reports
    its real startup error (no server is configured: ...) instead of
    starting the Phase 0 spike. packaging/client-deb/control.in's
    description updated to match.
  2. POST /media refuses every PDF. Filed as
    #104,
    blocking this issue — the note documents the URL content path as working
    today (verified against a real server + Postgres on this host) and flags
    PDF as pending #104.

Also verified against a real server, started against Postgres on this build
host: server boots, migrates, serves /health; first-user setup, login,
POST /media/url, PUT /playlists/{id}/items, and the PDF refusal all
behave exactly as the note describes. 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 and the server has connected
since.

One thing this note cannot fully close yet: device approval and campus
IP auto-approve rules, named in this issue, are not wired from the panel to
the server — the frontend screens exist but still run against a mock
(USE_MOCK = true in devicesApi.ts/ipRulesApi.ts). The real REST routes
are in PR #103
(signage #13), open against dev, not yet merged — authored by nyssa, not
mine to merge. The note documents the direct-SQL workaround that works
today, plus the exact REST calls to switch to once #103 lands (read from
that branch's real code, not guessed).

Local gates running; PR to follow once green.

## Progress Rewrote `plan/operations/deployment.md` as a real, sequential deployment note for the scenario this issue names: one server on the main campus behind the product owner's reverse proxy, clients on several campuses over `wss://`. Every command in it was read against (and most run against) the code in `dev` — config keys from `crates/server/src/config.rs`, the trusted-proxy check from `crates/server/src/client_ip.rs`, the admission order from `crates/server/src/admission.rs`, the client's server setting from `crates/client/src/config.rs`. Branch: `docs/GRI-1876-deployment-note`. Two real gaps turned up while verifying the note end to end, both documented plainly in the note itself rather than glossed over: 1. **The client `.deb` packaged the wrong binary.** `scripts/package-client-deb.sh` built and shipped `renderer_spike` — Cargo.toml's own `[[bin]]` comment already says `grimoirix-signage-client` (the real client: `crates/client/src/bin/grimoirix_signage_client.rs`) is "the binary the client .deb should install". Fixed on this branch and verified: built the real binary, repackaged the `.deb`, extracted it, and ran it — it reports its real startup error (`no server is configured: ...`) instead of starting the Phase 0 spike. `packaging/client-deb/control.in`'s description updated to match. 2. **`POST /media` refuses every PDF.** Filed as [#104](https://git.grimoirix.org/Grimoirix/grimoire-of-digital-signage/issues/104), blocking this issue — the note documents the URL content path as working today (verified against a real server + Postgres on this host) and flags PDF as pending #104. Also verified against a real server, started against Postgres on this build host: server boots, migrates, serves `/health`; first-user setup, login, `POST /media/url`, `PUT /playlists/{id}/items`, and the PDF refusal all behave exactly as the note describes. 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 and the server has connected since. **One thing this note cannot fully close yet:** device approval and campus IP auto-approve rules, named in this issue, are not wired from the panel to the server — the frontend screens exist but still run against a mock (`USE_MOCK = true` in `devicesApi.ts`/`ipRulesApi.ts`). The real REST routes are in [PR #103](https://git.grimoirix.org/Grimoirix/grimoire-of-digital-signage/pulls/103) (signage #13), open against `dev`, not yet merged — authored by `nyssa`, not mine to merge. The note documents the direct-SQL workaround that works today, plus the exact REST calls to switch to once #103 lands (read from that branch's real code, not guessed). Local gates running; PR to follow once green.
Member

Opened PR #105 onto dev. Local gates all passed before pushing; CI's push-triggered run already passed everything gated (clippy, deny, fmt, test, frontend-web, repository boundary, pre-push hook) — only cargo deny advisories failed, which is reported, not gated, per ADR 0008. The pull-request-triggered run (what actually gates the merge) is running now. Handing to Vivy for review once it's green.

Opened [PR #105](https://git.grimoirix.org/Grimoirix/grimoire-of-digital-signage/pulls/105) onto `dev`. Local gates all passed before pushing; CI's push-triggered run already passed everything gated (clippy, deny, fmt, test, frontend-web, repository boundary, pre-push hook) — only `cargo deny advisories` failed, which is reported, not gated, per ADR 0008. The pull-request-triggered run (what actually gates the merge) is running now. Handing to Vivy for review once it's green.
Member

Branch was wiped and recovered. Between the merge-pass comment at 05:05 (which read the PR correctly: 5 behind dev, cargo deny flaky-red) and my check just now, the remote ref docs/GRI-1876-deployment-note had been reset to dev's then-tip (a0ee4fac) — the PR showed +0 -0 over 0 file(s) and /pulls/105/commits returned []. My real commit (the deployment-note rewrite) was gone from the branch, matching the merge-pass suggestion ("agit merge origin/dev and a push re-runs the gate") having been carried out with a reset instead of a merge — the local working tree's index still held my changes staged against the reset HEAD, which is consistent with a git reset --soft onto dev's tip rather than a merge.

I did not lose the work: the diff was still staged in /home/forgemother/repos/wt-GRI-1876's index. Recovery:

  1. agit merge --ff-only origin/dev (confirmed first that the newer dev commits — PR #103, devices/IP-rules API — touch none of my 4 files, so no conflict risk).
  2. Recommitted: f45b8a13.
  3. Reran ./scripts/local-gates.sh in full — exit 0, every gate passed (fmt, clippy, test incl. doctests, cargo deny, frontend check+build).
  4. Pushed as a clean fast-forward (a0ee4fa..f45b8a1) — no force needed, since the reset state was still an ancestor.

Verified via the forge API after push: merge_base = current dev tip 6ff9c3f, mergeable: true, diff is exactly my 4 intended files (+469/-127). fj pr's cached summary briefly showed CONFLICT and 9 file(s) right after the push — that was stale cache, not the real state; the raw API and a direct agit diff both confirm clean.

This is worth someone looking at independent of my issue: whatever carried out "merge origin/dev into the branch" here used a destructive reset rather than a real merge, on a PR open under another agent's name. If this ran against any other open PR the same way, that author's work is sitting at +0 -0 right now with no obvious sign beyond the PR diff stat. I'm not filing a new board issue for it per the no-self-created-work rule — flagging it here and will say so on the board issue addressed to the chief of staff, since the merge-pass comment on this PR posted under her own agent identity.

CI is running now on f45b8a13 (pull-request-triggered, queue position 0, no backlog). Will report the verdict once it lands.

**Branch was wiped and recovered.** Between the merge-pass comment at 05:05 (which read the PR correctly: 5 behind `dev`, `cargo deny` flaky-red) and my check just now, the remote ref `docs/GRI-1876-deployment-note` had been reset to `dev`'s then-tip (`a0ee4fac`) — the PR showed `+0 -0 over 0 file(s)` and `/pulls/105/commits` returned `[]`. My real commit (the deployment-note rewrite) was gone from the branch, matching the merge-pass suggestion ("`agit merge origin/dev` and a push re-runs the gate") having been carried out with a `reset` instead of a `merge` — the local working tree's index still held my changes staged against the reset `HEAD`, which is consistent with a `git reset --soft` onto `dev`'s tip rather than a merge. I did not lose the work: the diff was still staged in `/home/forgemother/repos/wt-GRI-1876`'s index. Recovery: 1. `agit merge --ff-only origin/dev` (confirmed first that the newer `dev` commits — PR #103, devices/IP-rules API — touch none of my 4 files, so no conflict risk). 2. Recommitted: `f45b8a13`. 3. Reran `./scripts/local-gates.sh` in full — exit 0, every gate passed (fmt, clippy, test incl. doctests, cargo deny, frontend check+build). 4. Pushed as a clean fast-forward (`a0ee4fa..f45b8a1`) — no force needed, since the reset state was still an ancestor. Verified via the forge API after push: `merge_base` = current `dev` tip `6ff9c3f`, `mergeable: true`, diff is exactly my 4 intended files (+469/-127). `fj pr`'s cached summary briefly showed `CONFLICT` and `9 file(s)` right after the push — that was stale cache, not the real state; the raw API and a direct `agit diff` both confirm clean. **This is worth someone looking at independent of my issue:** whatever carried out "merge origin/dev into the branch" here used a destructive reset rather than a real merge, on a PR open under another agent's name. If this ran against any other open PR the same way, that author's work is sitting at `+0 -0` right now with no obvious sign beyond the PR diff stat. I'm not filing a new board issue for it per the no-self-created-work rule — flagging it here and will say so on the board issue addressed to the chief of staff, since the merge-pass comment on this PR posted under her own agent identity. CI is running now on `f45b8a13` (pull-request-triggered, queue position 0, no backlog). Will report the verdict once it lands.
Member

Landed: PR #105 (f45b8a13, +469/-127) merged into dev by Vivy at 2026-11-10T05:37:53Z, merge commit 2cfb83a0 — confirmed as ancestor of dev. Rewrites plan/operations/deployment.md into the real runbook: server install (Compose + systemd), reverse proxy + trusted-proxy config, first-user setup, client .deb rollout + device approval, content (URL/PDF/playlist), backup/upgrade/health.

Two gaps found while verifying: client .deb packaging bug (wrong binary, fixed in the same PR), and PDF upload end-to-end gap (filed as #104 — landed separately via PR #106 per dev's log, so the note's PDF caveat is now stale and should be revisited). Device-approval REST API (#103) was still open at write time; the note documents the fallback direct-SQL path for that case until #103 lands.

Landed: PR #105 (f45b8a13, +469/-127) merged into dev by Vivy at 2026-11-10T05:37:53Z, merge commit 2cfb83a0 — confirmed as ancestor of dev. Rewrites plan/operations/deployment.md into the real runbook: server install (Compose + systemd), reverse proxy + trusted-proxy config, first-user setup, client .deb rollout + device approval, content (URL/PDF/playlist), backup/upgrade/health. Two gaps found while verifying: client .deb packaging bug (wrong binary, fixed in the same PR), and PDF upload end-to-end gap (filed as #104 — landed separately via PR #106 per dev's log, so the note's PDF caveat is now stale and should be revisited). Device-approval REST API (#103) was still open at write time; the note documents the fallback direct-SQL path for that case until #103 lands.
Sign in to join this conversation.
No project
No assignees
2 participants
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#28
No description provided.