Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
06fc988
fix: install flatpak, without which the image cannot honour its own c…
hanthor Sep 5, 2026
3975c3d
fix: build the Utah live ISO end to end
hanthor Sep 6, 2026
1903fa3
feat: install Utah to an encrypted disk and prove it boots
hanthor Sep 6, 2026
c7daac7
test: verify the desktop starts, and keep the screenshots as the record
hanthor Sep 6, 2026
d663b35
feat: ship a terminal, watch the VMs, and keep the installed disk
hanthor Sep 6, 2026
c9ef679
fix: create /usr/local/libexec before installing into it
hanthor Sep 6, 2026
ba6d970
fix: keep the Anaconda installer branch out of the transaction
hanthor Sep 6, 2026
8bafd34
test: refresh the verification record from a run on this branch
hanthor Sep 6, 2026
8897a09
test: open the terminal from inside the session, not over SSH
hanthor Sep 6, 2026
719bc2a
feat: ship Ghostty rather than the BlueShell rebrand
hanthor Sep 6, 2026
dca47d4
test: wait for the live VM to exit before booting the disk it wrote
hanthor Sep 6, 2026
5999e56
fix: pin complete Utah package repository
Copilot Sep 6, 2026
c08da3d
test: assert extensions load, embed the proof in the README, and fix …
hanthor Sep 6, 2026
0e5be0a
test: give the live VM ten minutes to shut down, not one
hanthor Sep 6, 2026
6048f58
test: refuse to run while a try-installed VM holds the work directory
hanthor Sep 6, 2026
6d46125
test: give the installed system's device jobs 180s, not 45
hanthor Sep 6, 2026
ce90673
test: read the extension State field as gnome-extensions prints it
hanthor Sep 6, 2026
60921e9
test: wait for the shell to answer before reading extension state
hanthor Sep 6, 2026
fbfd8f3
test: do not fail a green run on an unreadable extension state
hanthor Sep 6, 2026
3df8145
test: make the extension check actually check, and diagnose failed boots
hanthor Sep 6, 2026
4e1222c
docs: record the passing end-to-end run
hanthor Sep 6, 2026
d50f8b8
test: flush /boot in the guest instead of racing a shutdown that neve…
hanthor Sep 6, 2026
4437d8f
fix: break the rechunker-group-fix ordering cycle that deletes device…
hanthor Sep 6, 2026
166fe14
fix: stage the ISO build on disk, not in tmpfs
hanthor Sep 6, 2026
f944d0c
test: say so when the live ISO was built without debug
hanthor Sep 6, 2026
05933ad
fix: do not enable rechunker-group-fix; Utah rechunks with chunkah
hanthor Sep 6, 2026
a03563c
fix: align image inputs with current package base
Copilot Sep 7, 2026
425f60e
chore(ci): retrigger image builds after runner artifact failure
Sep 7, 2026
280e3b9
ci: retrigger failing image builds
Sep 7, 2026
11d4eea
fix: strip rechunker-group-fix from the image, not just disable it
hanthor Sep 8, 2026
ee870cc
ci: rerun failing checks
github-actions[bot] Sep 9, 2026
51a82d8
fix: align base and package image pins
Sep 9, 2026
1fb5630
fix: use complete Utah package repository pin
Sep 9, 2026
809498d
fix: let install create script destinations
Sep 10, 2026
877275c
ci: retry transient failing checks
Sep 10, 2026
86f436d
fix(iso): integrate current package contract into ISO test branch
hanthor Sep 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Containerfile
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ COPY --from=common /system_files/bluefin /tmp/utah-bluefin
COPY --from=brew /system_files /tmp/utah-brew
COPY system_files/shared /tmp/utah-local


