Found on the deployment machine on 2026-10-11, the first time `hhstream-live` was run **as a unit** rather than from a login shell: a systemd unit's PATH has no system profile, so the capture command `grim` is not found, ten times, and the stream gives up. It answers on its port, serves the landing page and reports `"stopped": true, "failures": 10` while showing nothing -- the quiet half of the failure is what makes it worth a file. The module already solves this for `sessions.apps` by requiring an absolute store path; the stream's unit has to do the same (or set PATH, which is what made the deployment run work). Recorded in `docs/TODO/` with the two fixes, and named as a risk on stage 3 of the plan, which is the stage that turns this from an experiment into the only path.
56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
# The capture command needs an absolute path under a unit
|
|
|
|
## The issue
|
|
|
|
`hhstream-live` runs its capture command (`grim -c -t jpeg -q 80 -o <output> -`)
|
|
by name, from the `PATH` it inherits. Under **systemd** that path is
|
|
`/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` — the system
|
|
profile is deliberately not on it — so the capture fails, ten times, and the
|
|
stream gives up:
|
|
|
|
```
|
|
WARNING hhstream.live: stream on hh-chromium-yhvpms: giving up after 10
|
|
consecutive capture failures: capture command ['grim', '-c', '-t', 'jpeg',
|
|
'-q', '80', '-o', 'hh-chromium-yhvpms', '-'] could not be run:
|
|
[Errno 2] No such file or directory: 'grim'
|
|
```
|
|
|
|
Measured on 2026-10-11 on the deployment machine, the first time the app was
|
|
run **as a unit** rather than from a login shell. A login shell has
|
|
`/run/current-system/sw/bin` on its `PATH`, which is why every run before this
|
|
one — the stage-1 work, the standalone `serve --stream` runs, the whole test
|
|
suite — never saw it.
|
|
|
|
What makes it worth a file rather than a line: the failure is quiet in the
|
|
worst way. The unit starts, the port opens, the landing page answers, and
|
|
`status.json` reports a stream that is simply `"stopped": true` with
|
|
`"failures": 10`. A viewer sees an empty frame area and nothing else says why.
|
|
Only the unit's log names the reason, one line above the giving-up entry.
|
|
|
|
## Ideas
|
|
|
|
1. **An absolute binary, as the module already does elsewhere** *(recommended)*.
|
|
`sessions.apps` requires an absolute store path for exactly this reason —
|
|
"a unit's default `PATH` does not include the system profile", which is why
|
|
the allowlist spells `foot` as `${pkgs.foot}/bin/foot`. The stream's unit
|
|
should not inherit `grim` by name either: pass
|
|
`${pkgs.grim}/bin/grim` as the capture command from the module (or set
|
|
`PATH` on the unit, which is what made it work on the deployment machine).
|
|
The absolute path is also the stronger control: it names one exact binary
|
|
instead of whatever `PATH` resolves to at the moment the unit starts.
|
|
2. **Resolve early and fail loudly.** Have the app resolve the binary itself at
|
|
start-up and refuse to serve with a named error (`capture_binary_missing`)
|
|
if it is not there. A unit that dies at start is a five-second diagnosis; a
|
|
unit that serves an empty frame is an afternoon.
|
|
3. **Both.** The module passes the absolute path *and* the app checks it once
|
|
at start-up: the first is the fix, the second is what catches the next
|
|
deployment shape nobody has thought of yet.
|
|
|
|
## Why it matters
|
|
|
|
Stage 3's unit is the point at which running under systemd stops being an
|
|
experiment and becomes the only path every deployment takes — and a stream
|
|
that answers, reports a healthy port, and shows nothing is a worse failure than
|
|
one that does not start. Whichever idea is taken, the check for it belongs in
|
|
the same stage as the unit: a `vm-*` check that starts the unit and reads one
|
|
frame would have caught this on the day it was written. |