Variants#
How the Dakota ISO build target works.
Scope: dakota and utah#
This repo ships the Dakota and Utah ISOs. The bluefin and bluefin-lts-hwe ISO builds are
retired (#228): their matrix entries in build-iso-utah.yml (renamed from build-iso-bluefin.yml)
are commented out and they are not promotable. Scripts and live/src/<variant>/ config are kept so a variant can be revived.
| Surface | State |
|---|---|
test-luks-install.yml matrix | variant: [dakota]; stable / lts kept as a comment |
test-plain-install.yml matrix | variant: [dakota]; stable / lts kept as a comment |
build-iso-utah.yml | active, monthly schedule on the 8th at 04:00 UTC (0 4 8 * *) + workflow_dispatch; matrix builds utah ā bluefin / bluefin-lts-hwe entries retired as comments |
build-iso.yml (dakota) | active |
Required on main (ruleset main ā review policy) | 1 approving review; status check ShellCheck |
Retired bluefin builds stay off because their matrix entries are commented out, not because
the workflow is disabled ā build-iso-utah.yml is enabled and scheduled for monthly Utah builds (8th, 04:00 UTC).
Reviving a variant#
- Uncomment the variant in the
test-luks-install.yml/test-plain-install.ymlmatrix. - For the bluefin ISO build, uncomment the variant's matrix entry in
build-iso-utah.yml
and re-add it to thepromote-release.ymlchoices. - Add the corresponding
LUKS E2E <variant> (<channel>)contexts to the
main ā review policyruleset.
The stable and lts legs were red at the time of the change ā sshpass got
Permission denied, please try again. against the live VM (issues #155, #161,
#163). Reviving them means fixing that first.
Current build#
| Variant | Live env image | Payload (offline store) | Bootloader | Composefs | Filesystem | State |
|---|---|---|---|---|---|---|
dakota | projectbluefin/dakota-nvidia:stable | same | systemd-boot | yes | btrfs | active |
utah | projectbluefin/utah:stable | same | grub2 (live ESP systemd-boot, Secure Boot off) | no | btrfs | active (monthly schedule, 8th 04:00 UTC) |
bluefin | projectbluefin/bluefin-nvidia:stable | same | grub2 | no | btrfs | retired |
bluefin-lts-hwe | projectbluefin/bluefin-lts-hwe-nvidia:stable | same | grub2 | no | btrfs | retired |
All variants default to btrfs. XFS is offered as a user-selectable installer option only for the non-composefs variants (utah, bluefin, bluefin-lts-hwe); Dakota uses composefs, which needs fs-verity, so it cannot install to XFS.
There is one unified ISO: dakota-live.iso.
| Build target | payload_ref | Live boot | Offline install |
|---|---|---|---|
dakota | ghcr.io/projectbluefin/dakota-nvidia:stable | NVIDIA live env | NVIDIA VFS store (auto-rebases to non-NVIDIA on first upgrade) |
CI and local builds both use just iso-sd-boot dakota. There is no separate dakota-nvidia
build target ā the dakota/live_target file points to dakota-nvidia to select the right
container image.
How the build target works#
The dakota/ directory contains two files:
dakota/
payload_ref ā ghcr.io/projectbluefin/dakota-nvidia:stable
live_target ā dakota-nvidia
The justfile reads <target>/payload_ref for the OCI image to embed and <target>/live_target
for the container build arg. The live container is built from live/Containerfile with
--build-arg TARGET=<live_target>:
container target:
podman build \
--build-arg TARGET={{live_target}} \
-t {{target}}-installer -f ./live/Containerfile ./live
The installer configs inside the ISO (images.json, recipe.json) are patched at
build time to reference the correct image via configure-live.sh.
Reading variant config: scripts/variant-config.sh#
Every host-side read of per-variant config goes through one file,
scripts/variant-config.sh. Source it and call a function ā do not cat the
config files inline:
source scripts/variant-config.sh # from the repo root
variant_live_target dakota # ā dakota-nvidia
variant_tag dakota # ā stable
variant_registry dakota # ā projectbluefin
variant_bootloader_variant dakota # ā dakota (live_target minus -nvidia/-nvidia-open)
variant_composefs dakota # ā true (live/src/<bootloader-variant>/composefs)
variant_bootloader dakota # ā systemd (live/src/<bootloader-variant>/bootloader)
variant_bootloader_recipe bluefin # ā grub2 (fisherman's spelling of "grub")
variant_composefs_json bluefin # ā false (for a recipe.json field)
Two things this centralises:
-
The default set.
live_targetdefaults to the variant name,tagto
stable,registrytoprojectbluefin,composefstotrue, and
bootloadertosystemd. Those five defaults are now stated once. They
were previously restated at each call site, so adding a key or changing a
default meant finding every copy. -
The namespace-B key derivation.
composefsandbootloaderdo not
live underlive/src/<variant>/ā they live underlive/src/<live_target minus the -nvidia/-nvidia-open suffix>/, because a variant can build its
live environment from an NVIDIA image while sharing bootloader config with
the non-NVIDIA one. That is whyltsreadslive/src/bluefin-lts-hwe/.
Getting this wrong returns defaults rather than an error, so it is worth
having in exactly one place.
payload_ref and live_title are deliberately not exposed: payload_ref
has no default (callers hard-error when it is missing) and live_title is
free text that must not be whitespace-stripped.
Config keys#
Each key lives in exactly one place. A file anywhere else is not read.
| Key | Location | Read by | Required | Default when absent |
|---|---|---|---|---|
payload_ref | <variant>/ | justfile, scripts/*.sh | yes (hard error) | ā |
live_target | <variant>/ | variant_live_target | no | variant name |
live_title | <variant>/ | scripts/iso-sd-boot.sh | no | ā |
registry | <variant>/ | variant_registry | no | projectbluefin |
tag | <variant>/ | variant_tag | no | stable |
composefs | live/src/<bootloader-variant>/ | variant_composefs, configure-live.sh | no | true |
bootloader | live/src/<bootloader-variant>/ | variant_bootloader, configure-live.sh | no | systemd |
base_imgref | live/src/<bootloader-variant>/ | configure-live.sh | no | ghcr.io/projectbluefin/dakota:stable |
nvidia_imgref | live/src/<bootloader-variant>/ | configure-live.sh | no | ghcr.io/projectbluefin/dakota-nvidia:stable |
images.json | live/src/<bootloader-variant>/ | configure-live.sh | no | live/src/etc/bootc-installer/images.json |
recipe.json | live/src/<bootloader-variant>/ | configure-live.sh | no | live/src/etc/bootc-installer/recipe.json |
flatpaks | live/src/<bootloader-variant>/ | install-flatpaks.sh | no | live/src/flatpaks |
configure-live.d.sh | live/src/<bootloader-variant>/ | configure-live.sh | no | no hook |
dakota has no live/src/dakota/ directory: every live/src default above is
the Dakota value. tests/test_live_build_invariants.py fails if a namespace-A
key (payload_ref, live_target, live_title, registry, tag) or the
unread flatpak_var_path reappears under live/src/. The installer reads
flatpak_var_path from images.json.
Adding a custom build target#
For local testing, create a directory with payload_ref and optionally live_target:
mkdir my-variant
echo 'ghcr.io/projectbluefin/my-variant:latest' > my-variant/payload_ref
just iso-sd-boot my-variant
Output: output/my-variant-live.iso
images.json ā catalog lock#
live/src/etc/bootc-installer/images.json locks the installer to show only the
available image choices. Key fields:
{
"name": "Dakota",
"imgref": "ghcr.io/projectbluefin/dakota:latest",
"bootloader": "systemd",
"filesystem": "btrfs",
"composefs": true,
"needs_user_creation": false,
"flatpak_var_path": "state/os/default/var"
}
bootloader: "systemd"ā installs systemd-boot, not GRUBcomposefs: trueā enables composefs backendneeds_user_creation: falseā GNOME Initial Setup handles user creation at first bootflatpak_var_pathā where installer places Flatpak data on the installed system
Lessons#
payload_ref must not have trailing whitespace (2026-05)#
The justfile strips whitespace with tr -d '[:space:]', but if a script reads
payload_ref directly without stripping, trailing newlines cause podman pull
to fail with an invalid reference error. Always strip when reading payload_ref:
Templating a variant for an unpublished image (2026-06)#
Create all variant files and commit them, but add the CI matrix entry commented out
in build-iso-utah.yml. This keeps files reviewable without breaking CI.
When the image is published, enabling it is a single-line uncomment.
Fedora/Silverblue-based variants: grub2 + no composefs (2026-06)#
Bluefin and bluefin-lts-hwe are Fedora Silverblue bootc images. Key differences from Dakota:
bootloader: grub2ā fisherman skips--bootloaderflag (grub2 is the default; onlysystemdneeds explicit flag)composefs: falseā ostree-native path;ostree.final-diffidannotation must be removed after squash (not updated)filesystem: btrfsfor ALL variants (bluefin, bluefin-lts-hwe, dakota)flatpak_var_path: var/lib/flatpakā Silverblue stores flatpaks at the root, not in a deployment subdir/usr/localis a dangling symlink on Silverblue at build time ā always write installer files to/usr/share/, not/usr/local/
cat <variant>/payload_ref | tr -d '[:space:]'
Dead image refs ā ublue-os org (2026-06)#
ublue-os image names are legacy. All active images live under ghcr.io/projectbluefin/.
bluefin-gdx does not exist in projectbluefin ā never use it.
projectbluefin/bluefin-lts publishes no standalone -nvidia image; the nvidia/HWE
variant is bluefin-lts-hwe-nvidia:stable. Always verify with:
skopeo list-tags docker://ghcr.io/projectbluefin/<image>
or read execute-release.yml in the source repo.
systemd-boot title is controlled by live_title file (2026-06)#
Each variant directory contains a live_title file whose contents appear verbatim
as the boot menu entry in systemd-boot and loopback.cfg:
bluefin/live_title ā Bluefin Live
bluefin-lts-hwe/live_title ā Bluefin LTS HWE Live
dakota/live_title ā Dakota Live
build-iso.sh accepts --title <string>; the justfile reads <target>/live_title
and passes it. To customise the title for a new variant, create a live_title file
in the variant directory.
Non-composefs (ostree) offline storage: overlay additional store vs VFS size explosion (2026-06-24)#
When building ISOs for non-composefs (ostree/bootcDirect) targets:
- Squashing is prohibited: Squashing the payload image flattens the filesystem layer and breaks bootc's ostree unencapsulation (corrupts hardlinks, leading to
Expected commit object, not Fileand missingostree.final-diffidannotations). - VFS size explosion: Storing the image unsquashed in a VFS-format containers-storage additional store replicates and inflates all ~120 layers, causing
no space left on deviceand OOM errors during build or installation. - The Solution: Build an unsquashed
oci-archivepayload and import it into anoverlay-driver additional store (/usr/lib/containers/storage) inside the live squashfs root. To boot and run natively on EL10/LTS host kernels (which lack native overlay-on-overlay support), configure the live ISO's/etc/containers/storage.confto usefuse-overlayfsas the mount program:[storage] driver = "overlay" additionalimagestores = ["/usr/lib/containers/storage"] [storage.options.overlay] mount_program = "/usr/bin/fuse-overlayfs" - Fisherman targetImgref: Ensure that
targetImgrefis populated in the fisherman recipe JSON. If omitted, fisherman's direct-mode path runs bootc without the--source-imgrefargument, failing withEither --source-imgref must be defined or this command must be executed inside a podman container.