RUN for pair in install-packages.py:utah-install-packages \
verify-rpm-contract.py:utah-verify-rpm-contract \
build-gnome-extensions.sh:utah-build-gnome-extensions \
Expand Down
1 change: 1 addition & 0 deletions Containerfile.kernel
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ FROM ${BASE_IMAGE} AS builder
# buildroot. Fedora is builder-only; it is not copied into the runtime stage.
COPY packages/hummingbird.repo /etc/yum.repos.d/hummingbird.repo
COPY packages/fedora-44.repo /etc/yum.repos.d/fedora-44.repo
RUN mkdir -p /usr/local/libexec
COPY scripts/install-ogc-kernel.sh /usr/local/libexec/utah-install-ogc-kernel
COPY scripts/install-nvidia.sh /usr/local/libexec/utah-install-nvidia

Expand Down
12 changes: 12 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,18 @@ build-local stream="testing" package_image="localhost/utah-packages:local-merged
--tag "localhost/{{ image }}:{{ stream }}" \
--file Containerfile .

# Install Utah from its live ISO onto an encrypted disk in QEMU, boot the
# result, answer Plymouth's passphrase prompt, and confirm it comes up. Needs a
# debug ISO -- `just iso testing 1` -- because the install phase drives the
# installer over SSH.
luks-test iso_path="output/utah-live.iso" image="ghcr.io/projectbluefin/utah:testing":
bash iso/scripts/luks-e2e.sh "{{ iso_path }}" "{{ image }}"

# Boot the disk luks-test installed, with VNC and a browser console, so the
# verified result can be driven by hand instead of only asserted about.
try-installed:
bash iso/scripts/boot-installed.sh

generate-build-tags base_name stream flavor kernel_pin build_number version event_name event_number:
@echo "{{ stream }} {{ version }}"

Expand Down
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,11 @@
# Utahraptor

<!-- BEGIN E2E VERIFICATION -->
[![Verified end to end](docs/verification/screenshots/installed-fastfetch.png)](docs/verification/README.md)

*Verified end to end on 2026-09-06T18:12:30Z: installed to a LUKS2-encrypted disk, unlocked at the Plymouth prompt, and logged in to a GNOME session — the shot above is fastfetch inside that booted install. Full record and more screenshots in [docs/verification](docs/verification/README.md), refreshed by `just luks-test`.*
<!-- END E2E VERIFICATION -->

†Utahraptor ostrommaysi

Bluefin built on Fedora Hummingbird. The more ... civilized murder machine.
Expand Down
20 changes: 20 additions & 0 deletions docs/skills/local-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,26 @@ persists.

## Verification

### Encrypted install and screenshot harness

`just luks-test` runs `iso/scripts/luks-e2e.sh` against a debug live ISO
(`just iso testing 1`). It checks the live GNOME session, installs to a
disposable LUKS2 disk from the embedded payload, boots without the ISO,
unlocks the disk, and checks graphical login and extension states.
Read the recipe and script prerequisites before running it: it creates test
accounts and requires local QEMU/KVM access, not a production installation.

Passing runs refresh `docs/verification/README.md`, its screenshots, and the
delimited verification block in the root README. These are historical local
test records, not proof that the current commit passed CI. In particular,
the fastfetch capture currently waits after terminal autostart; it does not
independently assert that fastfetch rendered. Automated CI publication still
needs to be wired up and must retain the tested commit/image digest.

When integrating this harness with newer image-build fixes, retain the
currently verified package-image digest and available-package contract.
The older ISO branch's package pin and exclusions must not replace them.

```bash
just check
```
Expand Down
53 changes: 53 additions & 0 deletions docs/verification/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Verification

Written by `just luks-test` (iso/scripts/luks-e2e.sh). Do not edit by hand:
the next passing run overwrites it.

Every image below is a QEMU screendump taken during that run, at the moment
the check beside it passed.

| | |
| --- | --- |
| Captured | 2026-09-06T18:12:30Z |
| Live ISO | `utah-live.iso`, 7.7G |
| Installed image | `ghcr.io/projectbluefin/utah:testing` |
| Root filesystem | btrfs on LUKS2, passphrase unlock |
| Live session | GNOME, wayland |
| Installed session | GNOME, wayland, user `utahtest` |

