phoebus_os/installer/live/README.md
Phoebus 0f6d503c2e
Some checks are pending
ci / test (push) Waiting to run
docs(live): document the PHOEBUS_REUSE_ROOTFS build cache
2026-09-21 06:47:53 -07:00

79 lines
3.8 KiB
Bash

# 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:
```sh
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. 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.