Skip to content

Bluefin

Recipes for managing a Bluefin (Universal Blue) immutable desktop. These wrap rpm-ostree and ostree commands with safety checks.

Updates

update runs ujust update — the standard Bluefin update path that handles the ostree image, flatpaks, and Homebrew packages together. Use this for routine updates.

docs prints links to Bluefin documentation.

Boot and Deployments

Bluefin uses ostree with two deployment slots: the booted image and a rollback. Understanding this is key to the boot recipes.

booted shows which image is currently running. status gives the full picture including both deployment slots, version info, and layered packages.

pin / unpin control whether a deployment is protected from garbage collection. Pinned deployments survive cleanup but consume space in /boot (which is typically small on Bluefin).

stage-upgrade — Careful Ostree Upgrades

stage-upgrade is a defensive upgrade recipe for when /boot is tight or you want explicit control. It:

  1. Checks for an available update (bails early if none)
  2. Unpins old rollback deployments
  3. Cleans up /boot to free space
  4. Stages the new image
  5. Pins the current booted deployment as rollback

When to use this instead of update: When /boot is nearly full, when ujust update fails with "no space left on device", or when you want to stage without rebooting immediately.

Trade-off: Step 3 briefly leaves you without a rollback. If staging fails (network drop, disk error), re-run rpm-ostree upgrade manually.

This does not replace update — it only handles the ostree image. Flatpaks and Homebrew packages are not touched.

Boot Maintenance

boot-cleanup removes temporary files from /boot by default (-b). Pass -p to remove a pending (staged but not rebooted) deployment, or -r to remove the rollback deployment.

ostree-journal and boot-kernel-journal show the previous boot's journal — useful for diagnosing why an update failed to finalize or why the last boot was slow.

Common Workflows

"My /boot is full and updates fail":

  1. just sys bluefin status — check for pinned deployments
  2. just sys bluefin stage-upgrade — handles cleanup and staging safely

"I rebooted and something is broken":

  1. Reboot and select the previous deployment from GRUB
  2. just sys bluefin status — confirm you're on the rollback
  3. just sys bluefin boot-kernel-journal — check what went wrong