## What passed

1. The live ISO boots and its session reaches `graphical.target` with
`gdm.service` active and `gnome-shell` running — not a text console
that merely answers SSH.
2. The installer creates a LUKS2 volume and installs from the ISO's embedded
container store, with no network.
3. The installed disk boots on its own, with no ISO attached.
4. Plymouth's passphrase prompt is answered and the root volume opens.
5. The system reaches the graphical target rather than an emergency shell.
6. The user logs in at the GDM greeter and gets a GNOME session.

## Screenshots

### The installed system, running
![fastfetch](screenshots/installed-fastfetch.png)

A terminal on the desktop this test built, reporting the OS, kernel and
desktop from inside it. Everything below is how it got there.

### Live session
![Live session](screenshots/live-desktop.png)

The desktop the ISO boots into, with the installer available.

### GDM greeter on the installed system
![Greeter](screenshots/installed-greeter.png)

After the encrypted root has been unlocked and the system has reached the
graphical target. This is what proves the boot did not stop at a console.

### Logged in
![Desktop](screenshots/installed-desktop.png)

`utahtest`'s GNOME session, entered by typing the password at the
greeter above.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/verification/screenshots/live-desktop.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
21 changes: 20 additions & 1 deletion iso/live/Containerfile
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,13 @@ ENV TARGET_IMAGE=${TARGET_IMAGE} DEBUG=${DEBUG}

# Utah already carries dracut-live; systemd-boot is added only to the live
# environment because the installed image uses the Hummingbird bootloader.
RUN dnf5 install -y --setopt=install_weak_deps=False systemd-boot-unsigned && \
#
# dbus-daemon is for the build itself: install-flatpaks.sh starts a system bus
# so flatpak can install into /var/lib, and Utah carries dbus-broker rather
# than the reference daemon, so /usr/bin/dbus-daemon is not there. The package
# is small and never leaves the live overlay.
RUN dnf5 install -y --setopt=install_weak_deps=False \
systemd-boot-unsigned dbus-daemon && \
dnf5 clean all && rm -rf /var/cache/dnf /var/cache/libdnf5

# Bake the installer plus precisely the Flatpaks declared by the Bluefin
Expand All @@ -32,9 +38,22 @@ RUN chmod 0755 /tmp/utah-live-src/configure-live.sh && \
# Rebuild against Utah's own kernel and userspace. Hummingbird's dracut emits
# a harmless /root install warning in the container build context but still
# returns a successful image with dmsquash-live included.
#
# tpm2-tss and pcsc are omitted because they cannot be satisfied. Hummingbird's
# dracut config adds "fido2 tpm2-tss pkcs11 pcsc" unconditionally, and a module
# named there is an error rather than a skip when its helpers are missing:
# tpm2-tss wants tpm2_pcrread from tpm2-tools and pcsc wants the pcsc-lite
# tools, and neither package exists in Hummingbird or in this factory.
#
# Dropping them costs nothing here. This is the live initramfs, which boots an
# unencrypted squashfs from the ISO and has no smartcard or TPM-backed volume
# to open; the installed system boots the payload image's own initramfs, which
# this build never touches. Revisit if Utah ever wants TPM-bound LUKS, which
# needs tpm2-tools in the installed image, not in the live overlay.
RUN set -eux; \
kernel="$(ls /usr/lib/modules | sort -V | tail -1)"; \
dracut --force --reproducible --no-hostonly \
--add dmsquash-live \
--omit 'tpm2-tss pcsc' \
--add-drivers 'squashfs overlay loop iso9660 sr_mod cdrom' \
"/usr/lib/modules/${kernel}/initramfs.img" "${kernel}"
18 changes: 10 additions & 8 deletions iso/live/src/configure-live.sh
Original file line number Diff line number Diff line change
Expand Up @@ -77,14 +77,16 @@ EOF
systemctl enable var-tmp.mount || true

# Utah is a conventional bootc image rather than Dakota's composefs runtime.
# The ISO builder embeds its OCI payload as a VFS containers-storage graphroot.
mkdir -p /var/lib/containers/storage /etc/containers
cat >/etc/containers/storage.conf <<'EOF'
[storage]
driver = "vfs"
runroot = "/run/containers/storage"
graphroot = "/var/lib/containers/storage"
EOF
# The ISO builder embeds its OCI payload into /usr/lib/containers/storage, the
# image store this platform already resolves to.
#
# There is deliberately no /etc/containers/storage.conf here. One used to
# write driver = "vfs" and a graphroot under /var, and it did nothing:
# Hummingbird ships /usr/share/containers/storage.conf.d/00-vendor.conf, and
# drop-ins are read after /etc, so the driver stayed overlay and podman kept
# looking in the vendor image store. The payload now lives where the platform
# looks, which needs no override and cannot drift from one.
mkdir -p /etc/containers
mkdir -p /var/fisherman-tmp

# Installer branding/configuration. The custom recipe must reference the same
Expand Down
61 changes: 58 additions & 3 deletions iso/live/src/install-flatpaks.sh
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,36 @@ INSTALLER_VERSION="${UTAH_INSTALLER_VERSION:-v3.0.16}"

mkdir -p "${FLATPAK_CACHE}/tmp" /run/dbus
export TMPDIR="${FLATPAK_CACHE}/tmp"
# /root is a symlink to /var/roothome in a bootc image and the target does not
# exist during a container build, so mkdir -p /root/... fails outright. Point
# the cache somewhere writable instead; this only silences dconf's warnings.
export XDG_CACHE_HOME="${FLATPAK_CACHE}/cache"
mkdir -p "${XDG_CACHE_HOME}"
# An OCI flatpak remote makes flatpak spawn a session bus of its own, and a bus
# refuses to start without a machine id -- which a container image does not
# have. Flathub installs never needed one; the TunaOS remote does:
# Cannot spawn a message bus without a machine-id
# The id is build-time only; systemd regenerates a real one on first boot.
if [[ ! -s /etc/machine-id ]]; then
systemd-machine-id-setup >/dev/null 2>&1 || dbus-uuidgen > /etc/machine-id
fi
dbus-daemon --system --fork --nopidfile
# ...and a session bus. Installing from an OCI remote reaches for one and,
# finding none, tries to autolaunch it:
# error: Cannot autolaunch D-Bus without X11 $DISPLAY
# Flathub's ostree remotes never ask for it, which is why this only appeared
# when the TunaOS remote was added.
if [[ -z "${DBUS_SESSION_BUS_ADDRESS:-}" ]]; then
DBUS_SESSION_BUS_ADDRESS="$(dbus-daemon --session --fork --print-address)"
export DBUS_SESSION_BUS_ADDRESS
fi
sleep 1

if [[ -d "${FLATPAK_CACHE}/repo/refs" ]]; then
rsync -a --ignore-existing "${FLATPAK_CACHE}/repo/" /var/lib/flatpak/repo/ || true
# cp, not rsync: rsync is in neither Hummingbird nor the factory, so it
# cannot be installed into the live layer. -n keeps the seed
# non-destructive, which is all --ignore-existing was doing.
cp -a -n "${FLATPAK_CACHE}/repo/." /var/lib/flatpak/repo/ || true
fi

