Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 3 additions & 1 deletion Containerfile
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ COPY scripts/install-packages.py \
scripts/configure-services.sh \
scripts/configure-branding.sh \
scripts/verify-desktop-contract.py \
scripts/verify-first-boot.sh \
scripts/verify-gnome-extensions.py \
/tmp/utah-scripts/
# Common publishes Bluefin artwork, desktop defaults, Brewfiles, and setup
Expand All @@ -77,8 +78,9 @@ RUN for pair in install-packages.py:utah-install-packages \
configure-services.sh:utah-configure-services \
configure-branding.sh:utah-configure-branding \
verify-desktop-contract.py:utah-verify-desktop-contract \
verify-first-boot.sh:utah-verify-first-boot \
verify-gnome-extensions.py:utah-verify-gnome-extensions; do \
install -m 0755 "/tmp/utah-scripts/${pair%%:*}" "/usr/local/libexec/${pair##*:}" || exit 1; \
install -Dm0755 "/tmp/utah-scripts/${pair%%:*}" "/usr/local/libexec/${pair##*:}" || exit 1; \
done && \
cp -a /tmp/utah-common/. / && \
cp -a /tmp/utah-bluefin/. / && \
Expand Down
8 changes: 8 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ check:
grep -q 'enable ublue-system-setup.service' system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset
test -f scripts/configure-services.sh
bash -n scripts/configure-services.sh
test -f scripts/verify-first-boot.sh
bash -n scripts/verify-first-boot.sh
test -f scripts/configure-branding.sh
bash -n scripts/configure-branding.sh
test -f scripts/verify-desktop-contract.py
Expand All @@ -33,10 +35,16 @@ check:
git submodule update --init --recursive
python3 -m py_compile scripts/verify-desktop-contract.py scripts/verify-gnome-extensions.py
python3 scripts/verify-desktop-contract.py --check contracts/bluefin-desktop.toml
test -f tests/unit/test_first_boot.py
python3 tests/unit/test_first_boot.py
python3 scripts/verify-gnome-extensions.py --source
grep -q '/system_files/bluefin' Containerfile
grep -q 'flatpak-preinstall.service' scripts/configure-services.sh
grep -q 'flathub.flatpakrepo' scripts/configure-services.sh
grep -q 'input-remapper.service' scripts/configure-services.sh
grep -q 'bluefin-stats-refresh.timer' scripts/configure-services.sh
grep -q 'UTAH_FIRST_BOOT_OK' scripts/verify-first-boot.sh
grep -q 'UTAH_EXPECT_REPEAT' scripts/verify-first-boot.sh
test -f iso/live/Containerfile
test -f iso/live/src/configure-live.sh
test -f iso/live/src/install-flatpaks.sh
Expand Down
29 changes: 29 additions & 0 deletions contracts/bluefin-desktop.toml
Original file line number Diff line number Diff line change
Expand Up @@ -129,14 +129,43 @@ apps = [
"page.tesk.Refine",
]

[first_boot]
# These are the hooks copied into the image by Utah or the Bluefin-derived
# common layer. The runtime verifier syntax-checks every one before checking
# first-boot service results.
hooks = [
"/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh",
"/usr/share/ublue-os/privileged-setup.hooks.d/11-framework-ucsi-workaround.sh",
"/usr/share/ublue-os/privileged-setup.hooks.d/99-flatpaks.sh",
"/usr/share/ublue-os/user-setup.hooks.d/12-gnupg.sh",
"/usr/share/ublue-os/user-setup.hooks.d/20-framework.sh",
"/usr/share/ublue-os/user-setup.hooks.d/99-privileged.sh",
]
deferred_state = "/var/lib/ublue/setup-services/tailscale.deferred"

[first_boot.file_contains]
"/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh" = [
"command -v tailscale",
"tailscale.deferred",
"rerun ublue-privileged-setup",
]

[services]
enabled = [
"bootc-unified-storage.service",
"bluefin-stats-refresh.timer",
"brew-setup.service",
"dconf-update.service",
"flatpak-nuke-fedora.service",
"flatpak-preinstall.service",
"gdm.service",
"input-remapper.service",
"ublue-system-setup.service",
"uupd.timer",
]
user_enabled = [
"ublue-user-setup.service",
]
optional = [
"tailscaled.service",
]
5 changes: 5 additions & 0 deletions docs/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@ just build-ghcr utah testing main
just generate-bootable-image testing
just boot-vm

