diff --git a/CHANGELOG.md b/CHANGELOG.md index b0572fc..ebfade6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,18 @@ future maintainers can see why a change exists, not just what it changes. ## [Unreleased] +### v0.7 BlueBuild OCI spike (active) + +- Promote `v0.7-bluebuild-spike` to active mainline; v0.6 cancelled. +- Port `build-bluebuild.yml` to the Forgejo runner (`runs-on: nullstone`): + install BlueBuild CLI in-job, push to `git.s8n.ru/veilor-org/veilor-os`, + gate cosign keyless / SBOM / attest steps to GitHub-only. +- Atomic CLI tools: `veilor-update` rewritten on `bootc upgrade`, + new `veilor-postinstall` first-login TUI, `veilor-doctor` learns + `bootc status --json` while keeping the legacy dnf path. +- Docs: `docs/INSTALL-V07.md`, `docs/STRATEGY.md` PIVOT EXECUTION + section, README quick-install rewritten for v0.7. + ### Planned - v0.3 polish — Plymouth black theme, SDDM theme, Konsole profile, diff --git a/README.md b/README.md index 7e01b91..0c422fd 100644 --- a/README.md +++ b/README.md @@ -48,26 +48,46 @@ spike at v0.7**, **bootc-only at v1.0**. --- -## Quick install +## Quick install — v0.7+ (recommended, atomic / OCI) ```bash -# 1. Download the ISO from the latest Forgejo release. +# 1. Download the bootstrap installer ISO from Forgejo. # https://git.s8n.ru/veilor-org/veilor-os/releases/tag/ci-latest -# (rolling tag; replaced on each successful build-iso.yml run) sha256sum -c veilor-os-43-*.iso.sha256 -# 2. Flash to USB. Replace /dev/sdX with your USB device — triple-check. +# 2. Flash to USB. Replace /dev/sdX — triple-check. sudo dd if=veilor-os-43-*.iso of=/dev/sdX bs=4M status=progress conv=fsync sync -# 3. Boot from USB, pick "Install veilor-os" from the menu. -# 4. Set a strong LUKS passphrase — the only prompt during install. -# 5. Reboot, remove USB. -# 6. On first boot: TTY prompts for an admin password (≥14 chars, mixed case, -# digit, symbol). Once accepted, SDDM starts. Log in as `admin`. +# 3. Boot from USB. Anaconda asks for LUKS passphrase + admin password. +# Anaconda then runs `ostreecontainer --url=git.s8n.ru/veilor-org/veilor-os:43` +# which populates / from the signed BlueBuild OCI image. + +# 4. Reboot. Log in as `admin`. The first-login TUI (veilor-postinstall) +# asks for the small set of decisions we defer from install: +# keyboard, locale, hostname, GPU drivers, package presets, +# bluetooth, USBGuard policy snapshot. Each step skippable. + +# 5. Day-to-day: `sudo veilor-update` (atomic, A/B, instant rollback). ``` -Full install + first-boot walkthrough: [docs/INSTALL.md](docs/INSTALL.md). +Full v0.7 walkthrough: [docs/INSTALL-V07.md](docs/INSTALL-V07.md). + +--- + +### Legacy v0.5.0 install (kickstart-flat path) + +The kickstart-installed v0.5.0 ISO ships as a frozen proof-of-work +release. Same hardening, no bootc/rpm-ostree atomic layer. Updates +go through `dnf upgrade` instead of `bootc upgrade`. + +```bash +# Same flash + boot, then pick "Install veilor-os". +# Single LUKS passphrase prompt during install; admin password set +# on first boot via TTY. +``` + +Walkthrough: [docs/INSTALL.md](docs/INSTALL.md). --- diff --git a/docs/INSTALL-V07.md b/docs/INSTALL-V07.md new file mode 100644 index 0000000..fd0808e --- /dev/null +++ b/docs/INSTALL-V07.md @@ -0,0 +1,138 @@ +# Installing veilor-os (v0.7+) + +> v0.7 is the first OCI / atomic release. The kickstart-installed +> v0.5.x path still ships as legacy — if you want that flow, see +> [INSTALL.md](INSTALL.md). Both paths produce a hardened veilor-os +> system; the v0.7 path is what we recommend going forward. + +## What's different from v0.5 + +| Topic | v0.5.x (kickstart) | v0.7+ (BlueBuild OCI) | +|---|---|---| +| Root filesystem | mutable, `/usr` writable | atomic / immutable, layered via `rpm-ostree` | +| Updates | `sudo dnf upgrade` | `sudo bootc upgrade` (atomic A/B, instant rollback) | +| Adding a package | `sudo dnf install foo` | `sudo rpm-ostree install foo` (layered into next deployment) | +| Base hardening | re-derived in our `%post` scripts | inherited from secureblue OCI image | +| Build artefact | `~2.7 GB` live ISO | small bootstrap ISO + signed OCI image at registry | + +## Step-by-step + +### 1. Download the bootstrap installer ISO + +The bootstrap ISO is a tiny Anaconda-driven installer. It does +nothing more than collect a LUKS passphrase + admin password and +then call `ostreecontainer --url=...:43 --transport=registry` to +populate `/` from the pre-built signed OCI image. + +Download from the Forgejo release: + + + +Reassemble the chunked ISO if needed (legacy artefact format): + +```sh +cat veilor-os-*.iso.part-* > veilor-os.iso +sha256sum -c veilor-os-*.iso.parts.sha256 +``` + +### 2. Verify the OCI image signature (optional, recommended) + +The OCI image is cosign-signed at build time. If you have `cosign` +installed: + +```sh +cosign verify --key cosign.pub git.s8n.ru/veilor-org/veilor-os:43 +``` + +The public key `cosign.pub` ships with the bootstrap ISO and is also +on the Forgejo release page. + +### 3. Flash to USB + +Replace `/dev/sdX` with your USB device — triple-check the path. + +```sh +sudo dd if=veilor-os.iso of=/dev/sdX bs=4M status=progress conv=fsync +sync +``` + +### 4. Boot from USB + +Pick **Install veilor-os** from the boot menu. Anaconda starts and +asks two things, no more: + +- **LUKS passphrase** for the encrypted root +- **admin password** (≥14 chars, mixed case, digit, symbol) + +Anaconda then runs the `ostreecontainer` directive — pulls the +signed OCI image, writes it to disk, configures bootloader. + +### 5. Reboot, remove USB + +The first boot lands on SDDM with `admin` pre-filled. Log in. + +### 6. First-login TUI + +`veilor-postinstall` runs once, asks for the small set of things we +defer from install time: + +- Keyboard / locale (defaults are fine for most operators) +- Hostname (default `veilor`) +- GPU drivers (NVIDIA layered via `rpm-ostree install`; mesa = no-op) +- Package presets (`dev` / `media` / `homelab`, all opt-in) +- Bluetooth (opt-in) +- USBGuard snapshot (plug in trusted devices first) +- `veilor-doctor` first run + +Each step is skippable. The TUI writes a marker file and disables +itself; it never runs again. + +If you need to re-run it: `sudo veilor-postinstall --force`. + +### 7. Day-to-day + +```sh +# update (atomic, A/B, instant rollback) +sudo veilor-update + +# layer a package (takes effect after reboot) +sudo rpm-ostree install foo + +# remove a layered package +sudo rpm-ostree uninstall foo + +# health check + drift report +veilor-doctor + +# rollback to previous deployment +sudo bootc rollback + +# inspect current and staged deployments +bootc status +``` + +### Troubleshooting + +| Symptom | Try | +|---|---| +| `veilor-update` says "no rollback target" | First boot — bootc only has rollback after the first successful upgrade. Normal. | +| Network down inside Anaconda | Bootstrap ISO uses NetworkManager defaults; plug in ethernet for the first install. WiFi support post-first-boot. | +| `rpm-ostree install foo` fails | Run `bootc status` — if a staged deployment exists, reboot first, then re-try. rpm-ostree won't layer onto a staged tree. | +| First-login TUI didn't appear | Marker check: `ls /var/lib/veilor/postinstall-complete`. If present, run `sudo veilor-postinstall --force`. | +| GPU is black after NVIDIA layer + reboot | `bootc rollback` and try mesa first; check `journalctl -b -1 -u sddm` from the previous boot. | + +### Where the OCI image comes from + +The image is built by `.github/workflows/build-bluebuild.yml` on the +self-hosted Forgejo runner (label `nullstone`). Build inputs: + +- Base: `ghcr.io/secureblue/securecore-kinoite-hardened-userns` +- Recipe: [`bluebuild/recipe.yml`](../bluebuild/recipe.yml) +- Veilor overlay: stamped via BlueBuild `type: files` modules +- Layered RPMs: `sudo`, `xorg-x11-server-Xwayland`, `mullvad-browser`, + `tailscale`, `yggdrasil` +- Output: `git.s8n.ru/veilor-org/veilor-os:{43,latest}` + +The build is cosign-signed (key-pair on Forgejo, keyless on GitHub +parallel mirror). See [`bluebuild/README.md`](../bluebuild/README.md) +for the recipe walk-through. diff --git a/docs/STRATEGY.md b/docs/STRATEGY.md index 7a732a1..76dd724 100644 --- a/docs/STRATEGY.md +++ b/docs/STRATEGY.md @@ -334,3 +334,29 @@ dir. - Yggdrasil: - Reticulum manual: - Iroh blobs design: + +--- + +## PIVOT EXECUTION — 2026-05-06 + +The hybrid strategy locked at v0.5 is now in execution. + +- **v0.5.0 shipped** as the proof-of-work / portfolio release of the + kickstart-flat path. Self-hosted Forgejo CI green-built a 2.7 GB + ISO; tag pushed; download lives at the ci-latest release. +- **v0.6 milestone cancelled.** Continuing to debug + `livecd-creator + anaconda` quirks for v0.6 polish would be sunk- + cost work on tooling we retire at v1.0. Original v0.6 plan kept in + ROADMAP.md as historical reference. +- **v0.7 BlueBuild OCI is the active mainline.** The + `v0.7-bluebuild-spike` branch carries the BlueBuild recipe layered + on `ghcr.io/secureblue/securecore-kinoite-hardened-userns`, the + `ostreecontainer` kickstart bootstrap, and the new `bootc upgrade`- + driven update channel. +- **v0.6 ergonomic CLIs ported, not rewritten.** `veilor-update` + rewrites onto `bootc upgrade`; `veilor-postinstall` becomes the + first-login TUI on the atomic system; `veilor-doctor` learns + `bootc status --json` while keeping the legacy dnf path for v0.5.x. +- **v1.0 retires the kickstart entirely.** Only `kickstart/install- + ostreecontainer.ks` (10 lines) ships forward — bootstrap installer + for ostreecontainer pulls.