phoebus_os/installer/live/README.md
Phoebus b4a6b5df80
Some checks are pending
ci / test (push) Waiting to run
feat(nvidia): hardware-driven driver policy, installed integration and live payload
- resolve the NVIDIA branch and kernel-module flavor from PCI device IDs
  (Turing+ open modules; Maxwell/Pascal/Volta proprietary, masked below 595;
  Fermi/Kepler fall back to nouveau, reported; unknown IDs reported)
- capture pci_id/pci_address in the probe; drive VIDEO_CARDS, package.use,
  package.accept_keywords, package.mask, modprobe.d and dracut from the plan,
  preserving hybrid Intel/AMD
- add the nvidia_drivers install stage (after the kernel, before boot) that
  emerges the driver, regenerates the initramfs, records /etc/phoebus/nvidia and
  fails the install on failure; sys update rebuilds modules and the initramfs
- refuse AI changes to x11-drivers/nvidia-drivers
- live ISO: signed non-free components, stable-kernel pin (testing 7.2 breaks
  the 550 driver), DKMS build for the exact kernel, gated pre-greetd load,
  fail-safe entry, gpu-report, and a --verify-live-nvidia build gate that runs
  on cached rootfs builds and fails on any missing component
- docs: ADR 0012, STATUS/CHANGELOG/HANDOFF, live README
- also carries the pending OpenCode model-variant/streaming changes and fixes
  the GUI bridge install thread join that could hang
2026-09-22 21:53:28 -07:00

155 lines
8.5 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),
passwordless `sudo`.
- 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`, which checks
the kernel modules, the GLVND/EGL/GBM userspace libraries, `nvidia-smi`, the
EGL external-platform manifests, the GSP firmware, the gated load script and
the nouveau blacklist. It runs on **every** build, including
`PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship without
the payload. The bundled driver version, module flavor and kernel are recorded
in `/etc/phoebus/nvidia` on the medium.
- Nouveau blacklisting and module options come from Debian's own
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in
favour of the live-only `phoebus-nvidia.service`, which runs the gated
`phoebus-nvidia-load` before greetd/Mango **only when an NVIDIA display device
is present**, so systems without one keep nouveau/virtio and record no failed
unit.
- The GRUB **fail-safe graphics** entry disables modesetting
(`nomodeset`) and blacklists the NVIDIA modules for that boot; it is the
documented recovery path when driver initialisation misbehaves. 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.