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

68 lines
2.3 KiB
Bash

# 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:
```sh
cd installer-rs
RUSTFLAGS="-C target-feature=+crt-static" \
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
```
Then:
```sh
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:
```sh
/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.