Bluefin Administration Guide

Day to Day Operation

Bluefin and Aurora are designed to be installed for the life of the hardware without reinstallation. Unlike traditional operating systems the image is always pristine and “clean”, making upgrades less problematic. Updates are automatic and silent by default.

Secure Boot

Secure Boot is supported by default on our systems, providing an additional layer of security. After the first installation, you will be prompted to enroll the secure boot key in the BIOS.

Enter the password ublue-os when prompted to enroll our key.

If this step is not completed during the initial setup, you can manually enroll the key by running the following command in the terminal:

ujust enroll-secure-boot-key

Secure boot is supported with our custom key. The pub key can be found in the root of the bazzite repository here. If you’d like to enroll this key prior to installation or rebase, download the key and run the following:

sudo mokutil --timeout -1
sudo mokutil --import secure_boot.der

Note:

If you encounter an issue with a password being recognized as incorrect, try using the - key on the numpad instead.

Installing Applications

Graphical Applications

Use the GNOME Software Center or KDE Discover applications to install applications from Flathub. Unlike stock Fedora, system updates and upgrades are not handled by this application, it’s scope has been reduced to only install Flatpaks from Flathub. The Warehouse tool is included for management.


Command Line Applications

The brew application is the package manager used for installing command line applications in Bluefin and Aurora.

System Updates

Bluefin and Aurora are designed to be “hands off”. System updates apply weekly, and Flatpaks update twice a day in the background. Updates are applied when the system reboots. Therefore, it is recommended to routinely power off your device when it’s not being used to ensure kernel updates are being applied. Application updates (like the browser) happen independently of this and don’t require a reboot.

See configuration of updates if you want to change the default behavior.

Machine firmware updates are provided through the standard Software Center:

Upgrades and Throttle Settings

Bluefin publishes images for the current and last stable version of Fedora. This is to give users maximum flexibility by allowing them to rebase to the version they want. You can choose from three rolling tags, or lock to a specific version of Fedora.

gts (default) stable latest
Fedora Version: 39 40 40
GNOME Version: 45 46 46
Target User: Most users Enthusiasts Advanced users
System Updates: Weekly Weekly Daily
Application Updates: Twice a Day Twice a Day Twice a Day
Kernel: Gated Gated Upstream
  • gts: This is the default image and is always aliased to the previous stable version of Fedora. It targets the majority of users.
  • stable: This is for enthusiasts who want the latest version of the GNOME and Fedora. It is always aliased to the current version of Fedora but follows the Fedora CoreOS release schedule and not the Fedora Silverblue release schedule.
  • latest: For users who want the very latest Fedora has to offer, daily updates, full open throttle. :smile:

The major difference between latest and stable is when they update. latest will upgrade to the next major Fedora release as soon as it is available and it builds daily. stable will upgrade when CoreOS does it’s userpace upgrade, which is usually a few weeks afterwards, and only builds weekly.

Gated Kernel

The gts and stable tags feature a gated kernel. This kernel follows the same version as the Fedora CoreOS stable channel, which is a slower cadence than default Fedora Silverblue.

Asus and Surface Devices

Asus and Surface devices use their own dedicated images and only follow the :latest tag. This is to ensure proper support for those devices.

Switching between channels

Use the ujust rebase-helper command to select rebase and select a specific channel:

Or select date and choose an older image.

Switching between tags manually

Here are the manual commands with rpm-ostree, we recommend becoming familiar with them if you find yourself rebasing often:
Before changing a channel it is recommended to remove any locally layered packages:
rpm-ostree reset

Then run a status:

rpm-ostree status

and look for the image you are on, look for a terribly long line like this: ostree-image-signed:docker://ghcr.io/ublue-os/bluefin:gts

The ghcr.io/ublue-os/bluefin:gts is the important part, with bluefin being the image name, and the :latest being the image tag. That is the image you are currently on. Look for :gts, :stable, :latest, or in certain cases the version like :39 or :40. Use the bootc switch command to move to a newer or older version:

Examples

In this example we’re rebasing to :stable, which is the latest stable release of Fedora (currently 40):

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bluefin:stable

To always be on the :gts (default) release:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bluefin:gts

Explicit version tags of the Fedora release are available for users who wish to handle their upgrade cycle manually:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bluefin:40

Additionally rebasing to a specific date tag is encouraged if you need to “pin” to a specific day or version:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bluefin:38-20231101