# From the booted VM, validate first-boot units and repeat-boot state:
sudo /usr/local/libexec/utah-verify-first-boot
# Reboot, then run:
sudo UTAH_EXPECT_REPEAT=1 /usr/local/libexec/utah-verify-first-boot

# Optional local diagnostics over SSH (never use for a published image):
ENABLE_SSHD=1 just build-ghcr utah testing main
```
Expand Down
46 changes: 44 additions & 2 deletions docs/skills/desktop-contract.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: desktop-contract
version: "1.0"
last_updated: "2026-09-05"
last_updated: "2026-09-11"
id: desktop-contract
one_line_purpose: Maintain Utah identity, Bluefin desktop defaults, and first-boot Flatpak policy.
entry_point: docs/skills/desktop-contract.md
Expand Down Expand Up @@ -54,10 +54,17 @@ The TOML's sections are the contract's table of contents:
(`https://dl.flathub.org/repo/`), the Bazaar preinstall, the
`99-flatpaks.sh` privileged-setup hook, and the system-flatpaks Brewfile
whose app list the contract enumerates.
- **`[first_boot]`** — hooks that must be present and parse as shell before
the image is considered bootable. The Tailscale hook also documents the
persistent deferred-state file used when its optional binary is absent.
- **`[services]`** — systemd units the preset must enable: `gdm.service`,
`ublue-system-setup.service`, `flatpak-preinstall.service`,
`flatpak-nuke-fedora.service`, `brew-setup.service`, `dconf-update.service`,
`bootc-unified-storage.service`, `uupd.timer`.
`bootc-unified-storage.service`, `input-remapper.service`,
`bluefin-stats-refresh.timer`, `uupd.timer`, and the global
`ublue-user-setup.service`. `tailscaled.service` is optional: when its unit
is present it must be enabled, and when its package is absent the hook must
leave a retryable state instead of invoking a missing command.

## GNOME extensions are pinned submodules

Expand Down Expand Up @@ -98,6 +105,38 @@ under `[services]` in `packages/utah.toml` and configured in
`scripts/configure-services.sh`, which also disables `PrivateTmp` on
`systemd-resolved.service` for bootc early-boot DNS resolution.

`input-remapper.service` and `bluefin-stats-refresh.timer` are explicit policy,
not incidental package defaults. The stats unit checks the writable `/var`
mount and creates `/var/cache/bluefin` at execution time because image cleanup
removes build-time cache directories.

## First-boot runtime validation

The image contains `/usr/local/libexec/utah-verify-first-boot`. Run it from a
booted Utah system after the graphical session is available:

```bash
sudo /usr/local/libexec/utah-verify-first-boot
```

It checks the enabled system and global user setup units, failed setup results,
hook syntax, the Flathub remote, the declared system Flatpaks, the update and
statistics policy, and the optional Tailscale path. It writes a persistent
key/value report to `/var/lib/utah/first-boot-status` and prints one of
`UTAH_FIRST_BOOT_OK`, `UTAH_FIRST_BOOT_RETRYABLE`, or
`UTAH_FIRST_BOOT_FAIL`. A missing network-dependent Flatpak or optional
Tailscale package is reported as retryable with the next action visible in the
report; it is not silently treated as installed.

After rebooting the same disposable system, request the repeat-boot assertion:

```bash
sudo UTAH_EXPECT_REPEAT=1 /usr/local/libexec/utah-verify-first-boot
```

The report records the boot ID and increments its boot count, so a second
invocation in the same boot cannot masquerade as a repeat-boot result.

## The verifiers run twice

