pixop-image-update

Download and apply digest-pinned Pixop LIVE (docker.io/pixop/live) or TSDuck (public.ecr.aws/z7b3p1n3/tsduck) container images. Updates LIVE_IMAGE / TSDUCK_IMAGE in env files and restarts only units that were active at apply time.

Does not upgrade host OS, NVIDIA driver, or systemd units — those require a new tested AMI or QCOW2. Generic docker pull with mutable tags is not a supported operator workflow.

Version note: Confirm on your appliance with pixop-version, command -v pixop-image-update, and pixop-image-update -h. Operators do not type sudo; the tool re-executes to /opt/pixop/bin/pixop-image-update when needed. status may auto-elevate when env files are not world-readable.

Trusted references

Immutable form only:

live    docker.io/pixop/live@sha256:<64-lowercase-hex>
tsduck  public.ecr.aws/z7b3p1n3/tsduck@sha256:<64-lowercase-hex>

Pixop publishes digests for your release line. Production appliances should not rely on mutable tags.

Target	Env file	Keys
`live`	`/etc/pixop-live/live.env`	`LIVE_IMAGE`, `LIVE_IMAGE_PREV`
`tsduck`	`/etc/pixop-live/tsduck.env`	`TSDUCK_IMAGE`, `TSDUCK_IMAGE_PREV`

Journal / lock: /var/lib/pixop-live/image-update/, /run/pixop-live/image-update.lock.

Usage

pixop-image-update status [live|tsduck]
pixop-image-update rollback live|tsduck
pixop-image-update live  <digest-ref> (--download-only | --apply)
pixop-image-update tsduck <digest-ref> (--download-only | --apply)
pixop-image-update -h|--help
pixop-image-update help

Rule	Detail
Exactly one of `--download-only` / `--apply`	Required for `live` / `tsduck` image lines
`--apply` never pulls	Image must exist locally (`docker images`)
`rollback` never pulls	`*_IMAGE_PREV` digest must be present locally
Hub auth options	Only `live --download-only`

Docker Hub (LIVE download only)

Private docker.io/pixop/live pulls need a read-only Hub token at download time:

Interactive prompt after elevation, or
--dockerhub-username USER --dockerhub-token-stdin (token on stdin, never argv)

Credentials live only in a temporary DOCKER_CONFIG (mode 0700) for the pull, then removed. They are not stored in env files, journal, or permanent docker config.

TSDuck pulls from public ECR — no Hub credentials.

Workflow

1. Download (may contact registry)

pixop-image-update live docker.io/pixop/live@sha256:<hex> --download-only
pixop-image-update tsduck public.ecr.aws/z7b3p1n3/tsduck@sha256:<hex> --download-only

2. Apply (local only)

pixop-image-update live docker.io/pixop/live@sha256:<hex> --apply
pixop-image-update tsduck public.ecr.aws/z7b3p1n3/tsduck@sha256:<hex> --apply

Apply behavior:

Target	If unit was active	If inactive
`live`	Restarts `pixop-live.service`, waits for health	Updates env only; prints no restart
`tsduck`	Restarts each active `tsduck-in@` / `tsduck-out@` unit	Updates shared `TSDUCK_IMAGE` only

TSDuck apply prints: TSDuck restart will interrupt active media paths.

If digest already matches configured value and image is local → no restart.

3. Rollback

pixop-image-update rollback live
pixop-image-update rollback tsduck

Requires LIVE_IMAGE_PREV / TSDUCK_IMAGE_PREV from the last successful apply and local image present. Swaps current/previous digests in env and restarts previously active units.

4. Status

pixop-image-update status
pixop-image-update status live

Shows configured / previous digest, local image presence, pixop-live or active TSDuck units. If an unresolved transaction exists, prints recovery instructions (do not start another apply until resolved).

Exit codes

Code	Typical cause
0	Success
1	General failure (missing local image, apply error)
2	Usage (bad ref, both/neither download+apply, bad Hub options on tsduck/apply)
3	Lock timeout
4	Pending / unresolved transaction policy
5	Rollback / recovery failure

Operational risk

Risk	Mitigation
SRT disconnect during TSDuck restart	Schedule off-hours; warn partners
Pixop restart mid-stream	Prefer maintenance window; ingress may need recover after LIVE apply
Partial failed apply	Check `status` for unresolved tx; follow printed recovery
Wrong digest	`rollback` if prev recorded; else re-download known good digest

Host stack changes (kernel, driver, unit files) still need a new appliance image — this tool only swaps pinned container digests.

What does not work

Approach	Why
`docker pull pixop/live:latest`	Not digest-pinned; not wired into env
`pixopctl pull` / `pixop-stack pull`	Explicitly refused
Apply without prior download	Apply verifies local image only
Hub token on `tsduck download`	Rejected at CLI parse

Task matrix

Goal	Command
See current digests	`pixop-image-update status`
Stage new LIVE image	`... live @sha256:... --download-only`
Cut over LIVE	`... live @sha256:... --apply`
Revert LIVE	`pixop-image-update rollback live`
Update all TSDuck containers	`tsduck ... --download-only` then `--apply`
CI pull LIVE	`echo "$TOKEN" \| pixop-image-update live @sha256:... --download-only --dockerhub-username u --dockerhub-token-stdin`

After LIVE apply, pixopctl restart is not required — image-update restarts when needed. After only env edit without this tool, use pixopctl/stack as appropriate.