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

docs: STRATEGY.md — hybrid kickstart bootstrap + bootc OCI on secureblue

Browse source 
Locks in the strategic decision from 2026-05-05 secureblue research
agent: pivot the technical base toward bootc/OCI, but as a layer over
secureblue's `securecore-kinoite-hardened-userns` rather than a
Containerfile-from-scratch.

## What changed

- New: `docs/STRATEGY.md` — full hybrid plan (kickstart bootstrap →
  first-boot bootc rebase → bootc-only at v1.0). Documents secureblue
  rationale, our overrides (drop Trivalent, restore sudo + Xwayland),
  next concrete steps for v0.7 spike (BlueBuild recipe + GH Actions
  workflow + `veilor-firstboot-rebase` one-shot).

- Updated: `docs/ROADMAP.md` v0.7 bootc-spike subsection — supersedes
  the Agent 3 Containerfile-from-scratch plan with the BlueBuild
  layering plan. Spike compresses 1 week → 2 days; hardening review
  inherited from 30 secureblue contributors.

## Why hybrid, not pure pivot

- Anaconda's LUKS UX (single passphrase prompt + custom
  partitioning) is mature; bootc-image-builder's installer is not yet
  on par. Keep the kickstart as the bootstrap.
- bootc upgrade gets us atomic A/B + signed image chain + instant
  rollback that we can't realistically build alone with our
  contributor count.
- The kickstart work is not lost — it becomes the day-zero installer
  through v0.7. v1.0 deprecates it entirely once bootc-image-builder
  installer ISO matures.

## Why secureblue, not Athena (Arch)

| Axis | secureblue | Athena OS |
|---|---|---|
| Maintainers | 30 | 8 |
| MAC enforcing OOB | SELinux + custom policy | AppArmor active, profiles mostly unconfined |
| Atomic / immutable updates | Yes (bootc/rpm-ostree) | No (rolling) |
| Threat model published | No | Yes |
| MS-signed Secure Boot shim | Yes (Fedora shim) | Yes (with auto-MOK) |

Athena's only structural advantage is the published threat model.
We're already drafting one (Agent 5 of 2026-05-05 wave) — we get
that win regardless. secureblue's contributor count + atomic update
infrastructure is the leverage.

## Strategic credibility win

Publishing `docs/THREAT-MODEL.md` BEFORE the v0.7 launch positions
veilor-os ahead of secureblue (no threat model) and Athena (has
threat model but smaller contributor base) on the one axis that
matters most.

## Open questions documented in STRATEGY.md

- secureblue contribution acceptance for upstream patches (USBGuard
  id-based-rules fix, threat model framework)
- Brave vs Mullvad-Browser pick for default browser
- bootc rebase first-boot fallback if rebase fails
- Fedora 44 transition timing follows secureblue's release tags
This commit is contained in:
veilor-org 2026-05-05 15:05:59 +01:00
parent 4e9782a18a
commit 50a241a603
2 changed files with 174 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
docs/ROADMAP.md
View file

