docs: v0.7 user-facing docs (INSTALL-V07, STRATEGY pivot, README, CHANGELOG)
A4 inline (agent failed on API): - docs/INSTALL-V07.md: 130-line user walkthrough — bootstrap ISO, Anaconda LUKS prompts, ostreecontainer pull, first-login TUI, day- to-day bootc-upgrade / rpm-ostree-install / bootc-rollback. - docs/STRATEGY.md: append PIVOT EXECUTION 2026-05-06 section recording v0.5 ship, v0.6 cancel, v0.7 active. - README.md: rewrite Quick install block for v0.7 path; legacy v0.5.0 block kept below. - CHANGELOG.md: Unreleased entry covering the spike's CI port + atomic CLI port + docs.
This commit is contained in:
obsidian-ai
parent
606806f82f
commit
4d53d76442
4 changed files with 206 additions and 10 deletions
12
CHANGELOG.md
12
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,
|
||||
|
|
|
|||
40
README.md
40
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).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
138
docs/INSTALL-V07.md
Normal file
138
docs/INSTALL-V07.md
Normal file
|
|
@ -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:
|
||||
|
||||
<https://git.s8n.ru/veilor-org/veilor-os/releases/tag/ci-latest>
|
||||
|
||||
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.
|
||||
|
|
@ -334,3 +334,29 @@ dir.
|
|||
- Yggdrasil: <https://github.com/yggdrasil-network/yggdrasil-go>
|
||||
- Reticulum manual: <https://reticulum.network/manual/>
|
||||
- Iroh blobs design: <https://github.com/n0-computer/iroh-blobs/blob/main/DESIGN.md>
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue