Some checks are pending
ci / test (push) Waiting to run
Record the reliability pass across STATUS, HANDOFF, CHANGELOG, ADR 0012, the live README and the boot-verification log: the deterministic live GPU decision with a real nouveau fallback, the 580 legacy cap and mixed open/proprietary incompatibility, the compatibility verifier, the installed lifecycle fix, the repaired GUI harness, the automated but unrun rollback gate, and the scoped live sudoers. Withdraw the stale handoff claim that the gui_bridge tests hang (the workspace suite passes) and record the installed-target missing-sys gap.
167 lines
9.4 KiB
Bash
167 lines
9.4 KiB
Bash
# 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:
|
|
|
|
1. Fetch and **SHA-256 verify** the pinned desktop sources
|
|
(`releases.sha256`): the Mango source release and the DankMaterialShell
|
|
release tarball.
|
|
2. `mmdebstrap --mode=unshare --format=tar testing` builds 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.
|
|
3. A customize hook (`livefs-hook.sh`) runs inside the rootfs: it creates the
|
|
unprivileged `phoebus` user, **builds Mango from source**, installs the
|
|
pinned DMS release, and enables `greetd`, networking and the serial console.
|
|
4. After the rootfs is extracted, `build.sh` installs the live payload:
|
|
the static installer, the shared desktop assets emitted by
|
|
`phoebus-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 lets
|
|
`PHOEBUS_REUSE_ROOTFS=1` pick up asset changes without a new mmdebstrap.
|
|
5. 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.
|
|
6. 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, and `xorriso -boot_image any keep` preserves 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.
|
|
|
|
## Build
|
|
|
|
Prerequisites: `mmdebstrap`, `xorriso`, `squashfs-tools`, `curl`, `dpkg-deb`,
|
|
`unshare`, and the static installer built first:
|
|
|
|
```sh
|
|
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-bridge` JSON 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, `ERASE` authorization, 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 as `phoebus` / `phoebus` (live-only credential) and
|
|
use `sudo` with that password. Unattended (`NOPASSWD`) escalation is scoped
|
|
to the two typed brokers — `/usr/local/bin/phoebus-installer` and
|
|
`/usr/local/bin/sys` — plus `systemctl poweroff`/`reboot`. There is no
|
|
`NOPASSWD: ALL`, no `sh -c` and no wildcard; the policy is emitted as
|
|
`live-sudoers`, installed to `/etc/sudoers.d/90-phoebus-live` and validated
|
|
with `visudo` at build time. The password-authenticated recovery console is
|
|
deliberate and preserved.
|
|
- The `phoebus-dwl` session remains selectable as a fallback.
|
|
|
|
## 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-free` and
|
|
`non-free-firmware` components (enabled in `build.sh`). The `testing` suite
|
|
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-tree `nouveau` driver.
|
|
- The **live kernel is pinned to Debian stable (trixie, 6.12 LTS)**. Debian
|
|
testing's current kernel (7.2) removed the `strncpy` declaration the 550
|
|
driver still uses, so `nvidia-kernel-dkms` cannot build against it; the
|
|
rolling kernel metas are removed from the package list and `build.sh`
|
|
resolves and installs the exact stable kernel, headers and kbuild packages
|
|
from `trixie` (pinned in an apt setup hook). The rest of the rootfs stays on
|
|
testing for wlroots 0.20 / scenefx 0.5 / Quickshell.
|
|
- `livefs-hook.sh` builds the DKMS modules against that exact kernel and
|
|
**fails the build** if any of the four modules is missing. Debian's
|
|
`nvidia-kernel-dkms` renames them `nvidia-current`, `nvidia-current-modeset`,
|
|
`nvidia-current-drm` and `nvidia-current-uvm`; the verifier and the hook
|
|
accept either that naming or the upstream names.
|
|
- `build.sh` then runs `phoebus-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's
|
|
`modules.dep`, checks the userspace `libnvidia-glcore` and firmware-directory
|
|
versions against the bundled driver, infers and checks the module flavor,
|
|
requires non-empty GSP firmware and the exact
|
|
`etc/modprobe.d/phoebus-nvidia.conf`. It runs on **every** build, including
|
|
`PHOEBUS_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/nvidia` on the medium.
|
|
- The live load script makes a **deterministic, device-based decision** via
|
|
`phoebus-installer --live-gpu-plan`, not a `0x10de` vendor grep. A supported
|
|
GPU loads the bundled accelerated stack; an unsupported GPU (or a failed
|
|
accelerated load) explicitly `modprobe`s `nouveau`; a machine with no NVIDIA
|
|
display device leaves auto-detection alone. `build.sh` writes
|
|
`etc/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 of `phoebus-nvidia.service`, which
|
|
runs the script before greetd/Mango.
|
|
- The GRUB **fail-safe graphics** entry sets `nomodeset phoebus.nvidia=off` and
|
|
blacklists the NVIDIA modules for that boot; the load script and the unit both
|
|
stand down, so recovery intent is authoritative. Use `phoebus-gpu-report` for
|
|
read-only diagnostics (PCI devices, loaded modules, `nvidia_drm` modeset,
|
|
`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. See
|
|
`docs/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 defaults to the
|
|
Mango session, with dwl selectable. Automatic login is **live-only** and is
|
|
never copied to the installed system; see ADR 0009.
|