How to Install Universal Blue's Base Images

General
1

Base / Main Universal Blue Images

What are the base images?

The base images are the building blocks for our end-user images like Bluefin, Aurora, and Bazzite. They live in the ublue-os/main repository.

These are generic Fedora Atomic Desktop but with non-free codecs, RPMFusion, and automatic updates out of the box. The base images do not deviate too far from Fedora Atomic and plan to stay as close to upstream as possible.

They are intended to be built upon and used as a base for custom images. Think of them like basic stock, we use them to act as a solid foundation to build from.

For the full list of packages which base images have, please click here.

Why would I use them?

Typically, we do not recommend users consume the base images directly on their devices, but anyone is free to use any Fedora Atomic image they desire regardless of the opinions from maintainers and contributors in Universal Blue. The purpose of these images is to have a place to start from to make your own.

A scenario where an individual does not want to use our end-user focused images or community images, then they can rebase to a base image which sticks closer to Fedora Atomic outside of some minor changes.

Universal Blue does not recommend or promote the usage of the base images for daily use.

Installing the Base Images

Attention: Universal Blue no longer supports an official installer and requires rebasing from an upstream Fedora Atomic image.

Download an Installer ISO

Upstream installer ISOs can be downloaded from Fedora Atomic Desktops.

Note: Choose the version which corresponds to the Universal Blue image you’d like to use. It is recommended to install Fedora Sway Atomic if you plan to use a desktop environment or window manager that isn’t available upstream to avoid conflicts.

Flash the ISO to a bootable drive and the rest of the installation should be similar to Fedora Silverblue’s installation process.

Rebasing Guide

This guide was originally written by Qoijjj and is slightly edited here.

1. Choose the base image

Check the available images here.

2. Choose and install an official Fedora Atomic Desktop ISO

The ISOs are available here.

Choose the ISO that corresponds to the desktop environment or standalone window manager that you’d like to use.

3. Rebase to the unsigned variant of the base image

For example, if you chose kinoite-nvidia as your choice, then run the following commands:

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

Reboot:

systemctl reboot

4. Rebase to the signed variant of the image you chose

For example, if you chose kinoite-nvidia as your choice, then run the following commands:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/kinoite-nvidia:latest

Reboot:

systemctl reboot

5. Nvidia GPU Configuration (Nvidia-only)

Run this ujust command to setup the required kernel arguments:

ujust configure-nvidia

Reboot:

systemctl reboot

Optimus laptops only

For Optimus laptops, run this command:

ujust configure-nvidia-optimus

Reboot:

systemctl reboot

This configures Optimus laptops.

Documentation Contributors: Qoijjj, fiftydinar, and Jorge Castro

3 Likes
2

Hi,

thanks for the documentation. I am/was happy with ublues enriched Silverblue images and want to continue to use it. I don’t want to use Bluefin nor Bazzite. Why you don’t recommend to use the base-image directly or is there an “Gnome Vanilla” alternative?

Can I rebase from silverblue-framework:39 directly to silverblue-main:40? Can I just use step 4 (Rebase to the signed variant)?

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

Thanks

Keywan

1 Like
3

Yep, that’s the correct command!

1 Like
4

I’m also a bit confused on the same topic as @keywan.
I’d like to have my own variation of the ublue, but I don’t want the things in bluefin/others.
Recently, I’ve created a repo based on the GitHub - ublue-os/image-template: Build your own custom Universal Blue Image!. I’m modifying build.sh with whatever packages/config I need on my system. However, some research shows me that there’re at least 3 ways of how to customize ublue:

  • fork existing spin (bazzite, bluefin,…) - Fork Your Own image - I think it’s not that great to have to both remove stuff we don’t need, and add stuff we do need, with lots of potential conflicts on pulls from the fork.
  • start from the template - the post here discourages this way, although it seems to be the simplest and most logical one. Why is it discouraged? It seems that it allows us to take some well-established base (vanilla gnome, and fedora silverblue base setup, or some hardware variant, like framework one) and build on top of it.
  • use blue-build - the guide there is in some stage of development, and is not ready to follow yet.

