237968bfac
The 'securecore-kinoite-hardened-userns' image we'd been targeting does not exist in the secureblue org's package list. Their KDE Plasma (Kinoite) hardened variant is published as 'kinoite-main-hardened' (or 'kinoite-nvidia-hardened' for NV boxes). Switch the recipe + all doc references.
138 lines
4.7 KiB
Markdown
138 lines
4.7 KiB
Markdown
# 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/kinoite-main-hardened`
|
|
- 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.
|