Repository navigation
Viewer onboarding: the service should hand you a working viewer config, not a documentation exercise #1953
Description
Field feedback from a real setup: getting the remote Viewer working was harder than any other part - copy-pasting JSON from the documentation, merging it with --print-viewer-connection's terminal output, and discovering by trial that the VIEWER's darling.json wants "managed": false even though the SERVER runs "managed": true. Every one of those steps is work the service could do itself, since it already has every value the viewer needs.
The fix shape
- A --export-viewer-config verb (or an extension of --print-viewer-connection) that writes the COMPLETE viewer-side darling.json - connection string with the resolved host, Root Certificate path wired, "managed": false already set - plus the server.crt beside it, as files ready to drop on the viewer machine. No hand-merging. The managed-flag confusion dissolves structurally: nobody writes that file by hand anymore.
- Consider the full step further: the service ships the entire Viewer's code already - evaluate exporting a pre-configured viewer ZIP (binaries + config + cert) so the viewer machine unzips and runs. Weigh the binary-duplication cost honestly; the config-plus-cert export alone removes most of the pain if the ZIP is too heavy.
- --print-viewer-connection warns BEFORE it prints, not after. The reporter saw the secret hit their scrollback and THEN the redirect advice. Order the STDERR guidance ahead of the STDOUT payload, and verify the interleaving on a real console rather than assuming stream order.
- The exported file carries its own comments documenting each field, including the valid 'Root Certificate=' values - the export becomes the reference the docs currently fail to be.
Alternative also worth weighing: a first-run GUI prompt in the Viewer asking for host/port/credential/cert instead of requiring a file at all. The export and the prompt are complementary, not competing.
Activity
erikdarlingdata commentedon Jul 31, 2026
PR #1968 implements items 1, 3 and 4.
Item 2 (pre-configured viewer ZIP) was evaluated and declined, per the issue's own instruction to weigh the binary-duplication cost honestly. The Viewer is a WPF app whose publish output runs to tens of MB against a ~6 KB config folder; the service would have to carry or reach the viewer's build output at runtime; and the operator still has to unblock a downloaded archive and keep the shipped binaries in step with the service version on every upgrade - a versioning surface the config folder simply does not have. The config-plus-cert export removes the pain the field report actually described, which the issue already anticipated as the fallback. Reopen or file a follow-up if the ZIP is wanted anyway.
The first-run GUI prompt alternative is untouched and still open as an idea - it is complementary, as the issue says, not something this PR forecloses.
Merge pull request #1968 from erikdarlingdata/fix/1953-export-viewer-…
erikdarlingdata commentedon Aug 1, 2026
Shipped in #1968. Darling now writes the whole remote-Viewer handoff folder from the service host: --export-viewer-config produces a complete darling.json (resolved host/port/role credential, verify-full TLS, managed:false already set, every field documented in comments the Viewer's parser skips), the store's server.crt beside it, and a README covering the valid Root Certificate values including the working-directory trap. Copy the folder next to the Viewer and start it - nothing to edit. The exported JSON is pinned against the REAL ViewerSettings parser in tests. Also in the same PR: --print-viewer-connection now emits every STDERR warning BEFORE the STDOUT payload (the field report watched a live password scroll by ahead of the advice), and the export path is hardened - owner-safe delete-then-create writes, refusal to overwrite anything the verb did not write, junction/symlink refusal, and an ACL on the secret-bearing file that is confirmed rather than assumed. Follow-ups tracked separately: #1970 (viewer-side anchoring of a relative Root Certificate, which would remove the one remaining hand-edit case) and #1973 (failure-path sweep + ancestor-junction guard comment, both minor).
Retouch the #1953 entry: the working-directory caveat is obsolete wit…
Export the viewer's whole config folder instead of documenting it (er…