# 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.