Year of the Linux Desktop #7: Building a Custom Bazzite Image

Summary

#

The cool thing about an immutable distro based on bootc is that you can setup your own custom image in a way that is not that different from what you can do with NixOS or Guix, except it relies on containers and breaks all barriers that custom configuration languages had introduced. Now, you just use the system’s package manager again. Let’s learn how to setup a custom Bazzite image!

Background Knowledge

#

We are starting from Bazzite, which is a bootc image based on Fedora Atomic and maintained by Universal Blue. Universal Blue also provides two other images, Aurora, a general desktop image based on KDE, and Bluefin, a workstation image based on GNOME. I picked Bazzite because I’m installing on a desktop that I use for work but also gaming, and setting up game support is a lot harder than setting up everything else.

Filesystem

#

When preparing your custom bootc image, there are a few things worth knowing regarding the filesystem. The following table covers those details, or at least what I understood so far:

There are other helpful details that we, as users, don’t usually think about. For example, I was initially using an immutable /opt to drop system-wide uv tools (/opt/uv/<tool>), until I realized I should instead be using something like /usr/share/uv/tools/<tool>. This is the type of mindset you must build for yourself when working on OS components.

Template Repo

#

While bazzite-nvidia-open is a regular container image, the best way to setup your custom image is not by directly deriving from it. Instead, you should use Universal Blue’s image template and create your own repo from it. This will provide a preconfigured Containerfile, as well as the necessary GitHub Actions to build and push your image to GHCR.

About image naming, the general suggestion, as confirmed by the devs, is to use your own custom name, avoiding direct mentions to the original image. For example, using the Bazzite name might be confusing in terms of ownership. On other hand, using a custom name won’t break relation to Bazzite regardless—this is still clear from the Containerfile or even the repo’s template.

We decided to use DLT OS as the name of our custom image based on Bazzite, but more on it below.

What to Edit

#

Once you setup your repo based on ublue-os/image-template, you should start by editing build_files/build.sh. This is the entry point for your custom system commands.

While not included in the template, it is also common to create a system_files directory, where you can drop files to be copied over to the root filesystem of your final image, usually to /usr (non-local) or /etc. It is also frequent to create a repo_files directory, where we can store stuff like the logo for the custom image, to appear on ArtifactHub (optionally).

Cosign

#

Our image should also be signed using cosign. This is done automatically by the provided build.yml GHA, but we are required to first generate a key pair, as described in the image template repo’s instructions:

COSIGN_PASSWORD="" cosign generate-key-pair

This will produce a cosign.key private key, that I recommend you move to ~/.cosign and backup appropriately, and a cosign.pub public key, that should be committed to the repo. You must also setup your private key as a repo secret under Settings → Security → Secrets and variables → Actions → Repository secrets. Name it as SIGNING_SECRET and paste the contents of cosign.key into it. This is all that you need to do to sign your image automatically during build.

ArtifactHub

#

If you’d like your image to be listed on ArtifactHub when ready, simply create an account and repo on ArtifactHub, and copy over the repo ID to artifacthub-repo.yml, filling in the owners as well. Keep in mind that the e-mail you use will be public, and it should be the same used to sign up to ArtifactHub.

Build and Update

#

Now, as your image grows, you’ll want to handle both build performance, through caching mechanisms, as well as ensure that the users of your image will get incremental upgrades when they run sudo bootc upgrade, as opposed to downloading a huge image layer every time.

This is where the concept of rechunking enters. As I understand it, this simply repackages the image by reorganizing the layers in a way that user upgrade become more atomic and smaller. Let’s say that we add a dnf install for a specific package at the end of our Containerfile or build script. When the final image is built, it will produce completely different layers, due to metadata or other elements changing. As such, if our custom image adds 4 GiB of packages on top of Bazzite, the final user will keep downloading 4 GiB with each upgrade, despite the actual upgrade only changing a fraction of that.

