veilor-os/docs/INSTALL-V07.md

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. 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):

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:

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.

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

# 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
• 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 for the recipe walk-through.