phoebus_os/installer/README.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

124 lines
4.5 KiB
Bash

# Phoebus OS installer
A deterministic, text-mode installer for Phoebus OS, inspired by
`void-installer`. It is usable entirely without an LLM; AI only augments it.
## Goals
- Simple keyboard-driven TUI.
- Logical, revisitable configuration stages.
- A complete installation plan and explicit confirmation before anything
destructive happens.
- Logs for every backend operation.
- No magical hidden disk modifications.
## Two layers
```
tui/ front-end: menus, dialogs, screens
menu.sh main loop, review and install flow
screens.sh one function per configuration stage
ui.sh dialog/whiptail abstraction
lib/ deterministic backend (usable without the TUI)
state.sh structured configuration state
logging.sh logging + run_cmd + dry-run
confirm.sh destructive-operation authorization gates
hardware.sh read-only hardware probing
disks.sh read-only disk discovery and protection rules
partitions.sh GPT partitioning
filesystem.sh mkfs, mount, fstab/crypttab generation
encryption.sh LUKS2
btrfs.sh subvolume layout
network.sh live networking + target hostname
portage.sh Portage configuration and stage3
pkgpolicy.sh compile-vs-binary policy
kernel.sh kernel profile and installation
boot.sh systemd-boot (BLS entries) + dracut initramfs
users.sh accounts, passwords, sudo
desktop.sh desktop profiles
ai.sh assistant and structured proposals
opencode.sh pinned, checksum-verified OpenCode
plan.sh installation plan generation
validation.sh configuration validation
install.sh staged orchestration
config/
defaults.conf all defaults
opencode.manifest pinned OpenCode release + SHA-256
tests/ unit tests, no root or disks required
```
## Running in a Gentoo Live environment
The LiveGUI reference (or any Gentoo live medium with `dialog`, Portage and the
disk tools listed in `doc/FINDINGS.md`) can run the installer directly:
```sh
sudo /path/to/installer/bin/ai-installer
```
Useful non-interactive modes (the backend works without the TUI):
```sh
# Print the generated installation plan and validate the configuration
ai-installer --plan
# Load a saved configuration
ai-installer --config /root/phoebus-install.conf
# Dry run: every command is logged, nothing is executed
ai-installer --dry-run
# Run the backend without a TUI (still requires explicit ERASE confirmation)
ai-installer --config /root/phoebus-install.conf --install
# Fetch and verify the pinned OpenCode release
ai-installer --bootstrap-opencode
```
### Typical flow
1. Network (connect Wi-Fi if needed).
2. Keyboard, hostname, locale, timezone, user.
3. Disk: pick a target (protected devices are never offered).
4. Filesystem / encryption: LUKS2 is the default; set a passphrase.
5. Boot / kernel / packages / desktop as desired.
6. Review configuration -> inspect the plan.
7. Install -> read the destructive summary, type `ERASE`, confirm again.
## Safety model
- Detection never modifies a disk.
- The target disk must be explicitly selected from candidates.
- Disks that are mounted, read-only, optical/loop, or back the live medium are
marked **PROTECTED** and cannot be selected.
- All destructive commands go through `run_destructive`, which refuses to run
unless `PHOEBUS_DESTRUCTIVE_AUTHORIZED=yes`. Only `install.sh` grants this,
only after the plan is approved.
- Whole-disk erase additionally requires typing `ERASE`.
- Dry-run mode redirects all file writes to a temporary sandbox and runs no
commands.
- Passwords, passphrases and API keys are never written to the config or logs.
## Package policy
`lib/pkgpolicy.sh` implements the rule "compile when cheap or beneficial, use a
binary when expensive and the benefit is negligible". It is deterministic and
uses a curated table plus optional historical compile times
(`$STATE_DIR/compile-times.tsv`). No model is consulted to guess performance.
## AI policy
- The normal install path is fully deterministic and LLM-free.
- The AI assistant explains hardware, disks, filesystems, kernel and package
choices, and can translate a natural-language request into a **structured
proposal** (flat JSON with a fixed key whitelist).
- Every proposed field is validated by `lib/validation.sh`. The LLM never
receives secrets, never touches a disk and never runs a command.
- Proposal flow: request -> proposal -> validation -> preview -> confirmation ->
backend.
See `doc/FINDINGS.md` for environment findings and `doc/TESTING.md` for safe
testing instructions.