phoebus_os/docs/FINDINGS.md
Phoebus 1e5337e7a5 refactor!: retire the Bash installer tree and relocate its docs
Delete installer/bin, lib, tui, config, tests/*.sh and README.md now that the
Rust installer is the only proven path (docs/BASH-MIGRATION.md Phase 4). Move
FINDINGS.md and VM-BOOT-VERIFICATION.md to docs/ and delete the Bash-only
TESTING.md. The disposable VM harness under installer/tests/vm/ is retained.
2026-09-20 04:00:14 -07:00

4.8 KiB

Environment findings

This document records what was actually found in the reference environment before any installer code was written. Nothing here is assumed just because "Gentoo usually has it".

Reference media

  • Repository: /home/dominic/Source/phoebus_os
  • Reference image: livegui-amd64-20260913T163055Z.iso
    • Volume label: gentoo-amd64-livegui
    • 4.3 GiB ISO 9660 (El Torito, UEFI + BIOS bootable)
  • Root filesystem: image.squashfs (4.1 GiB) inside the ISO
  • Base system: Gentoo Base System release 2.18
  • Reference profile: default/linux/amd64/23.0/desktop/plasma (i.e. the LiveGUI is a KDE Plasma / OpenRC image)

Inspection was done by extracting image.squashfs with 7z and listing it with unsquashfs -l (365,567 entries); individual config files were extracted read-only. The host used for development is Ubuntu 26.04; the reference is used strictly as read-only data.

Init system mismatch (important)

The LiveGUI reference boots OpenRC/sysvinit (/etc/inittab present, no systemctl, /usr/lib/systemd/systemd-sysctl/systemd-udevd come from sys-apps/systemd-utils). Phoebus OS itself is systemd-based.

Consequence: the installer runs on an OpenRC live medium but installs a systemd target. Inside the target chroot, systemctl is available after the stage3, and service enablement is performed there. The installer must not assume the live environment can systemctl.

Tools found in the live environment

Present (usr/bin, usr/sbin, bin, sbin):

  • Shell: bash, coreutils, sed, awk, grep
  • TUI: dialog (and whiptail), libdialog, libncurses, tput
  • Portage: emerge, portageq, eselect, locale-gen
  • Disk: lsblk, blkid, findmnt, parted, sgdisk, gdisk, fdisk, sfdisk, wipefs, partprobe, udevadm, losetup, dmsetup
  • Filesystems: mkfs.btrfs, btrfs, btrfsck, mkfs.fat, mkfs.ext4, mkswap, swapon
  • Encryption: cryptsetup, gocryptfs
  • Network: NetworkManager/nmcli/nmtui, iw, wpa_supplicant, dhcpcd, ip, ping, rfkill
  • Boot: efibootmgr, grub-install, dracut; arch-chroot
  • Compiler/toolchain: gcc, make, git, rsync, curl, wget, openssl, gpg, sha256sum
  • Misc: lspci, lsusb, lscpu, dmidecode, smartctl, tmux, vim

Absent / not available in the live environment:

  • systemctl, bootctl, kernel-install, ukify, localectl, timedatectl, hostnamectl, systemd-cryptenroll
  • genkernel, jq (so all parsing is done in pure bash)
  • opencode, node, npm, flatpak

Portage configuration found

  • /etc/portage/make.conf: catalyst stage defaults, COMMON_FLAGS="-O2 -pipe", LC_MESSAGES=C.UTF-8
  • /etc/portage/make.profile -> .../desktop/plasma
  • /etc/portage/binrepos.conf/gentoo.conf: https://distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64, verify-signature = true - confirms Gentoo binary packages are usable and signed, which the package policy relies on
  • /etc/portage/package.license/package.license: */* @BINARY-REDISTRIBUTABLE
  • Kernel package sys-kernel/gentoo-kernel with experimental USE flag in the live image; sys-fs/lvm2 thin
  • No Portage tree is present (/var/db/repos exists but is empty)

Consequence: the installer must sync Portage and/or fetch a stage3 itself; it cannot rely on a pre-populated tree in the live image.

Goop / prior installer scripts

The reference image contains no Gentoo installer script that overlaps with what we are building (only unrelated *installer binaries from KDE/rust). There was nothing to reuse or avoid duplicating in-tree.

OpenCode

OpenCode is not present in the live image. It is downloaded by the installer from a pinned GitHub release (anomalyco/opencode, currently v1.18.31) and verified by SHA-256 against config/opencode.manifest before use. The vendor curl | sh installer is deliberately not used. (During development OpenCode v1.18.31 was fetched and hashed; the live image provides no Node.js, so the standalone opencode-linux-x64.tar.gz binary is used.)

Design decisions driven by these findings

  1. Bash + dialog, not a heavier stack: both are present in the live image and dialog gives a clean Void-style TUI with no extra dependencies.
  2. No jq: all JSON-ish parsing (AI proposals) is implemented in pure bash.
  3. systemd target: services are enabled inside the target chroot, not in the live environment.
  4. Binhost enabled by default: Gentoo signed binary packages are already configured in the reference, so the balanced package policy can use them.
  5. Installer fetches its own stage3: the live image has no Portage tree.
  6. systemd-boot + UKI are target-side operations (bootctl, kernel-install), performed after the stage3 is installed.