Rechunking should clear that up, and this is even available as a commented out step on the .github/workflows/build.yml GHA that is provided with the image template. However, from what I understand, this approach is deprecated—also, I tested it and it doesn’t work. As of now, this is an unsolved problem with DLT OS. As recommended on Universal Blue’s Discord, I will be been looking into compose build-chunked-oci to address this issue in the future.

Apart from correctly layering the image, another relevant issue to address is ensuring efficient build performance. If we add a single package to the system, we don’t want to wait 15 min for the built to finish. Again, at Universal Blue’s Discord server, they pointed me towards DNF cache, leading me to this specific approach, which I will explore in the near future as well.

As a side note, also don’t worry about editing the README.md file, since it doesn’t trigger a build on push—as long as it’s the only changed file, of course.

Custom Image

#

First, we edited the env vars on .github/workflows/build.yml, adding a custom description, the proper keywords, and a link to the logo image, stored under repo_files:

env:
  IMAGE_DESC: "..."
  IMAGE_KEYWORDS: "bootc,ublue,universal-blue,..."
  IMAGE_LOGO_URL: "https://..."

The build GHA is scheduled to run everyday at 10:05 am. This is how you get updates from your base image baked into your custom image, i.e., as bazzite-nvidia-open:stable gets updated, our custom image will also get those updates.

We started by adding custom packages to build_files/build.sh, but, as the scope grew, we split this into multiple scripts, with a RUN statement for each individual script under Containerfile, as this will help with layer caching in the future. We also added a system-wide niri config under system_files/etc/niri/config.kdl, as well as a few helper scripts under system_files/usr/bin. This is how these folders look like:

build_files/
├── ai.sh
├── base.sh
├── cargo-env.sh
├── containers.sh
├── data.sh
├── dev.sh
├── go-env.sh
├── graphics.sh
├── languages.sh
├── network.sh
├── shell.sh
├── uv-env.sh
└── validations.sh
system_files/
├── etc
│   └── niri
│       └── config.kdl
└── usr
    └── bin
        ├── docker
        ├── docker-compose
        └── tray-launch

Let’s unpack the build files. Our entry-point script is base.sh, which installs only system-specific packages, like niri, noctalia, and related graphical utilities.

Also notice that we have three scripts to setup environment variables: go-env.sh, cargo-env.sh, and uv-env.sh. These are used to setup requirements for system-wide installs using go install, cargo install, or uv tool install. We source the corresponding environment scripts whenever we need to install a system-wide binary or script based on Go, Rust, or Python, respectively.

The remaining scripts are software categories. We call them in the following order inside Containerfile: base, languages, shell, network, graphics, dev, containers, AI, and data. The final one is validations.sh, which simply runs config file validations—we currently just use it to validate niri’s config file.

System files are copied from system_files to the images root / just before validations.sh is called. The reasoning behind this is that changes to the niri config won’t require a full image rebuild, but instead just a validation run.

Once we push into the GitHub repo, the build action will trigger and the image will be available as latest, as well as via tags latest.YYYYmmdd and YYYYmmdd, so that you can easily go back to older versions.

That’s it, we’ve built a custom Bazzite image!

DLT OS

#

You can find DLT OS on GitHub, with its image listed on GHCR, and also on ArtifactHub. Below we’ll go through the changes we’ve packaged into DLT OS.

Features

#

• Preconfigured niri out-of-the-box, with the noctalia shell.
• Go, Rust, Python, and Node tooling, providing go, cargo, uv, andnpm.
• System-wide tools, installed via dnf5, go install, cargo install, or uv tool install, making it easy to naturally extend if you want to derive your custom image.

The following sections summarize the packages that DLT OS provides out-of-the-box.

Base

#

For the base system, we add niri and noctalia-shell, alongside a few utilities. We also remove xwaylandvideobridge, which opens a blank window by default on niri, but seems to be deprecated anyway. This let’s us run the xwayland-satellite integration without issues.

Languages

#

Shell

#

Network

#

Graphics

#

Dev

#

Containers

#

AI

#

Data

#

Validations

#

We also include a validations script, where, at this point, we only validate the /etc/niri/config.kdl file.