phoebus_os/installer/live
Phoebus 3515f1cf12
Some checks are pending
ci / test (push) Waiting to run
feat(desktop): streamline installer UX and add DWM keybindings
- Add canonical DWM / DWL keybindings to MANGO_CONFIG_DEFAULT (Mod+Shift+Return
  terminal, Mod+Return zoom, Mod+j/k focusstack, Mod+Shift+j/k movestack, Mod+h/l
  setmfact, Mod+i/d incnmaster, Mod+Shift+c/q killclient, Mod+t/m/f layouts,
  Mod+Shift+Space float toggle, Mod+Tab view previous, Mod+1..9 tags,
  Mod+Shift+1..9 movetotag, mouse window drag/resize)
- Close Welcome window on installer launch to allow full-screen tiling
- Rewrite PhoebusCombo into a scrollable dropdown with search and vertical scrollbar
- Parse XKB rules (evdev.lst / base.lst) for standard desktop keyboard layouts
- Streamline installer defaults: lock to Mango + DankMaterialShell, Btrfs with
  snapshots, and Nix + Flatpak enabled (removing confusing manual choices)
- Simplify Account step: username only, single password with disk encryption toggle,
  and remove artificial 8-character password length limit
- Direct installation confirmation without typing ERASE or ticking confirmation box
- Fix live progress log details view with a dedicated scrollable log box and 1.5s timer
2026-09-22 18:17:31 -07:00
..
desktop feat(desktop): streamline installer UX and add DWM keybindings 2026-09-22 18:17:31 -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(installer): graphical welcome and install wizard over a typed bridge 2026-09-21 13:13:40 -07:00
install-help.txt feat(installer): graphical welcome and install wizard over a typed bridge 2026-09-21 13:13:40 -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(installer): graphical welcome and install wizard over a typed bridge 2026-09-21 13:13:40 -07:00
README.md feat(installer): graphical welcome and install wizard over a typed bridge 2026-09-21 13:13:40 -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, 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:

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.

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.