flatpak remote-add --system --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
Expand Down Expand Up @@ -53,9 +78,39 @@ for branch in /var/lib/flatpak/app/${INSTALLER_APP_ID}/x86_64/*; do
done
flatpak override --system --filesystem=/etc:ro "${INSTALLER_APP_ID}"

mapfile -t apps < <(awk -F '"' '/^flatpak / {print $2}' /tmp/flatpaks-list)
# /tmp/flatpaks-list already holds bare application ids: the Containerfile
# converts the Brewfile before copying it in, so the contract stays the single
# source of truth. Parsing it as Brewfile syntax a second time matched nothing
# and left the array empty, and an empty array makes flatpak read the remote
# name as the thing to install:
# error: No remote refs found for 'flathub'
mapfile -t apps < <(grep -v '^[[:space:]]*#' /tmp/flatpaks-list | grep -v '^[[:space:]]*$')
if (( ${#apps[@]} == 0 )); then
echo "No flatpaks listed in /tmp/flatpaks-list; the Brewfile conversion is broken" >&2
exit 1
fi
flatpak install --system --noninteractive --no-related --or-update flathub "${apps[@]}"

# Ghostty, from the TunaOS OCI remote.
#
# Utah ships no terminal emulator at all otherwise. Bluefin's own image test
# asserts ptyxis, but ptyxis is not in Bluefin's package contract because
# Fedora's base image carries it -- and Hummingbird's does not, nor does it
# package ptyxis, vte291 or gnome-console, so there is nothing to install.
# Until this factory builds a terminal, the flatpak is the terminal.
#
# Kept out of the Brewfile-derived list on purpose: that list is the parity
# contract with Bluefin and verify-desktop-contract compares it byte for byte.
# This is Utah's own addition and does not belong in it.
flatpak remote-add --system --if-not-exists tuna-os \
https://tunaos.org/flatpak/tuna-os.flatpakrepo
flatpak install --system --noninteractive --no-related --or-update \
tuna-os com.mitchellh.ghostty
flatpak uninstall --system --noninteractive --unused || true

mkdir -p "${FLATPAK_CACHE}"
rsync -a --delete /var/lib/flatpak/repo/ "${FLATPAK_CACHE}/repo/"
# Replacing the directory outright is what --delete was for: a stale object
# left in the cache would be seeded into the next build and never collected.
rm -rf "${FLATPAK_CACHE}/repo"
mkdir -p "${FLATPAK_CACHE}/repo"
cp -a /var/lib/flatpak/repo/. "${FLATPAK_CACHE}/repo/"
109 changes: 109 additions & 0 deletions iso/scripts/boot-installed.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
#!/usr/bin/env bash
# Boot the disk `just luks-test` installed, with a console you can drive.
#
# The end-to-end test proves the system works and then throws the machine
# away. This keeps it: same disk, same firmware variables, but a VNC display
# and an optional browser console so the result can be used rather than only
# asserted about.
#
# The disk is opened through a qcow2 overlay, so anything done here is
# discarded on the next run and the verified artifact stays as the test left
# it.
#
# The root volume is encrypted. Plymouth asks for the passphrase on the
# console before anything else happens.
set -euo pipefail

WORK="${UTAH_E2E_WORK:-/var/tmp/utah-luks-e2e}"
BASE="${WORK}/install.qcow2"
VARS_SRC="${WORK}/ovmf-vars-installed.fd"
OVERLAY="${WORK}/try.qcow2"
VARS="${WORK}/try-vars.fd"
VNC_DISPLAY="${UTAH_TRY_VNC:-1}"
VNC_PORT=$((5900 + VNC_DISPLAY))
WEB_PORT="${UTAH_TRY_WEB_PORT:-8080}"
SSH_PORT="${UTAH_TRY_SSH_PORT:-2299}"
NOVNC_IMAGE="${UTAH_TRY_NOVNC_IMAGE:-docker.io/geek1011/easy-novnc:latest}"

[[ -f "${BASE}" ]] || {
echo "No installed disk at ${BASE} -- run 'just luks-test' first." >&2
exit 1
}
# The firmware variables matter as much as the disk: the installer writes an
# NVRAM boot entry and this ESP has no \EFI\BOOT\BOOTX64.EFI fallback, so a
# fresh variable store boots to the EFI shell instead of to Utah.
[[ -f "${VARS_SRC}" ]] || {
echo "No firmware variables at ${VARS_SRC} -- rerun 'just luks-test'." >&2
exit 1
}

QEMU="$(command -v qemu-system-x86_64 /usr/libexec/qemu-kvm 2>/dev/null | head -1)"
[[ -n "${QEMU}" ]] || { echo "qemu-system-x86_64 not found" >&2; exit 1; }
OVMF_CODE=""
for f in /usr/share/edk2/ovmf/OVMF_CODE.fd /usr/share/OVMF/OVMF_CODE_4M.fd \
/usr/share/OVMF/OVMF_CODE.fd \
/home/linuxbrew/.linuxbrew/share/qemu/edk2-x86_64-code.fd; do
[[ -f "$f" ]] && { OVMF_CODE="$f"; break; }
done
[[ -n "${OVMF_CODE}" ]] || { echo "OVMF firmware not found" >&2; exit 1; }

if [[ -f "${WORK}/try.pid" ]] && kill -0 "$(cat "${WORK}/try.pid")" 2>/dev/null; then
echo "Already running (pid $(cat "${WORK}/try.pid")). Stop it with:"
echo " kill \$(cat ${WORK}/try.pid)"
exit 0
fi

rm -f "${OVERLAY}"
qemu-img create -f qcow2 -b "${BASE}" -F qcow2 "${OVERLAY}" >/dev/null
cp -f "${VARS_SRC}" "${VARS}"

"${QEMU}" -name utah-try \
-machine q35 -cpu host -m 8192 -smp 4 -accel kvm \
-drive "if=pflash,format=raw,readonly=on,file=${OVMF_CODE}" \
-drive "if=pflash,format=raw,file=${VARS}" \
-drive "if=none,id=disk,file=${OVERLAY},format=qcow2" \
-device virtio-blk-pci,drive=disk \
-netdev "user,id=net0,hostfwd=tcp::${SSH_PORT}-:22" \
-device virtio-net-pci,netdev=net0 \
-vnc "127.0.0.1:${VNC_DISPLAY}" \
-monitor "unix:${WORK}/try-monitor.sock,server,nowait" \
-serial "file:${WORK}/try-serial.log" \
-daemonize -pidfile "${WORK}/try.pid"

echo "Utah is booting."
echo
echo " VNC vnc://127.0.0.1:${VNC_PORT}"

# A browser console is nicer than asking for a VNC client, but it is a
# convenience: if the proxy image cannot be fetched, the VNC port above is
# still there and the VM is unaffected.
if command -v podman >/dev/null 2>&1; then
podman rm -f utah-novnc >/dev/null 2>&1 || true
if podman run -d --name utah-novnc --network host "${NOVNC_IMAGE}" \
--addr "127.0.0.1:${WEB_PORT}" --host 127.0.0.1 --port "${VNC_PORT}" \
--no-url-password >/dev/null 2>&1; then
echo " Browser http://127.0.0.1:${WEB_PORT}"
# Open it. The point of a browser console is not having to go and find
# it. UTAH_TRY_OPEN=0 for a headless host, where xdg-open has nothing
# to open and would just print an error.
if [[ "${UTAH_TRY_OPEN:-1}" == "1" ]] && command -v xdg-open >/dev/null 2>&1; then
setsid xdg-open "http://127.0.0.1:${WEB_PORT}/" >/dev/null 2>&1 &
fi
else
echo " (browser console unavailable: could not start ${NOVNC_IMAGE})"
fi
fi

cat <<EOF

SSH ssh -p ${SSH_PORT} utahtest@127.0.0.1
Serial ${WORK}/try-serial.log

The root volume is encrypted, so Plymouth asks for a passphrase first.
Defaults from the test, overridable there:

passphrase testpassphrase
user utahtest / utahtest

Stop it with: kill \$(cat ${WORK}/try.pid) && podman rm -f utah-novnc
EOF
Loading
Loading