phoebus_os/installer/doc/FINDINGS.md
Phoebus 38214ea9e7 chore: import Phoebus OS installer and Rust migration
Initial public import of the proven Bash installer (installer/) and the production Rust workspace (installer-rs/). The reference ISO, build output and local agent transcripts are gitignored.

Verified: installer/tests/run_tests.sh and cargo test --workspace both pass.
2026-09-20 02:07:33 -07:00

103 lines
4.8 KiB
Markdown

# 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.