veilor-org/veilor-os
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

docs: v0.7 user-facing docs (INSTALL-V07, STRATEGY pivot, README, CHANGELOG)

Browse source 
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.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
claude-veilor-bot 2026-05-06 16:48:48 +01:00
parent b03dd499ad
commit 6fcdd7e04c
4 changed files with 206 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
CHANGELOG.md
View file

@ -11,6 +11,18 @@ future maintainers can see why a change exists, not just what it changes.
## [Unreleased] ## [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 ### Planned
- v0.3 polish — Plymouth black theme, SDDM theme, Konsole profile, - v0.3 polish — Plymouth black theme, SDDM theme, Konsole profile,

40
README.md
View file

@ -48,26 +48,46 @@ spike at v0.7**, **bootc-only at v1.0**.
--- ---
## Quick install ## Quick install — v0.7+ (recommended, atomic / OCI)
```bash ```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 # 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 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 sudo dd if=veilor-os-43-*.iso of=/dev/sdX bs=4M status=progress conv=fsync
sync sync
# 3. Boot from USB, pick "Install veilor-os" from the menu. # 3. Boot from USB. Anaconda asks for LUKS passphrase + admin password.
# 4. Set a strong LUKS passphrase — the only prompt during install. # Anaconda then runs `ostreecontainer --url=git.s8n.ru/veilor-org/veilor-os:43`
# 5. Reboot, remove USB. # which populates / from the signed BlueBuild OCI image.
# 6. On first boot: TTY prompts for an admin password (≥14 chars, mixed case,
# digit, symbol). Once accepted, SDDM starts. Log in as `admin`. # 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
View 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.

26
docs/STRATEGY.md
View file

@ -334,3 +334,29 @@ dir.
- Yggdrasil: <https://github.com/yggdrasil-network/yggdrasil-go> - Yggdrasil: <https://github.com/yggdrasil-network/yggdrasil-go>
- Reticulum manual: <https://reticulum.network/manual/> - Reticulum manual: <https://reticulum.network/manual/>
- Iroh blobs design: <https://github.com/n0-computer/iroh-blobs/blob/main/DESIGN.md> - 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.