If you use an nvidia machine, remember that the -nvidia is important! (This is why it’s important to note the image name when you ran that previous status command:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bluefin-nvidia:stable

Check the Fedora Silverblue User Guide for more information.

Overwriting System Defaults

Most Bluefin and Aurora system defaults are shipped on the base image along with Fedora configuration in /usr/etc. Most of these can be overriden by placing a file in /etc.

For example, the Distrobox configuration is in /usr/etc/distrobox/distrobox.ini. Your customization options will be placed in /etc/distrobox/distrobox.ini. This is useful for situations where you need a copy of the original file for reference.

Check the XDG Base Directory Specification for more information on configuration options, in particular ~/.local and ~/.config.

Power Management

By default Bluefin will switch the power profile depending on if you’re on AC or battery. You can adjust this setting by going to the logo menu → extensions manager, and then selecting what you want.

You can also turn off the extensions entirely with this command:

  • To turn it off: ujust configure-auto-power-profile disable
  • To turn it on: ujust configure-auto-power-profile enable

Remote Management

Note

This feature is incomplete and needs contributors to make it a reality

Bluefin and Aurora include Cockpit for machine management. We’re hoping to include more out-of-the-box management templates, please check this issue if you’re interested in volunteering.

Verification

These images are signed with sigstore’s cosign. You can verify the signature by downloading the cosign.pub key from this repo and running the following command:

cosign verify --key cosign.pub ghcr.io/ublue-os/bluefin

Building Locally (Bluefin Example)

  1. Clone this repository and cd into the working directory

    git clone https://github.com/ublue-os/bluefin.git
    cd bluefin
    
  2. Make modifications if desired

  3. Build the image (Note that this will download and the entire image)

    podman build . -t bluefin
    
  4. Podman push to a registry of your choice.

  5. Rebase to your image to wherever you pushed it:

    sudo rpm-ostree rebase ostree-image-signed:docker://whatever/bluefin:latest
    
5 Likes

FYI, the command sudo rpm-ostree rebase ghcr.io/ublue-os/bluefin:39 didn’t work for me, starting from a ghcr.io/ublue-os/bluefin-dx-nvidia:38 base… it produced the error Invalid refspec ghcr.io/ublue-os/bluefin:39. But running sudo rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bluefin:39 did work.

1 Like

If updates aren’t handled through Gnome Software, is there another graphical way of installing updates?

If I do rpm-ostree upgrade, will that also update my flatpaks?

No, rpm-ostree doesn’t know a thing about flatpaks.

Just to make sure I’m not missing anything: The Updates tab is no longer present in the software center, right? And the screenshot is therefore outdated?

1 Like

I haven’t gotten in a while but I think it only shows up for fwupd notifications. I’ll try to catch the next one.

Hi, does not show any fwupd notifications in bluefin-latest compared to ujust upgrade

Hi Jorge,

I’ve started using ublue’s main image and then jumped ship to the startingpoint once I’ve felt that I needed my custom ISO’s for my future installations. But I quickly realized that it’s really hard to keep up with changes to startingpoint and that I wanted a more stable approach where defaults are usually fine but I want to automate my customizations on top of the base.

Here are things I used to do on top startingpoint:

  • Layer some packages
    • some system76 packages (system76-keyboard-configurator, …)
    • langpacks-tr
    • some dependencies (libgda for pano, etc.)
    • moby-engine
    • simple-scan
    • gnome-boxes (flatpak doesn’t have usb passthrough)
  • Remove some packages
    • firefox + lang packs
    • gnome-tour
    • toolbx
  • Install 1Password via bling
  • Disable pcscd.socket since it causes issues when I want to use my e-signature inside Boxes (requires Windows)
  • Install custom flatpacks
  • Added my own selection of packages to yafti
  • Added my own additions to just files

I used to customize GNOME desktop via Ansible by setting up dconf locally. I like some of the defaults in bluefin but want to add my customizations as well.

So I was wondering what the recommended approach is for customizing bluefin. Do you recommend to have a Containerfile (like we do for classic image overrides) and add my customizations on top of bluefin image? If this is the recommended approach, should I include my dconf changes in /usr/etc/dconf/db/local.d/ or /etc/dconf/db/local.d/ like you mentioned above? (afaik, I should use /usr/etc instead of /etc if I want to overwrite the defaults when building a custom image)

Yeah you would do a Containerfile with FROM ghcr.io/ublue-os/bluefin as yourthing

Here’s an example of what @dogphilosopher is doing, but he’s using Bazzite:

We keep it in /usr/etc so the machine always has a pristine copy of the files in case the user mangles their config in /etc and wants to start over. The one gotcha is to search for dconf in the bluefin repo and you’ll have to copy over a systemd service unit to do a dconf update on first boot.

Some other things real quick: bluefin removes the firefox and gnome-tour already so no need to do that. -dx has Docker if you want to snag that config instead of moby engine, and then you’ll find system and user flatpak install/remove service units there too that you might want to snag. Then for ISOs you’ll want to use this github action: GitHub - ublue-os/isogenerator: Creates an ISO for installing a container image as an OS

That should be it!

Per this guide, I was trying to switch from gts to latest. I tried:

% sudo bootc switch ghcr.io/ublue-os/bluefin-dx-nvidia:latest

But received:
ERROR Switching: Reading manifest data from commit: Missing ostree.manifest-digest metadata on merge commit

After some troubleshooting/reading, I changed to:
rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bluefin-dx-nvidia:latest

That worked, fortunately. Hope this helps someone else…

Good call, I’ve fixed the docs, thanks!

2 Likes

Will there be any side effects if I remove some layers/packages using rpm-ostree override? These packages are -

  • solaar: so that it doesn’t show in tray
  • plasma-thunderbolt: so that it doesn’t show in settings

Should be fine, you won’t save any space, doing this to the .desktop files will be cleaner.

You’d want to do it the other way around and add NoDisplay=true

1 Like

typo here?
Correction: The gts and stable tags feature a gated kernel…

1 Like