I think it’d be useful to have some clarification on when to go which way.

5

Yeah there’s a nearly unlimited amount of ways to make your own Containerfile/Dockerfile so we typically recommend a skeleton to get started and the actions.

I’ve removed the Fork information and just have that point to ublue-os/image-template, that’s what we recommend. Hopefully it’ll be less confusing for you!

6

Thanks for the clarification. Btw, I hope the blue-build solution takes off soon, since I believe it could aid with some common issues, like maybe applying some workarounds for SELinux issues with some packages, behind the scenes, or something similar. Also, it’d probably make sense for bluefin, and other „official” spins to switch over to blue-build conventions, just to make these spins easier to follow in terms of „how it was made”.

7

Question: should I rebase to the unsigned version and then to the signed version? Or are they different options of the same thing?

8

If you’re rebasing from an upstream Fedora Atomic Desktop (like Silverblue/Kinoite) then you have to rebase to an unsigned image first THEN to a signed image. If you’re already using a Universal Blue image then rebase directly to a signed image.

We do not want users using an unsigned image for security reasons.

1 Like
9

The whole reason I like the uBlue base image is because it has RPMFusion and codecs included AND it should allow easy updating.
When I used Silverblue and installed RPMFusion myself, I would always have to remove RPMFusion before upgrading. It was annoying (well documented on Fedora forum by many users).

I followed this guide exactly a couple of months ago: I did a clean install of Silverblue 40, then immediately after the rebase to uBlue OS main (non-nvidia). Then I installed via rpm-ostree a few basic stuff like gnome extensions, Nemo, Xed Texteditor.
All well.

Now, I get the notification to upgrade to v41 via Gnome Software. However when I hit the button, within seconds it says it cannot perform the update. When I hit “details” I get:

Refspec 'fedora/41/x86_64/silverblue' not found

Any idea what causes this issue? How to solve it?

$ $ rpm-ostree status
State: idle
AutomaticUpdates: stage; rpm-ostreed-automatic.timer: no runs since boot
Deployments:
● ostree-unverified-registry:ghcr.io/ublue-os/silverblue-main
                   Digest: sha256:b1d606e03fe632d6599bfa337f1b3a278def93b67ce27a0551c122bde4430770
                  Version: 40.20240630.0 (2024-06-30T03:12:17Z)
          LayeredPackages: dconf-editor docker-compose gnome-connections
                           gnome-network-displays gnome-screenshot
                           gnome-shell-extension-appindicator
                           gnome-shell-extension-blur-my-shell
                           gnome-shell-extension-dash-to-panel
                           gnome-shell-extension-drive-menu gstreamer1-vaapi hunspell-nl
                           make nemo nemo-compare nemo-emblems nemo-extensions
                           nemo-fileroller nemo-image-converter nemo-search-helpers
                           podman-docker xed

  ostree-unverified-registry:ghcr.io/ublue-os/silverblue-main
                   Digest: sha256:b1d606e03fe632d6599bfa337f1b3a278def93b67ce27a0551c122bde4430770
                  Version: 40.20240630.0 (2024-06-30T03:12:17Z)
          LayeredPackages: 'g++' dconf-editor docker-compose gnome-connections
                           gnome-network-displays gnome-screenshot
                           gnome-shell-extension-appindicator
                           gnome-shell-extension-blur-my-shell
                           gnome-shell-extension-dash-to-panel
                           gnome-shell-extension-drive-menu grubby gstreamer1-vaapi gthumb
                           hunspell-nl make nemo nemo-compare nemo-emblems nemo-extensions
                           nemo-fileroller nemo-image-converter nemo-search-helpers
                           podman-docker xed
10

Don’t use Gnome Software for system updates.

You don’t have a tag specified, so you’re 99% on ‘latest’, which is currently Fedora 41. Unrelated, but you’re also on an unsigned image for some reason.

  • Running rpm-ostree upgrade should be enough to get on 41.

What I advise you to do instead though, use a signed image and specify a tag, if you want to do that, to get the latest image:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/silverblue-main:latest

