Update Mechanisms in Bluefin#

Bluefin is designed for seamless, automatic updates of the operating system and Flatpak applications. This document explains how these update mechanisms work, how to control them, and how to customize update schedules using systemd timers and services. Homebrew and ujust management are now handled by the projectbluefin/common image; refer to its documentation for details on Homebrew and ujust workflows.

System Updates#

Bluefin uses bootc and rpm-ostree for system updates. By default, the system checks for updates every six hours and applies them on reboot. Application updates (such as browsers) occur independently and do not require a reboot. Bluefin supports multiple update streams (gts, stable, latest), allowing users to select their preferred cadence and kernel gating.

Manual System Updates

To manually update the system, run:

ujust update

This command will:

• Upgrade the system image using bootc upgrade (default)
• If package layering is detected (LockLayering=false in /etc/rpm-ostreed.conf), it will use rpm-ostree upgrade
• Update system and user Flatpaks

Note: rpm-ostree upgrade is used only when local package layering is enabled, as bootc upgrade does not support layered packages. See Bluefin administration documentation for more details.

For more information on the update logic, see the projectbluefin/common update script. Refer to rpm-ostree documentation and bootc documentation for advanced usage.

Flatpak Updates#

Bluefin defaults to system-wide Flatpak installations and enables automatic updates by default. Updates are performed daily via systemd timers and services. Flatpak updates do not require a reboot and are sandboxed for security.

Systemd Units for Flatpak Updates#

System-level Flatpak updates are managed by:

• Service: /usr/lib/systemd/system/flatpak-system-update.service
• Timer: /usr/lib/systemd/system/flatpak-system-update.timer

User-level updates use:

• Service: /usr/lib/systemd/user/flatpak-user-update.service
• Timer: /usr/lib/systemd/user/flatpak-user-update.timer

Timers are configured to run daily at 4:00 AM, with a randomized delay and a short delay after boot. They are persistent, so missed runs are caught up on next boot.

Example timer configuration:

[Timer]
RandomizedDelaySec=10m
OnBootSec=2m
OnCalendar=*-*-* 4:00:00
Persistent=true

The update sequence is:

flatpak --system uninstall --unused -y --noninteractive
flatpak --system update -y --noninteractive
flatpak --system repair

To mask a Flatpak app from updates (Flatpak 1.5.0+):

sudo flatpak mask com.example.App

To downgrade a Flatpak app:

sudo flatpak update --commit=<commit_id> com.example.App

Fedora Flatpak Repository Removal#

Fedora Flatpak repository removal is now managed by the projectbluefin/common image or upstream configuration. Bluefin no longer ships or manages the /usr/lib/systemd/system/flatpak-nuke-fedora.service. If you need to ensure only intended Flatpak repositories are present, refer to the common image documentation for current best practices and automation details.

Flatpak Overrides#

Flatpak override files are now managed by the projectbluefin/common image. Bluefin no longer ships local override files in /usr/share/ublue-os/flatpak-overrides/. For information on how Flatpak overrides work and how to customize permissions, see the Flatpak documentation on overrides and consult the common image documentation for current override examples and management workflows.

Homebrew and ujust Management#

Homebrew and ujust are now managed by the projectbluefin/common image. All Brewfile bundles, just recipes, and related update logic have been moved there. Bluefin no longer manages local Brewfiles or just files. For details on Homebrew installation, updates, and usage, refer to the common image documentation.

Update Orchestration: uupd Service#

The uupd service coordinates system and Flatpak updates. If present, it replaces or supplements rpm-ostreed-automatic and Flatpak timers.

• Service: /usr/lib/systemd/system/uupd.service
• Timer: /usr/lib/systemd/system/uupd.timer

If uupd.timer exists, it is enabled by default. Otherwise, Bluefin enables rpm-ostreed-automatic.timer, flatpak-system-update.timer, and flatpak-user-update.timer.

You can enable or disable the orchestrator timer:

sudo systemctl enable uupd.timer
sudo systemctl disable uupd.timer

Check status:

systemctl status uupd.timer

View logs:

journalctl -fexu uupd.service

Customizing Timers#

To override the schedule, create a drop-in file:

sudo systemctl edit uupd.timer

Example to run every 2 hours:

[Timer]
OnCalendar=
OnCalendar=hourly

Reload systemd after changes:

sudo systemctl daemon-reload
sudo systemctl restart uupd.timer

Toggling Automatic Updates#

Bluefin provides a utility to toggle automatic updates:

ujust toggle-updates enable
ujust toggle-updates disable

This enables or disables the relevant timer (uupd.timer or rpm-ostreed-automatic.timer).

Reference: Example systemd Unit and Timer#

Custom Timer for Flatpak Updates:

sudo systemctl edit flatpak-system-update.timer

Example override to run at 2:00 AM and 2:00 PM:

[Timer]
OnCalendar=
OnCalendar=*-*-* 2,14:00:00

Manual Update Run:

sudo systemctl start uupd.service

Check All Update Timers:

systemctl list-timers | grep update

Best Practices#

• Prefer system-wide Flatpak installations; avoid --user unless necessary.
• Use the provided utilities (ujust update, ujust toggle-updates) for safe management.
• When customizing timers, use drop-in files to avoid overwriting package-managed units.
• Monitor logs for update services to diagnose issues.
• Avoid local package layering unless absolutely necessary.
• For Homebrew and ujust workflows, consult projectbluefin/common.

For further details, see the Bluefin administration documentation and review systemd unit files in /usr/lib/systemd/system/ and /usr/lib/systemd/user/.

This document provides a reference for managing and customizing update mechanisms in Bluefin, including system and Flatpak updates. Homebrew and ujust management are now handled externally in the common image.