phoebus_os/installer/live
Phoebus bbd3d89d6a
Some checks are pending
ci / test (push) Waiting to run
feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO
- desktop.profile defaults to mango with Flatpak on; explicit none/minimal/dwl/
  full still win. The plan shows the selected session.
- Installed login uses greetd + tuigreet (authentication required, Mango default,
  dwl selectable); live autologin is a separate live-only configuration.
- installer/live/build.sh builds a rootless Debian testing rootfs with Mango
  (pinned source build), DankMaterialShell (pinned SHA-256 release), Quickshell,
  scenefx, Qt Wayland and greetd, then splices it into the base Debian-Live boot
  equipment. Live autologin, an Install Phoebus launcher and a serial/VT
  recovery console are included and the build fails clearly if a desktop
  component is missing. Verified in a graphical seat-providing VM (Mango + DMS +
  Quickshell; DMS panel captured).
- Shared desktop assets emitted by phoebus-installer --emit-asset, a graphical
  VM driver (live-driver.py), and regression tests for defaults/overrides,
  login, live/installed separation and the live ISO guards.
- Docs updated: ADR 0005/0009, STATUS, HANDOFF, CHANGELOG, ROADMAP, DEVELOPMENT
  and VM-BOOT-VERIFICATION.
2026-09-21 06:47:22 -07:00
..
payload feat(live): build a Debian-Live installer appliance ISO (no root) 2026-09-20 12:49:31 -07:00
base.sha256 feat(live): build a Debian-Live installer appliance ISO (no root) 2026-09-20 12:49:31 -07:00
build.sh feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO 2026-09-21 06:47:22 -07:00
live-packages.list feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO 2026-09-21 06:47:22 -07:00
livefs-hook.sh feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO 2026-09-21 06:47:22 -07:00
README.md feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO 2026-09-21 06:47:22 -07:00
releases.sha256 feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO 2026-09-21 06:47:22 -07:00
tools.list feat(live): build a Debian-Live installer appliance ISO (no root) 2026-09-20 12:49:31 -07:00

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, installs the shared session assets emitted by the static installer (phoebus-installer --emit-asset ...), builds Mango from source, installs the pinned DMS release, and enables greetd, networking and the serial console.
  4. 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.
  5. The base Debian-Live ISO (base.sha256) is used only for its boot equipment: the live squashfs, kernel, initramfs and a serial-patched GRUB configuration 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:

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=.

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. The Install Phoebus entry in the launcher opens the installer UI; it never starts a destructive operation by itself (the plan, disk protection, AI requirement, credential handling and the ERASE confirmation all remain in force).
  • 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.

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.