Bluefin Update Pipeline#

The update pipeline chains four layers: ujust update → bctl update → uupd → bootc. Each layer adds orchestration on top of the one below.

ujust update is the user-facing entry point. It:

1. Exits if uupd.service or rpm-ostreed-automatic.service is already running
2. Exits if layered packages are detected
3. exec bctl update when bctl is in PATH — full handoff, no return 1
4. Falls back to sudo bootc upgrade + manual flatpak/brew steps when bctl is absent 2

uupd Orchestration#

bctl update delegates to uupd, a Go daemon whose Update() function runs modules sequentially:

A file lock prevents concurrent runs. Each module's Enabled state is determined at startup — if BootcCompatible() returns false, uupd falls back to the rpm-ostree driver 3.

Failures from all modules are collected into a failures slice; if any exist, uupd sends a critical desktop notification via session.Notify listing the failed module names 4. There is no retry logic — a single transient network error fails the system module permanently for that run.

The --apply flag triggers systemctl reboot after a successful system update 5.

uupd ↔ bootc Integration#

SystemUpdater.Update() runs bootc upgrade --quiet --progress-fd 3 6. An OS pipe is passed as fd 3 so bootc writes structured JSON progress there while stdout/stderr are captured separately 7. A goroutine calls bootcScan() on the pipe, parsing BootcProgress structs in real time.

Progress Stage Mapping#

The PROGRESS_STAGES table maps bootc task names to display labels and percentage ranges:

Two JSON event types drive progress calculation 8:

• ProgressBytes — proportional byte progress within the stage's range
• ProgressSteps — proportional step progress within the stage's range

Update Pre-checks#

Known Failure Modes#

Transient GHCR Network Errors (no retry)#

bctl update / ujust update can fail immediately with "✗ System Image failed" when bootc encounters a transient EOF from the GitHub Container Registry blob CDN 9. Because uupd has no retry logic, a single network hiccup fails the entire system module. The progress bar reaches 0% and stops.

Workaround: Run sudo bootc upgrade directly and retry on failure — it works after transient CDN errors resolve.

False negative in --check: bctl update --check has been reported to return "System is up to date" even when bootc upgrade --check correctly reports a pending update 9. This is because the two tools call bootc upgrade --check via different code paths.

bluefin-lts Tag Mismatch (:lts → :stable)#

The image tag for Bluefin LTS changed from :lts to :stable when the project moved to the projectbluefin organization 9. Users already on the old image were auto-migrated via a systemd service. However, bctl reads image-info.json (baked at build time) for its channel display, while bootc status reports the live booted image ref. After migration, these can diverge — bctl shows stable/testing from the build-time tag while bootc status shows ghcr.io/projectbluefin/bluefin-lts:stable 10.

The correct current image references are:

• ghcr.io/projectbluefin/bluefin-lts:stable
• ghcr.io/projectbluefin/bluefin-lts-nvidia:stable

To switch manually: sudo bootc switch ghcr.io/projectbluefin/bluefin-lts:stable --enforce-container-sigpolicy

Key Files & Entry Points#

Upstream References#

• bootc upgrade docs — canonical reference for --progress-fd, --check, and JSON output format
• bluefin-lts README — current image refs and migration guide