The same verifier runs in the Containerfile and on demand, so a local image
Expand All @@ -113,6 +152,9 @@ or a CI artifact can be checked after the fact (recipe comment, `Justfile`,
already-composed image: the desktop verifier and the contract are
bind-mounted from the working tree, the extension verifier runs from the
image's own `/usr/local/libexec`.
- **After boot** — run `utah-verify-first-boot` in the guest. This is the only
check that can observe first-boot unit failures, actual Flatpak installation,
deferred optional setup, and a changed boot ID across a reboot.
- **Off-image** — `verify-desktop-contract.py --check` validates the contract
TOML itself in source-only CI and is part of `just check`; it asserts
nothing about any image.
Expand Down
4 changes: 2 additions & 2 deletions docs/skills/index.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"generated_at": "2026-09-05",
"generated_at": "2026-09-11",
"schema_version": "1.0",
"skills": [
{
Expand Down Expand Up @@ -53,7 +53,7 @@
],
"description": "The runtime desktop contract in contracts/bluefin-desktop.toml and its in-image verifiers. Use when changing branding, os-release, service presets, GNOME extensions, or first-boot Flatpak behavior.",
"version": "1.0",
"last_updated": "2026-09-05",
"last_updated": "2026-09-11",
"doc_type": "policy"
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/skills/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
This file is a human-readable mirror of `index.json`. Both are generated by
`scripts/generate_skill_index.py` — do not hand-edit either file.

Generated: 2026-09-05 · schema 1.0 · 8 skills
Generated: 2026-09-11 · schema 1.0 · 8 skills

| id | category | status | one-line purpose |
|---|---|---|---|
Expand Down
55 changes: 37 additions & 18 deletions scripts/configure-services.sh
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,23 @@ user_unit_exists() {
return 1
}

enable_unit() {
unit_exists "$1" && systemctl enable "$1" || true
# Under `set -e` above, a missing required unit aborts this script and fails
# the image build for every flavor -- not just this one. Only mark a unit
# required here if losing it silently would be worse than a broken build.
enable_required_unit() {
if ! unit_exists "$1"; then
echo "Required desktop unit is missing: $1" >&2
return 1
fi
systemctl enable "$1"
}

enable_optional_unit() {
if unit_exists "$1"; then
systemctl enable "$1"
else
echo "Optional desktop unit is unavailable; leaving it disabled: $1"
fi
}

disable_unit() {
Expand All @@ -35,20 +50,21 @@ disable_unit() {

# Services shared with Bluefin LTS. Optional units are guarded because
# Hummingbird intentionally does not ship every Bluefin integration package.
enable_unit rechunker-group-fix.service
enable_unit brew-setup.service
enable_unit flatpak-nuke-fedora.service
enable_unit flatpak-preinstall.service
enable_unit gdm.service
enable_unit firewalld.service
enable_unit fwupd.service
enable_unit fwupd-refresh.timer
enable_unit dconf-update.service
enable_unit tailscaled.service
enable_unit uupd.timer
enable_unit ublue-system-setup.service
enable_unit systemd-resolved.service
enable_unit bootc-unified-storage.service
enable_optional_unit rechunker-group-fix.service
enable_required_unit brew-setup.service
enable_required_unit flatpak-nuke-fedora.service
enable_required_unit flatpak-preinstall.service
enable_required_unit gdm.service
enable_required_unit firewalld.service
enable_required_unit fwupd.service
enable_required_unit fwupd-refresh.timer
enable_required_unit dconf-update.service
enable_optional_unit tailscaled.service
enable_required_unit ublue-system-setup.service
enable_required_unit systemd-resolved.service
enable_required_unit bootc-unified-storage.service
enable_required_unit input-remapper.service
enable_required_unit bluefin-stats-refresh.timer

# Bluefin's Brewfile and Bazaar preinstall hook need the Flathub remote before
# first boot. Keep this as a .flatpakrepo descriptor so the remote is available
Expand All @@ -68,7 +84,7 @@ systemctl mask bootc-fetch-apply-updates.timer bootc-fetch-apply-updates.service
# local debug build. The preset must agree or first-boot preset-all will undo
# the build-time enablement.
if [[ "${ENABLE_SSHD:-0}" == "1" ]]; then
enable_unit sshd.service
enable_optional_unit sshd.service
sed -i 's/^disable sshd.service$/enable sshd.service/' \
/usr/lib/systemd/system-preset/85-utah-desktop.preset
else
Expand All @@ -81,6 +97,9 @@ if user_unit_exists podman-auto-update.timer; then
fi
if user_unit_exists ublue-user-setup.service; then
systemctl --global enable ublue-user-setup.service
else
echo "Required global user setup unit is missing: ublue-user-setup.service" >&2
exit 1
fi

# Match Bluefin's login behavior. The operations are idempotent and authselect
Expand All @@ -93,7 +112,7 @@ authselect enable-feature with-fingerprint
install -Dm0755 /tmp/uupd/uupd /usr/bin/uupd
install -Dm0644 /tmp/uupd/uupd.service /usr/lib/systemd/system/uupd.service
install -Dm0644 /tmp/uupd/uupd.timer /usr/lib/systemd/system/uupd.timer
systemctl enable uupd.timer
enable_required_unit uupd.timer
# Avoid pulling the distrobox module on every update, as in Bluefin LTS.
sed -i 's|uupd|& --disable-module-distrobox|' /usr/lib/systemd/system/uupd.service

Expand Down
Loading