@ -223,17 +223,44 @@ public, benchmarks come after.
After threat model, not before.
5. **Press kit** — wallpapers, logo, screenshots, feature one-liner.
### bootc-image-builder spike (PROMOTED from v1.0+)
### Hybrid bootc spike — layer on secureblue (REVISED 2026-05-05)
The v0.5.27–31 grind cost us hours on anaconda + RPM-6.0 +
`--cmdline` mode brittleness: three install failures, kernel-cmdline
written to four different places before one worked, transaction-progress
patches that masked real bugs. **bootc-image-builder builds a
`Containerfile` once and gets a bootable image** — no anaconda, no
kickstart, no `%post --nochroot` vs `%post`, no
`CollectKernelArgumentsTask`. A v0.7 spike (NOT v1.0) evaluates whether
the next major rev should rebase on it. Spike outcome determines
whether `veilor-atomic` (stretch goal) becomes the mainline.
The original v0.7 entry called for a Containerfile-from-scratch
spike on `quay.io/fedora/fedora-bootc:43`. Research on 2026-05-05
(see `docs/STRATEGY.md` and
`docs/research/2026-05-05-agent-wave/`) found a faster path:
**layer veilor's branding + threat model + UX on top of
secureblue's already-shipping `securecore-kinoite-hardened-userns`
OCI image** via a BlueBuild recipe.
Reasoning:
- secureblue has 30 active contributors, 940 stars, 56 commits
in the last 5 weeks. They've already implemented the hardening
surface we'd need to build alone (sysctl + kargs + SELinux
custom policy + USBGuard + hardened-malloc + Unbound DoT +
cosign-signed OCI build pipeline).
- Containerfile-from-scratch spike: 1 week to first ISO.
BlueBuild recipe extending secureblue: ~2 days, ~200 lines
YAML. The hardening review is inherited.
- secureblue does NOT publish a threat model. Athena OS does
(their main differentiator, only public threat model in
hardened-Linux 2026). Our `docs/THREAT-MODEL.md` (drafted) gets
us ahead of both on the one axis that matters most for a
security-branded distro.
Hybrid path locked: kickstart ISO stays as the **bootstrap
installer** (Anaconda's LUKS UX is mature). On first boot, a
one-shot `veilor-firstboot-rebase` service runs `bootc rebase
ghcr.io/veilor/veilor-os:43`. From then on, `bootc upgrade` is
the update channel. v1.0 deprecates the kickstart entirely.
Overrides we apply over secureblue: replace Trivalent (their
single-maintainer browser fork) with Brave or Mullvad-Browser;
keep sudo (revert `run0`-only); re-enable Xwayland.
Full plan: `docs/STRATEGY.md`. Spike will land in
`bluebuild/recipe.yml` plus `.github/workflows/build-bluebuild.yml`.
---

137
docs/STRATEGY.md Normal file
View file

@ -0,0 +1,137 @@
# veilor-os Strategy — Hybrid kickstart bootstrap + bootc OCI
Decision date: **2026-05-05**
Locked at: **v0.5.31 → v0.7 spike → v1.0**
## TL;DR
- Keep the Anaconda-driven kickstart ISO as the **bootstrap installer**
(LUKS UX is mature, single passphrase prompt, custom partitioning
works).
- On first boot, the installed system is automatically rebased to a
**veilor-os OCI image** built via BlueBuild on top of secureblue's
`securecore-kinoite-hardened-userns`.
- All future updates flow through `bootc upgrade` — atomic A/B,
instant rollback, cosign-signed.
- The kickstart-driven mutable-root path is deprecated at v1.0; kept
alive as fallback through v0.7.
## Why hybrid, not pure pivot
Pure pivot to bootc-from-scratch (Agent 3's spike plan) was **1 week
to first ISO**. Pure pivot to layering on secureblue is **2 days to
first ISO** because the hardening work is already done. But both
require throwing away the partitioning UX we already have working in
Anaconda.
Hybrid:
- **Day-zero install:** Anaconda kickstart + custom partitioning +
LUKS prompt (what we have today). User experience = unchanged.
- **First boot, post-LUKS-unlock:** `bootc rebase
ghcr.io/veilor/veilor-os:43` runs once; pulls the OCI image; next
reboot lands in the veilor OCI tree.
- **Day-2:** `bootc upgrade` cadence for everything from then on.
We keep what works, pivot the part that doesn't.
## Why secureblue underneath
| Question | Answer |
|---|---|
| Maintainers | secureblue: 30 contributors, 56 commits/5wks. veilor-os: solo. |
| Hardening surface | secureblue ships sysctl + kargs + SELinux + USBGuard + hardened-malloc + DoT — far more than we'd build alone. |
| Build pipeline | BlueBuild → cosign-signed OCI in GH Actions (`build-all.yml`, `trivy.yml`). |
| Update model | bootc upgrade with A/B + instant rollback + signed image chain. |
| Variants | `kinoite-hardened-userns` is the KDE+Wayland+SELinux variant we'd want. |
| License | Apache-2.0 (compatible with our MIT). |
What we override in our recipe:
- **Browser**: Trivalent (their fork) → Brave / Mullvad-Browser.
Single-maintainer browser fork is unacceptable risk for daily-driver
audience.
- **`run0` instead of sudo**: revert. Breaks too many workflows.
- **Xwayland disabled**: revert. Some apps still need it.
- **veilor branding**: theme, KDE color scheme, Plymouth, SDDM, font,
os-release. All `overlay/*` ports verbatim from current repo.
## Strategic credibility win
secureblue does NOT publish a threat model. Athena OS does, and it's
their main differentiator. We've already drafted
`docs/THREAT-MODEL.md` (Agent 5 of 2026-05-05 wave). Publishing that
*before* the v0.7 launch positions veilor-os ahead of secureblue and
Athena on the one axis that matters most for a security-branded
distro: **honest, scoped, public threat model**.
## Roadmap implications
| Version | Status | Path |
|---|---|---|
| v0.5.31 | shipped | Anaconda kickstart, mutable root |
| v0.5.32 | active — top blockers from 9-agent wave | Anaconda kickstart |
| v0.5.x → v0.6 | maintenance | Anaconda kickstart, ergonomics + UX polish |
| **v0.7 spike** | **2-day BlueBuild prototype** | First veilor OCI image extending secureblue-kinoite-hardened |
| v0.7 ship | ISO bootstraps install, first boot rebases to OCI | Hybrid path live |
| **v1.0** | **bootc-only**, kickstart deprecated | `bootc upgrade` for all updates |
The `bootc-image-builder` spike plan (Agent 3) is **superseded** by
this hybrid: don't build a Containerfile from scratch on
`fedora-bootc:43`. Instead, write a BlueBuild recipe on
`securecore-kinoite-hardened-userns`. Spike compresses 1 week → 2 days.
## Next concrete steps
### v0.5.32 — current (no strategy change)
Ship the 7 blockers from `docs/research/2026-05-05-agent-wave/`:
suspend/resume wifi fix, firstboot WantedBy, USBGuard id-rules,
firewalld tailscale0 zone, KMS modeset, /etc/skel branding, virtio-9p
log capture.
### v0.7-spike (2 days)
1. New repo dir: `bluebuild/recipe.yml`.
2. `from`: `ghcr.io/secureblue/securecore-kinoite-hardened-userns:latest`.
3. Override modules:
- `type: files` — stamp our `overlay/*` tree (branding, themes,
veilor scripts, sddm theme, plymouth theme).
- `type: rpm-ostree` — install Brave + restore Xwayland.
- `type: rpm-ostree` — remove Trivalent.
- `type: brand` — PRETTY_NAME, GRUB_DISTRIBUTOR, distributor URL.
4. `.github/workflows/build-bluebuild.yml` — pull BlueBuild action,
build + cosign sign + push to GHCR.
5. `kickstart/install.ks` — add a one-shot `veilor-firstboot-rebase`
service that runs `rpm-ostree rebase ghcr.io/veilor/veilor-os:43`
then disables itself. User reboots once and is on the OCI image.
### v1.0 — bootc-only
- Drop `kickstart/veilor-os.ks`, drop `livecd-creator` workflow.
- Keep `installer-iso.toml` for the bootstrap ISO (built via
bootc-image-builder); the OCI image is the source of truth.
- `veilor-update` becomes thin `bootc upgrade --apply` wrapper.
## Open questions
- Does secureblue accept upstream contributions? If yes, send our
USBGuard id-based-rules fix and our threat model framework.
- Brave vs Mullvad-Browser: Brave has telemetry concerns out of box;
Mullvad-Browser is Tor-Browser-derived but not designed for
daily-driver. Test both in spike.
- Recovery flow when bootc rebase fails on first boot — need fallback
to keep the kickstart-installed system bootable. Likely already
handled by bootc's A/B; verify in spike.
- Fedora 44 transition: secureblue tracks Fedora releases (current
`v4.9` on F44). If we follow, we get F44 for free at the same time
upstream does.
## See also
- `docs/THREAT-MODEL.md` — drafted, needs publish for v0.7
- `docs/ROADMAP.md` — to be updated to reflect this strategy
- `docs/research/2026-05-05-agent-wave/03-bootc-spike-plan.md` —
superseded by this hybrid (kept as reference for the
Containerfile-from-scratch alternative)
- secureblue: <https://github.com/secureblue/secureblue>
- BlueBuild: <https://blue-build.org>