Two images are built from this repository:
| Image | Base | Intended hardware |
|---|---|---|
ghcr.io/philip-scott/os |
bazzite |
AMD/Intel GPUs |
ghcr.io/philip-scott/os-nvidia |
bazzite-nvidia-open |
Nvidia GPUs (open kernel modules) |
Both images share the same Containerfile and build.sh; the workflow builds
them in a matrix, passing SOURCE_IMAGE and IMAGE_VARIANT as build args. The
Nvidia image skips the ROCm packages (rocm-smi, rocm-hip, rocm-opencl,
rocminfo), which are only useful on AMD GPUs.
# AMD/Intel
rpm-ostree rebase ostree-unverified-registry:ghcr.io/philip-scott/os
# Nvidia
rpm-ostree rebase ostree-unverified-registry:ghcr.io/philip-scott/os-nvidiaEverything build.sh installs lands in a single Containerfile RUN layer,
which would change on every build and force a full re-download. The workflow
therefore rechunks the final image with rpm-ostree compose build-chunked-oci
(as in ublue-os/image-template),
splitting it into up to 127 per-package layers. --previous-build points at the
published :latest image to keep the layer plan stable, so an update only
downloads layers whose packages changed. The first update after rechunking was
introduced downloads the whole image once.
This image bundles OpenZFS so ZFS pools (for example a drive holding a Restic repository) can be imported and mounted.
Important
ZFS is currently disabled (ARG ENABLE_ZFS="false" in the Containerfile)
because Bazzite stable ships Linux 7.3 and no OpenZFS release supports it
yet. While disabled, the ZFS build and CI cache steps are skipped and both
images are built from stable. Set ENABLE_ZFS to "true" to re-enable it.
Universal Blue only publishes prebuilt ZFS kmods for the coreos-stable,
coreos-testing, longterm and centos kernel flavors, and Bazzite ships the
OGC kernel. The zfs-builder stage in the Containerfile therefore compiles
the module from the signed OpenZFS release tarball against the exact kernel in
the base image, and only the resulting RPMs are copied into the final image.
Compiling the module is slow, so CI caches the RPMs with actions/cache. The
cache key includes the base image kernel (ostree.linux label), ZFS_VERSION
and build-zfs.sh. It is restored into zfs-rpms/, and build-zfs.sh reuses
the RPMs only when they match the image kernel; otherwise it rebuilds them.
ZFS_VERSION in the Containerfile has to stay compatible with the base image
kernel. The build fails with an explicit message when the kernel moves past the
Linux-Maximum declared by that OpenZFS release; bump ZFS_VERSION to a
release that supports the new kernel.
The module is autoloaded at boot and zfs-import-cache, zfs-mount and
zfs-zed are enabled, so previously imported pools come back automatically:
sudo zpool import <pool>
restic -r /<pool>/<dataset>/<repo> snapshotsNote
The module is built locally and is not signed with an enrolled MOK, so it will not load while Secure Boot is enabled.
Files in root/ are copied onto the image filesystem as-is (root/etc/...
becomes /etc/...). root/etc/udev/rules.d/50-keychron.rules grants the
logged-in user access to hidraw devices from vendor 3434 (Keychron) so
tools like VIA / Keychron Launcher can configure the keyboard. Reboot after
updating to the new image for it to take effect. Check a keyboard's vendor ID
with lsusb | grep -i keychron (the ID 3434:xxxx part).
The image includes the keychron_battery kernel module, which reports the
battery level of Keychron M5 / M6 8K mice (wired, through the Ultra-Link 8K
receiver, or through the Link-KM receiver 3434:d026) to UPower and the
desktop battery widget. Its source is vendored in
patches/keykron-battery-module from
keychron-battery-dkms
v0.1.3 (commit 43c324e, GPL-2.0-only), so the build never fetches code from
that repository. Two local changes sit on top of v0.1.3: upstream PR 6
(responses are read through raw_event instead of a private URB), and
Link-KM support, whose vendor channel is on interface 1 instead of 4,
which takes queries only on its interrupt OUT endpoint, and
which reports as "Keychron M6" since it does not answer the paired-mouse
query. Because the Link-KM carries a joystick on the same interface, UPower
would show its battery as a game controller named after the receiver; the
module instead parents that battery to a virtual keychron_battery device with
an idle placeholder mouse, which 50-keychron.rules hides from libinput. DKMS cannot rebuild modules on an image based system, so the
keychron-battery-builder stage in the Containerfile compiles it against the
base image kernel, and build.sh installs it under
/usr/lib/modules/<kernel>/extra/. The module autoloads when a supported device
is connected:
cat /sys/class/power_supply/keychron_mouse/capacityTo update, review the upstream changes and copy keychron_battery.c and
Makefile from the new release into patches/keykron-battery-module, then
reapply the Link-KM changes (and upstream PR 6 if it has not been released yet). Like ZFS, the module is unsigned and will not
load while Secure Boot is enabled.
This repository is meant to be a template for building your own custom Universal Blue image. This template is the recommended way to make customizations to any image published by the Universal Blue Project:
This template includes a Containerfile and a Github workflow for building the container image. As soon as the workflow is enabled in your repository, it will build the container image and push it to the Github Container Registry.
Working knowledge in the following topics:
- Containers
- rpm-ostree
- Fedora Silverblue (and other Fedora Atomic variants)
- Github Workflows
Select Use this Template and create a new repository from it. To enable the workflows, you may need to go the Actions tab of the new repository and click to enable workflows.
This file defines the operations used to customize the selected image. It contains examples of possible modifications, including how to:
- change the upstream from which the custom image is derived
- add additional RPM packages
- add binaries as a layer from other images
This workflow creates your custom OCI image and publishes it to the Github Container Registry (GHCR). By default, the image name will match the Github repository name.
Container signing is important for end-user security and is enabled on all Universal Blue images. It is recommended you set this up, and by default the image builds will fail if you don't.
This provides users a method of verifying the image.
-
Install the cosign CLI tool
-
Run inside your repo folder:
cosign generate-key-pair
- Do NOT put in a password when it asks you to, just press enter. The signing key will be used in GitHub Actions and will not work if it is encrypted.
Warning
Be careful to never accidentally commit cosign.key into your git repo.
-
Add the private key to GitHub
-
This can also be done manually. Go to your repository settings, under Secrets and Variables -> Actions
Add a new secret and name it
SIGNING_SECRET, then paste the contents ofcosign.keyinto the secret and save it. Make sure it's the .key file and not the .pub file. Once done, it should look like this: -
(CLI instructions) If you have the
github-cliinstalled, run:
gh secret set SIGNING_SECRET < cosign.key
-
-
Commit the
cosign.pubfile into your git repository