phoebus_os/docs/adr/0005-debian-live-appliance.md
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

2.9 KiB

ADR 0005: Debian-Live installer appliance, Gentoo-only target

  • Status: Accepted
  • Date: 2026-09-20
  • Updated: 2026-09-21 — the live medium now ships a full Mango + DankMaterialShell desktop. The overlay-only layout (tools.list, /phoebus payload) is superseded by a Debian testing rootfs built with mmdebstrap (installer/live/build.sh, installer/live/live-packages.list); the old overlay files are retained only for reference. The Gentoo-only target, replaceable-plumbing principle and signature policy are unchanged. See ADR 0009.

Context

The installer is a statically linked Rust binary that treats the live medium as replaceable plumbing. Rebuilding a Gentoo live environment for every ISO would require compiling a distribution on a small build host, which conflicts with the "no release VPS" constraint and adds no value to the product: the live medium only has to boot, network, and provide disk/encryption/filesystem tooling.

The reference Gentoo LiveGUI medium has served this role and is kept as a fallback, but it ties the appliance to Gentoo maintenance.

Decision

The installer appliance is a Debian-Live (stable) image with the Phoebus payload overlaid, and the target remains 100% Gentoo:

  • The live medium partitions, encrypts and formats the target, downloads a verified Gentoo systemd stage3, and drives Portage inside chroot.
  • The appliance's package manager, init and configuration tools are never run against the target. Target configuration is written as Gentoo files (/etc/portage/*, /etc/kernel/*, /etc/fstab, ...) and executed by Gentoo tools inside the chroot.
  • The ISO is produced without root by leaving the Debian-Live squashfs untouched and overlaying /phoebus (the installer, sys, OpenCode manifest, and the Debian packages the standard image lacks). Bundling libc is forbidden; only the libraries the live image lacks are shipped.
  • The boot configuration is made serial-console visible and auto-booting.

Debian is chosen for a binary, boring, glibc userspace: broad tool availability, compatibility with fetched third-party binaries such as OpenCode, and a low-maintenance, automatable build. Void is a reasonable alternative (glibc, binary packages); Alpine is rejected for musl/BusyBox compatibility friction.

Consequences

  • The appliance becomes replaceable plumbing; Phoebus's identity stays in the target.
  • The build is a small overlay (installer/live/build.sh) rather than a distro rebuild, and can run without root.
  • The live image lacks some tools, so installer/live/tools.list pins the Debian packages to inject; --check-live guards against drift.
  • Recursive-boot and Secure Boot are not verified; non-free firmware and Debian licence/attribution for the appliance are open items.
  • The rootless overlay means the live filesystem's own packages are unchanged, so the appliance tracks the upstream Debian-Live image.