Menu
Article Atomic Linux

Rebasing in Universal Blue: A Comprehensive Guide

Rich Hughes

• 4 min read

Rebasing not Freebasing w/ Ublue

This guide explains how to rebase your Universal Blue system to a different image, effectively changing your desktop environment and core operating system components. It includes information on rollbacks, general instructions, and specific examples for switching from an Aurora-DX base to other Universal Blue variants. Do this at your own peril.

What is Rebasing?

Rebasing, in the context of Fedora Atomic Desktops and Universal Blue, is the process of switching your system's base operating system image to a different one. Think of it like changing the foundation of your house while keeping your furniture (your data and Flatpak applications) largely intact.

Key Concepts:

  • Immutable OS: Universal Blue (and Fedora Atomic Desktops) use an immutable operating system. The core OS is read-only, making it more stable and predictable.
  • OSTree: This is the underlying technology that manages the immutable OS images. It's like a version control system for your entire operating system.
  • Container Images (OCI): Universal Blue distributes its images as container images, similar to Docker images. This allows for easy distribution and updates.
  • rpm-ostree: This is the command-line tool you use to manage your system, including rebasing and rollbacks.

What is a Rollback and How to Perform One?

A rollback allows you to revert to a previous deployment (a previous state of your operating system) if something goes wrong after a rebase or update. This is a crucial safety feature of immutable systems.

How to Rollback:

  1. Reboot and Access GRUB: Reboot your computer. During the boot process, hold down the Shift key (or sometimes Esc) to access the GRUB boot menu.
  2. Select Previous Deployment: You'll see a list of available deployments. The current deployment will be selected by default. Use the arrow keys to select an older deployment (usually the one immediately above the current one).
  3. Boot into Previous Deployment: Press Enter to boot into the selected older deployment. Your system will now be running the previous version of the OS.

Make Rollback Permanent (Optional): If you want to make the rollback permanent (so you don't have to select it from GRUB every time), open a terminal and run:

rpm-ostree rollback

Then reboot.

General Rebasing Instructions

These instructions apply to rebasing from any Universal Blue image to another. Specific examples for Aurora-DX are provided in the next section.

Steps:

  1. Backup: Always back up your important data before rebasing. Use a tool like Deja Dup (Backups) or manually copy files to an external drive/cloud storage.
  2. Identify Target Image: Determine the exact name of the Universal Blue image you want to rebase to. This will usually be in the form ghcr.io/ublue-os/<image-name>:<tag>. Common tags are:
    • :latest - For the most recent build.
    • :40, :39, etc. - For specific Fedora versions (recommended).
  3. Open Terminal: Open a terminal window.
    • ostree-unverified-registry: This is required because you're pulling from a container registry (usually GitHub Container Registry).
  4. First Boot: The first boot after rebasing will take longer.
  5. Verify: After logging in, run rpm-ostree status in a terminal to confirm you're on the new base.

Reboot: After the command completes, reboot your system:

systemctl reboot

Rebase Command: Use the rpm-ostree rebase command with the correct image name. The general format is:

rpm-ostree rebase ostree-unverified-registry:<image-name>

Rebasing from Aurora-DX: Specific Examples

These examples show how to rebase from an Aurora-DX base to various other Universal Blue images. Replace :40 with your Fedora version if it's different.

Important Note: These examples assume you're on Fedora 40. If you're on a different Fedora version (e.g., 39), change the :40 tag to match your version (e.g., :39). Using the correct Fedora version tag is highly recommended.

  1. To Base Images (Minimal, for Customization):There are several base images. You would choose one based on your hardware and needs. Here are the options available:
  3. To Pre-Alpha Images (COSMIC - NOT RECOMMENDED FOR DAILY USE):Do not use these unless you are specifically testing COSMIC and are prepared for potential instability.

COSMIC (NVIDIA):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/cosmic-nvidia:40

COSMIC (Main):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/cosmic-main:40

Secureblue - Base:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/secureblue-base:40

Secureblue - Vauxite:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/secureblue-vauxite:40

Secureblue - Aurora:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/secureblue-aurora:40

Secureblue - Bazzite:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/secureblue-bazzite:40

Secureblue - Bluefin:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/secureblue-bluefin:40

Kinoite:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/kinoite:40

Silverblue:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/silverblue:40

Base:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/base:40

To Mate:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/mate-main:40

To Sericea (Sway):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/sericea-main:40

To Onyx (Budgie):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/onyx-main:40

To Lazurite (LXQt):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/lazurite-main:40

To Vauxite (Xfce):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/vauxite-main:40

To Aurora DX (Customized KDE):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/aurora-dx:40

To Aurora (Customized KDE):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/aurora:40

To Bluefin DX (Developer-focused, GNOME):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bluefin-dx:40

To Bluefin (Developer-focused, GNOME):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bluefin:40

To Bazzite (Gaming, KDE):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bazzite-kde:40

To Bazzite (Gaming, GNOME):

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bazzite:40

What Persists and What Doesn't?

  • Preserved:
    • Your home directory (/home/yourusername) and its contents.
    • Flatpak applications (usually).
  • Not Preserved (Generally):
    • System-wide configurations (outside your home directory).
    • Packages installed with rpm-ostree install.
    • Desktop environment settings (since you're changing DEs).

Troubleshooting

  • Rollback: Use the GRUB menu to revert to a previous deployment if anything goes wrong.
  • Logs: Check journalctl -b for error messages.

Flatpak issues:

flatpak repair
Share