pixop-stack

Orchestrates pixop-live.service and all TSDuck template instances (tsduck-in@*, tsduck-out@*) in a fixed order so shutdown metrics stay accurate and startup matches systemd After= expectations.

Version note: Use pixop-version and pixop-stack (no args) on the appliance to confirm available subcommands. Operators do not type sudo; the script self-elevates.

Usage

pixop-stack start [--all]
pixop-stack stop
pixop-stack restart [--all]
pixop-stack status
pixop-stack enable [--all]
pixop-stack disable
pixop-stack logs

There is no dry-run mode. Every start / stop / restart affects running services (individual steps may log skips; see below).

Command	Interrupts live streams?	Persists across reboot?
`start`	Starts units; may bind SRT listeners	No (`enable` sets boot policy)
`stop`	Yes — full pipeline down	No
`restart`	Yes — `stop` then `start`	No
`enable`	No (does not start)	Yes for enabled units
`disable`	No immediate stop	Removes enablement
`status` / `logs`	No	No

Refused: pixop-stack pull → exit 2; use pixop-image-update. Start never pulls images.

Default scope vs `--all`

Without --all, commissioning commands target only the primary pair:

Instance	Unit	Default SRT UDP
`main`	`[email protected]`	5000 ingest
`egress-main`	`[email protected]`	5001 egress

Secondary paths (UDP 5002–5003, instances egress-aux1, egress-aux2) stay out of scope until:

pixop-stack enable --all
pixop-stack start --all

or you tsduckctl enable / start specific aux instances after setting SRT_PASSPHRASE (and any relay templates) in their .env files.

Instances without a non-empty SRT_PASSPHRASE in /etc/pixop-live/tsduck/<name>.env are skipped on start/enable (message printed; not an error).

Start / stop order

Phase	`start` order	`stop` order
1	`pixop-live.service`	All ingress (`tsduck-in@*`)
2	Primary ingress `main`	`pixop-live.service`
3	Primary egress `egress-main`	All egress (`tsduck-out@*`)
4+ (`--all`)	Other ingress, then other egress	(included in ingress/egress loops)

Stop order stops ingress before Pixop so final Pulse metrics during shutdown stay meaningful. Start order brings Pixop up before TSDuck, matching unit dependencies.

restart runs stop (errors tolerated with || true) then start with the same --all flag.

Underlying tsduckctl start waits for SRT UDP bind when applicable; failed waits can leave units active but not listener-ready — check with tsduckctl check.

Enablement vs immediate state

Command	Effect
`enable`	`systemctl enable pixop-live` + `tsduckctl enable` on primary (and secondaries with `--all` if passphrases set)
`enable`	Does not call `start` — prints hint to run `pixop-stack start`
`disable`	Disables Pixop + all discovered TSDuck units; does not stop `docker.service`

Command matrix

Operator goal	Command
First-time boot persistence	`pixop-stack enable` then `pixop-stack start`
Commission aux egress	Configure `.env`, `pixop-stack enable --all`, `pixop-stack start --all`
Maintenance window — full down	`pixop-stack stop`
Bounce everything	`pixop-stack restart`
Bounce including aux	`pixop-stack restart --all`
Single-pane status	`pixop-stack status`
Follow all unit logs	`pixop-stack logs`
Restart Pixop only (keep ingest SRT)	pixopctl `restart`
Wedged pipeline	pixopctl `recover` (ingress cycle; egress stays)

`status` output

Pulse authentication — configured if /etc/pixop-live/pulse.env exists.
pixopctl status for pixop-live.service.
tsduckctl status-all table of every *.env instance.

Logs

pixop-stack logs follows journalctl for:

pixop-live.service
tsduck-in@*.service
tsduck-out@*.service

Default tail 200 lines, -f. Per-instance TSDuck file logs remain under /var/log/pixop-live/tsduck-*.log via tsduckctl logs.

Image updates

Container digest changes are not part of pixop-stack. After pixop-image-update --apply:

LIVE restarts only pixop-live.service if it was active.
TSDuck restarts each active tsduck-*@ unit (interrupts paths).

Plan image apply in off-hours; stack commands do not download images.

Risk summary

Action	Risk
`stop` / `restart`	Drops SRT sessions; viewers disconnect
`start` after long stop	Senders must reconnect; verify with `tsduckctl check`
`enable` without `start`	Reboot may auto-start if units were already active from before