Live image ships gnupg plus the Gentoo release key, fingerprint-checked at build time against the published release-key fingerprints, so the fail-closed DIGESTS verification cannot be silently skipped. Rollback harness: authenticate sudo (unique end markers, verified timestamp, abort instead of hanging), run both guest phases as root, use explicit --legacy for snapshot/break/undo, fix the verify SYS path, emit the real systemd state, and preserve the phase-1 transcript. |
||
|---|---|---|
| .. | ||
| desktop | ||
| payload | ||
| base.sha256 | ||
| build.sh | ||
| install-help.txt | ||
| live-packages.list | ||
| livefs-hook.sh | ||
| README.md | ||
| releases.sha256 | ||
| tools.list | ||
Phoebus installer + live desktop ISO
Builds the bootable Phoebus medium. The live medium is Debian; the installed
system is Gentoo. The live image boots directly into Mango +
DankMaterialShell; the installer it launches partitions, encrypts and formats
the target, downloads a verified Gentoo stage3 and drives Portage inside a
chroot. Nothing from Debian is installed into the Gentoo target.
Design: docs/PLAN-DEBIAN-LIVE.md, ADR 0005 (appliance), ADR 0009 (desktop).
How it is built (rootless)
The build runs entirely unprivileged and never touches a host disk:
- Fetch and SHA-256 verify the pinned desktop sources
(
releases.sha256): the Mango source release and the DankMaterialShell release tarball. mmdebstrap --mode=unshare --format=tar testingbuilds a Debian testing rootfs from the signed Debian archive. Testing is required because it provides wlroots 0.20, scenefx 0.5 and quickshell, which Mango and DMS need. The Debian archive keyring is fetched from Debian and handed to mmdebstrap.- A customize hook (
livefs-hook.sh) runs inside the rootfs: it creates the unprivilegedphoebususer, builds Mango from source, installs the pinned DMS release, and enablesgreetd, networking and the serial console. - After the rootfs is extracted,
build.shinstalls the live payload: the static installer, the shared desktop assets emitted byphoebus-installer --emit-asset, the branding (emblem, wordmark, wallpaper, tokens), the Quickshell welcome/installer configs, the live-only marker/etc/phoebus/live, the version/build files, the help text, and DMS's "already welcomed" markers. Keeping this post-extract letsPHOEBUS_REUSE_ROOTFS=1pick up asset changes without a new mmdebstrap. - The rootfs is extracted as the current user and packed with
mksquashfs -all-root; a tmpfiles rule restores the live user's home ownership at boot. - The base Debian-Live ISO (
base.sha256) is used only for its boot equipment: the live squashfs, kernel, initramfs and a serial-patched, Phoebus-branded GRUB configuration (menu names, colours and a rasterised wallpaper) are replaced, andxorriso -boot_image any keeppreserves the UEFI/BIOS boot path.
No curl | sh, no live/git packages, and signature verification is never
disabled. Debian packages are used only on the live medium. The live image
ships gnupg plus the trusted Gentoo release key at
/usr/share/openpgp-keys/gentoo-release.asc (provisioned by build.sh and
checked against Gentoo's published release-key fingerprints), so the
installer's signed-DIGESTS stage3 verification cannot be silently skipped.
Build
Prerequisites: mmdebstrap, xorriso, squashfs-tools, curl, dpkg-deb,
unshare, and the static installer built first:
cd installer-rs
RUSTFLAGS="-C target-feature=+crt-static" \
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
cd ..
installer/live/build.sh
The default work directory is /var/tmp/phoebus-live/build (world-traversable,
because the rootless user namespace cannot enter a 0750 home directory);
override with WORKDIR=. Output defaults to
installer/live/phoebus-installer-amd64.iso (+ .sha256); override with OUT=.
For fast iteration, PHOEBUS_REUSE_ROOTFS=1 reuses an already-built
$WORKDIR/livefs.tar instead of re-running mmdebstrap; the assemble and pack
steps still run, so a normal build never needs it.
A normal build produces the Mango desktop image. The build fails clearly if
mango, dms, quickshell, the live autologin config or the "Install Phoebus"
launcher is missing; it never silently emits a text-only ISO.
Using the live medium
- It auto-boots to a serial-visible live system and logs in automatically
as
phoebus(only on the live medium). - The graphical session starts automatically and opens the branded Phoebus welcome window: "Install Phoebus OS" is the dominant action, with network, display/keyboard, accessibility, help, keyboard-test and power tools, and troubleshooting tools under Advanced. It never authorizes or starts disk changes. DMS's upstream first-run dialogs are suppressed on the live medium.
- The welcome's action (and the Install Phoebus OS desktop entry) opens the
graphical installer wizard, which talks to the Rust backend over the typed
phoebus-installer --gui-bridgeJSON protocol: language/keyboard/timezone, network and prerequisites, AI model connection, destination disk (protected disks and the installation medium are identified and unselectable), account and encryption, review,ERASEauthorization, real-stage progress and completion. A second launch never opens a duplicate session. If Quickshell or Wayland is unavailable the launcher falls back to the TUI/CLI. - A text recovery console is available on the serial line and on another VT
(
Ctrl+Alt+F2): log in asphoebus/phoebus(live-only credential) and usesudowith that password. Unattended (NOPASSWD) escalation is scoped to the two typed brokers —/usr/local/bin/phoebus-installerand/usr/local/bin/sys— plussystemctl poweroff/reboot. There is noNOPASSWD: ALL, nosh -cand no wildcard; the policy is emitted aslive-sudoers, installed to/etc/sudoers.d/90-phoebus-liveand validated withvisudoat build time. The password-authenticated recovery console is deliberate and preserved.
NVIDIA accelerated graphics
The live medium bundles NVIDIA's accelerated driver so a supported GPU boots into Mango + DankMaterialShell accelerated without downloading or compiling anything at boot.
- The driver comes from the signed Debian archive's
contrib,non-freeandnon-free-firmwarecomponents (enabled inbuild.sh). Thetestingsuite currently ships branch 550.163.01; its proprietary kernel modules cover Maxwell through Ada/Hopper. Blackwell is not supported by this branch; on a Blackwell GPU the live medium falls back to the in-treenouveaudriver. - The live kernel is pinned to Debian stable (trixie, 6.12 LTS). Debian
testing's current kernel (7.2) removed the
strncpydeclaration the 550 driver still uses, sonvidia-kernel-dkmscannot build against it; the rolling kernel metas are removed from the package list andbuild.shresolves and installs the exact stable kernel, headers and kbuild packages fromtrixie(pinned in an apt setup hook). The rest of the rootfs stays on testing for wlroots 0.20 / scenefx 0.5 / Quickshell. livefs-hook.shbuilds the DKMS modules against that exact kernel and fails the build if any of the four modules is missing. Debian'snvidia-kernel-dkmsrenames themnvidia-current,nvidia-current-modeset,nvidia-current-drmandnvidia-current-uvm; the verifier and the hook accept either that naming or the upstream names.build.shthen runsphoebus-installer --verify-live-nvidia. It is a compatibility gate, not a presence list: it rejects placeholder modules/libraries, requires every module to be registered in the live kernel'smodules.dep, checks the userspacelibnvidia-glcoreand firmware-directory versions against the bundled driver, infers and checks the module flavor, requires non-empty GSP firmware and the exactetc/modprobe.d/phoebus-nvidia.conf. It runs on every build, includingPHOEBUS_REUSE_ROOTFS=1, so a cached rootfs can never silently ship a mismatched payload. The bundled driver version, module flavor and kernel are recorded in/etc/phoebus/nvidiaon the medium.- The live load script makes a deterministic, device-based decision via
phoebus-installer --live-gpu-plan, not a0x10devendor grep. A supported GPU loads the bundled accelerated stack; an unsupported GPU (or a failed accelerated load) explicitlymodprobesnouveau; a machine with no NVIDIA display device leaves auto-detection alone.build.shwritesetc/modprobe.d/phoebus-nvidia.conf(replacing Debian's unconditional nouveau configuration), so the fallback is real. Debian's unconditional modules-load entry is removed in favour ofphoebus-nvidia.service, which runs the script before greetd/Mango. - The GRUB fail-safe graphics entry sets
nomodeset phoebus.nvidia=offand blacklists the NVIDIA modules for that boot; the load script and the unit both stand down, so recovery intent is authoritative. Usephoebus-gpu-reportfor read-only diagnostics (PCI devices, loaded modules,nvidia_drmmodeset,nvidia-smi, recent kernel messages). - The installed Gentoo target is unaffected: it uses Portage
(
x11-drivers/nvidia-drivers) with the branch/flavor selected from the PCI device IDs — open kernel modules for Turing and newer, the proprietary branch for Maxwell/Pascal/Volta, and nouveau for older cards. Seedocs/adr/0012-nvidia-driver-policy.md.
The NVIDIA live payload was built and verified in a minimal mmdebstrap rootfs
(driver 550.163.01, kernel 6.12.107+deb13-amd64, modules nvidia-current*).
Actual NVIDIA acceleration is not verified (no NVIDIA GPU on the build
host; see docs/STATUS.md).
Verification
installer/tests/vm/gui-driver.py drives the graphical ISO in a disposable
UEFI VM: gui (welcome + wizard journey and screenshots), install
(non-interactive install with the static binary and a secret-leak scan) and
boot (detached boot of the installed disk). See
docs/VM-BOOT-VERIFICATION.md for the recorded evidence.
Installed system
An installed system always authenticates through greetd and starts the
Mango + DarkMaterial session. Automatic login is live-only and is
never copied to the installed system; see ADR 0009.