Some checks are pending
ci / test (push) Waiting to run
- Excised standalone dwl packages: gui-wm/dwl, waybar, wofi, mako, swaybg, swayidle, swaylock - Removed standalone dwl session and helper assets: PHOEBUS_SESSION_SCRIPT, PHOEBUS_MENU_SCRIPT, PHOEBUS_LOCK_SCRIPT, PHOEBUS_IDLE_SCRIPT, WAYBAR_CONFIG, WAYBAR_STYLE, phoebus-dwl.desktop - Consolidated DesktopProfile enum to Mango (default) and None (headless), rejecting legacy dwl configurations - PHOEBUS_MANGO_SESSION_SCRIPT (/usr/local/bin/phoebus-session-mango) fails visibly/diagnostically on error without silent fallback - Provided /usr/local/bin/phoebus-session as a direct wrapper to phoebus-session-mango - Live ISO emitted assets reduced from 24 to 17 and verified clean
166 lines
9.3 KiB
Bash
166 lines
9.3 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.
|
|
|
|
## 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 starts the
|
|
Mango + DarkMaterial session. Automatic login is **live-only** and is
|
|
never copied to the installed system; see ADR 0009.
|