phoebus_os/installer/live/README.md
Phoebus d6fa7c8dce feat(live): build a Debian-Live installer appliance ISO (no root)
Add installer/live/build.sh: overlay the static installer, the OpenCode
manifest and the Debian tools the standard live image lacks (cryptsetup,
btrfs-progs, gdisk, dosfstools, parted, util-linux-extra) onto a Debian-Live
stable base, patch the boot config for a serial console, and preserve the
hybrid BIOS+UEFI boot. The live squashfs is never repacked and libc is never
bundled, so the appliance is unchanged and the target remains Gentoo-only.
Records ADR 0005 and the implementation plan.
2026-09-20 12:49:31 -07:00

2.3 KiB

Phoebus installer appliance (Debian-Live base)

Builds the bootable Phoebus installer ISO. The appliance is Debian, the installed system is Gentoo: the live medium only partitions, encrypts and formats the target, downloads a verified Gentoo stage3, and drives Portage inside a chroot. Nothing from the appliance is installed; it disappears at reboot.

Design decisions: docs/PLAN-DEBIAN-LIVE.md and docs/adr/0005-debian-live-appliance.md.

No-root remaster

The script does not repack the live squashfs (that would destroy ownership and setuid bits without root). Instead it leaves the Debian-Live filesystem untouched and overlays a /phoebus directory onto the ISO:

/phoebus/
  bin/phoebus-installer   static Rust installer
  bin/sys                 static typed system broker
  bin/phoebus             launcher: stages to /tmp, sets PATH/LD_LIBRARY_PATH
  tools/                  Debian packages the live image lacks
                          (cryptsetup, btrfs-progs, gdisk, dosfstools,
                           parted, util-linux-extra)
  opencode.manifest
  README

The launcher copies /phoebus to /tmp/phoebus-payload and prepends the bundled usr/sbin/usr/bin to PATH, so the installer finds cryptsetup, sgdisk, partprobe, mkfs.fat and mkfs.btrfs. Only the libraries the live image lacks are bundled (never libc), so the live system's own tools are not shadowed.

Build

Prerequisites: xorriso, mksquashfs, curl, dpkg-deb, 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

Then:

installer/live/build.sh

Output: installer/live/phoebus-installer-amd64.iso (+ .sha256). The base Debian-Live ISO is downloaded to the repo root if absent and verified against base.sha256. These artifacts are gitignored.

Use

Boot the ISO (UEFI or BIOS). It auto-boots a serial-visible live system; log in as user / live (passwordless sudo). Then:

/run/live/medium/phoebus/bin/phoebus --help
sudo /run/live/medium/phoebus/bin/phoebus --config FILE --install --yes \
  --luks-passphrase-file /secure/luks.pw --user-password-file /secure/user.pw

Secrets are only ever supplied as 0600 files. The live user's /tmp is the staging area; the medium itself is read-only.