Or if you want to stay on 41, until you decide otherwise, specify the ‘41’ tag:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/silverblue-main:41

Edit: I see you are on a very old build with automatic updates enabled. I assume keys were updated and you don’t have those. In the case that the rebase commands above don’t work, do this first:

rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/silverblue-main:latest
11

Sorry but:

  1. I am on v40. I am trying to upgrade to Fedora 41 only because I got a notification from Gnome Software that I can upgrade to F41.
  2. I thought the whole goal of uBlue OS and all its flavours, is to support seamless upgrades in its base image. So that all its flavours will support it. Is it documented that you should never use Gnome Software to upgrade anything based on uBlue OS?
  3. Unsigned because the above guide simply mentioned that. The signed option seems to be metioned second only as optional…

I do understand now that I should always be on a signed version… but I still would like to understand if its “normal” for uBlue OS base, that I get this error message when trying to upgrade via Gnome Software?

I was hoping to finally have found a Linux OS that provides totally seamless upgrades without using terminal. Grandma proof.

12

You are on a image that is from June, so you might want to take a look at this:

Also you have things layered which might cause (usually does) issues when upgrading to a newer fedora version. But foremost, the key issue is propably the first reason why the update fails. Also the reason why automatic updates in the background haven’t worked

13

The guide mentions rebasing to a signed image clearly in its 4th step. Maybe it wasn’t clear before, I don’t know.

The rpm-ostree backend in Gnome Software tries to update to the latest upstream Fedora “image”, not uBlue. Updates in uBlue are handled automatically in the background by a systemd service. You won’t get these update notifications anymore, as the backend was recently removed for that exact reason.

You are on Fedora 40, because your updates stopped working, you are on a really old build, possibly because of what @inffy posted. I’m not sure if that problem is related to both unsigned and signed images, but your updates clearly don’t work. If they did work, you’d already be on 41, as that is the current version for the ‘latest’ tag. If a tag is not specified, it should default to latest.

Yes the upgrades are supposed to be seamless, but unfortunately mistakes happen from time to time.

14

This is because the Fedora upgrade mechanism isn’t using OCI it’s using ostree. Since it’s a main image we typically don’t touch the upstream behavior, so it’s unintentionally busted.

You’re getting this behavior because you’re using a base image instead of an end user image, and then additionally layering a bunch of packages. At that point it’s unsupportable by us as we expect users who stray off the path to understand how rebasing works. (As mentioned in the top paragraph of the instructions.)

It is optional but we don’t recommend it.

We provide this with Aurora and Bazzite, no one is actively testing the base images for usability or changes made by fedora, we use them to build the final base images. If you want to stay on the stock image you need to do an rpm-ostree reset, then do the upgrade, then layer all the stuff you want back. Hope this helps!

1 Like
15

@j0rge thanks a lot for taking the time to reply in-depth. Much appreciated!
I understand now.

The think I am disappointed about (not because of uBlue OS) is that Fedora Silverblue by itself also doesn’t support smooth updating via Gnome Software. Only in theory, not in real life. Because in real life, end users need codecs, hence they need RPMFusion layered (at least). After you do that, you cannot update using rpm-ostree upgrade anymore without removing it and all layers that require it + rebooting.

So there is no way for me to stay as close as possible to Silverblue + update via Gnome Software.

BUT, thanks to uBlue OS base, we end users get away with a single simple command to upgrade, without the need to remove stuff first.

I indeed performed curl -sL https://fix.universal-blue.org/ | sudo bash first to upgrade, @inffy thanks, I had already found that, just didn’t want to include more info here about my issue.

Afterwards, I ran the first command from lorduskordus to rebase to signed.

So all fine. Next time, just rpm-ostree upgrade should do the trick (until its replaced by bootc I guess).

1 Like
16

I empathize with this, I used silverblue for years before and it’s like “why would I move to this entirely new way of doing it if I still have to do manual labor?”

But then again we got to start from scratch and avoid the entire thing, shrug. :smile_cat:

2 Likes