Bootc Image Configuration#

Configuration in Bluefin-based bootc systems (Bluefin, Dakota, finpilot, Bluefin LTS) is embedded in the OCI image at build time — not applied post-install. The deployed root filesystem is read-only; the three writable tiers are: 1

/var is not 3-way merged — it uses Docker VOLUME semantics. Use systemd-tmpfiles.d to pre-create directories under /var. Prefer /usr over /etc where software supports both, and use drop-in directories (e.g., /etc/sudoers.d/) to minimize state drift. 2

See the bootc filesystem docs for authoritative details.

Multi-Stage OCI Build Pattern#

All Bluefin-based images use a context-stage multi-stage Containerfile that separates concerns cleanly across layers. The finpilot Containerfile is the canonical template:

ctx (scratch stage)
├── /build ← local build scripts
├── /custom ← local custom files
├── /oci/common ← imported from ghcr.io/projectbluefin/common
└── /oci/brew ← imported from ghcr.io/ublue-os/brew

base image (e.g. quay.io/fedora-ostree-desktops/silverblue:44)
└── RUN /ctx/build/00-image-info.sh
└── RUN /ctx/build/10-overlay.sh
└── RUN /ctx/build/20-packages-and-services.sh
└── RUN /ctx/build/90-cleanup.sh
└── RUN bootc container lint --fatal-warnings

Build scripts run in numeric order with ctx bind-mounted read-only: 3

Separating 20-packages-and-services.sh from the overlay phase is intentional — filesystem overlay changes should not bust the expensive package layer cache. 4

Key identity ARG values set at build time: IMAGE_NAME, IMAGE_VENDOR, UBLUE_IMAGE_TAG, BASE_IMAGE_NAME, VERSION. Volatile metadata (SHA_HEAD_SHORT, IMAGE_CREATED) is declared late so new commits don't invalidate package/overlay layers. 5 6

Supported base images: 7

system_files Overlay Layers (projectbluefin/common)#

projectbluefin/common organizes all shared configuration as three filesystem overlays merged at build time; later layers win on conflicts: 1

The Containerfile also copies in build-time generated artifacts: ujust completions, YubiKey U2F / game-device udev rules (SHA256-verified), and the umotd binary. 1

To audit local configuration drift after deployment, run:

ujust check-local-overrides

This diffs /usr/etc against /etc to surface machine-local divergence.

Declarative Kernel Arguments#

Kernel arguments are declared as TOML files embedded in /usr/lib/bootc/kargs.d/ inside the image — replacing the legacy grubby runtime approach: 1

# /usr/lib/bootc/kargs.d/framework-intel.toml
kargs = ["module_blacklist=hid_sensor_hub"]

For install-time machine-specific injection (serial consoles, extra mounts, networking), pass --karg to bootc install: 8

bootc install to-disk --karg console=ttyS0,115200 /dev/sda
bootc install to-existing-root --karg="systemd.mount-extra=UUID=:/data:xfs:defaults"

For UKI setups, use signed UKI addons to provide machine-specific kargs without invalidating the signed image.

Cleanup of legacy grubby kargs is handled in the OEM hooks — see system-setup.hooks.d/10-framework.sh in projectbluefin/common.

First-Boot Tooling Integration#

Several systemd units embedded in the image manage first-boot activation: 1

OEM Hardware Hooks#

Hooks in system-setup.hooks.d/ fire via ublue-system-setup.service and detect hardware via DMI strings: 1

• 10-framework.sh — Framework laptops: applies audio jack (AMD) and suspend (Ryzen 7040) fixes; cleans up legacy grubby kargs
• 11-asus.sh — ASUS hardware: enables asusd.service

Hooks exit immediately on non-matching hardware, so runtime cost is negligible.

Package Manager Pre-Staging#

Neither Homebrew nor Flatpak is invoked during the OCI image build. Instead: 9

• Homebrew: The ghcr.io/ublue-os/brew OCI layer is copied in at build time as a tarball + systemd units. brew-setup.service extracts it on first boot. Custom Brewfiles go in custom/brew/*.Brewfile and are staged to /usr/share/ublue-os/homebrew/ at build time.
• Flatpak: .preinstall INI files from custom/flatpaks/ are staged to /usr/share/flatpak/preinstall.d/ at build time. flatpak-preinstall.service installs them after network comes online.

Flatpaks are not reinstalled during bootc switch — only on first boot with network access. 9

ISO-Embedded Configuration#

Titanoboa (Bluefin ISO Builder)#

Titanoboa implements the Container-native ISO contract v0.1.0 — all ISO customizations must be embedded in the container image itself, not applied by the ISO builder. 1

Required files in the image: 1

iso.yaml defines the GRUB2 menu including kernel arguments inline in the linux: field. Titanoboa is consumed as a GitHub Action — see the titanoboa README for integration details.

Dakota ISO#

The Dakota ISO build embeds installer configuration in /etc/bootc-installer/ at container build time: 10

The OCI payload image is embedded as VFS containers-storage inside the squashfs — no network pull is needed at install time. driver = "vfs" is set in /etc/containers/storage.conf because composefs targets require it. 1

The live environment is built in three stages: 11

1. live/Containerfile — pulls Dakota NVIDIA image, configures GDM autologin, installs Flatpaks, drops in installer config
2. scripts/build-live-squashfs.sh — squashes to one layer, imports into VFS containers-storage, runs mksquashfs
3. live/src/build-iso.sh — assembles final ISO with squashfs and boot files

Key invariant: The VFS store at var/lib/containers/storage inside the squashfs must be populated with dakota-nvidia:stable before ISO upload — an empty store causes install failure even with network access.

Customizing with finpilot#

projectbluefin/finpilot is the official template for building custom Bluefin-derived images. Fork it and edit the following: 12

Key constraint: Clean up .repo files added during build — DNF repositories are non-functional at runtime, and bootc container lint --fatal-warnings will catch leftover repo artifacts. 13

For a package-adding example with COPR, see how 20-packages-and-services.sh installs uupd via copr_install_isolated. 14

Key References#