Existing systems and rebasing

Rebasing changes the operating system deployment. Confirm which update manager controls the system and read the Secure Boot guide before changing to an image with a different kernel.

NOTE

Back up persistent data separately. Rolling back an OS deployment does not restore application data, reverse a database migration, or recover deleted files.

Select a starting system

The steps depend on whether you are installing a new machine, switching from Fedora CoreOS, or updating an existing uCore deployment. Fedora Atomic desktops and Fedora IoT are unsupported starting points.

Examples below use ghcr.io/ublue-os/ucore:stable. Choose a different image and starting system in the image picker to see the matching reference and steps.

A new installation

First installation / prepare on another computer

Use the auto-rebase template

Set your credentials and replace both image references in the Butane template with ghcr.io/ublue-os/ucore:stable. Read the install guide before running disk installation commands.

shellCompile the edited Butane fileCOPY

$ podman run --interactive --rm quay.io/coreos/butane:release \    --pretty --strict < ucore-autorebase.butane > ucore-autorebase.ign

Continue with first-install instructions

Workflow sources: github.com, coreos.github.io

An existing Fedora CoreOS system

Existing Fedora CoreOS / two-stage transition

Before changing the OS

Back up application data and read the Secure Boot guidance before rebooting into a different kernel. This path starts from Fedora CoreOS, not a desktop Atomic system.

shellInitial CoreOS rebaseCOPY

$ sudo rpm-ostree rebase \    ostree-unverified-registry:ghcr.io/ublue-os/ucore:stable

NOTE

Reboot into uCore. Run the reboot command only after the rebase succeeds. The initial reference does not enforce the uCore image-signing policy.

shellReboot after the initial rebaseCOPY

$ sudo systemctl reboot

Once running uCore

Continue only after you have booted uCore. Its installed signing policy enables the signed-reference step below.

shellSelect the signed referenceCOPY

$ sudo rpm-ostree rebase \    ostree-image-signed:docker://ghcr.io/ublue-os/ucore:stable

NOTE

Reboot again. After the signed rebase succeeds, reboot and confirm the booted signed reference.

shellReboot after the signed rebaseCOPY

$ sudo systemctl reboot

shellCheck the booted deployment after rebootCOPY

$ sudo rpm-ostree status

Read the Secure Boot guidance

Workflow sources: github.com, github.com

uCore managed with bootc

Existing uCore / bootc-managed deployment

Check the current deployment

This path requires an existing bootc-managed uCore system with its container-signing policy intact. If an August 2026 image cannot fetch updates, read the recovery announcement first.

shellInspect current imageCOPY

$ sudo bootc status

shellStage the selected image with policy enforcementCOPY

$ sudo bootc switch --enforce-container-sigpolicy \    ghcr.io/ublue-os/ucore:stable

NOTE

Apply on reboot. After staging succeeds, check Secure Boot requirements and reboot when your workloads are ready.

shellReboot after stagingCOPY

$ sudo systemctl reboot

shellConfirm the booted image after rebootCOPY

$ sudo bootc status

August 2026 image-policy recovery

Workflow sources: bootc-dev.github.io, github.com

uCore managed with rpm-ostree

Existing uCore / rpm-ostree-managed deployment

Use the installed signing policy

This path is for an existing uCore system still managed with rpm-ostree. Check Secure Boot before changing kernels.

shellStage the selected signed imageCOPY

$ sudo rpm-ostree rebase \    ostree-image-signed:docker://ghcr.io/ublue-os/ucore:stable

NOTE

Apply on reboot. After staging succeeds, reboot when your workloads are ready.

shellReboot after stagingCOPY

$ sudo systemctl reboot

shellConfirm after rebootCOPY

$ sudo rpm-ostree status

Workflow sources: github.com

Fedora Atomic desktop or Fedora IoT

This rebase path is unsupported

Reinstall and switch to uCore

uCore does not support rebasing from Fedora Atomic desktops or Fedora IoT. Use the CoreOS installer to reinstall with the uCore auto-rebase Ignition configuration, which switches the machine to uCore on first boot.

Read the first-install guide

Workflow sources: github.com

NOTE

An OS rollback returns to an earlier deployment. It does not restore application data or reverse database changes. Maintain and test separate backups.

Source: uCore installation and update guidance, bootc switch manual. Checked September 18, 2026.