# scripts/prereqs/ -- workstation/workspace prerequisite installers

New operators start here. These scripts get a Debian/Ubuntu workstation (or the
vcloud host / Office1 control point) ready to run the VR1 DC-DC workflow, so a
runbook never assumes a runtime is already present (DOCFIX-178). Each installer
is **idempotent** (a satisfied prereq is a no-op) and supports `--check`
(read-only report) and `--dry-run` (print actions, mutate nothing).

## Quick start

```bash
bash scripts/prereqs/check-prereqs.sh      # read-only: what's missing?
bash scripts/prereqs/install-all.sh --dry-run   # preview
bash scripts/prereqs/install-all.sh        # install everything missing (uses sudo)
```

Then re-login (or `newgrp libvirt`) if the virtualization installer just added
you to the `libvirt` group, and re-run `check-prereqs.sh` to confirm all green.

## What each script covers

| Script | Prereq | Needed by |
|---|---|---|
| `install-opentofu.sh` | OpenTofu `tofu` >= 1.6.0 (deb repo -> `/usr/bin/tofu`) | dc-dc Stage 1-6 `tofu` steps + `scripts/opentofu-validate.sh` |
| `install-virtualization.sh` | libvirt + qemu-kvm + virsh + `libvirt` group | dc-dc Stage 1+ (pools, networks, node VMs) |
| `install-apparmor-libvirt.sh` | AppArmor grant `<pool-parent>/** rwk,` so qemu can open disks under the **custom** VR1 pool parent (default `/var/lib/libvirt/vr1`; override `VR1_POOL_PARENT`) | **Every VR1 VM boot** -- Office1 edge, DC edges, node VMs |
| `install-jq.sh` | jq | cloud-assert + many ops scripts (and the test gauntlet) |
| `install-image-tools.sh` | qemu-utils (`qemu-img`) | Stage 2/3 OPNsense image prep (`opnsense-prep-image.sh`). The `xorriso`/ISO9660 requirement was REMOVED 2026-07-13: the config-seed ISO path is deleted (D-112 -- the Importer can never fire on a nano image; D-113(a2) -- config is done over the REST API). |
| `check-prereqs.sh` | (read-only report of all of the above + curl/python3/sudo) | run first, on any new workspace |
| `install-all.sh` | orchestrator over the five installers + a final check | one-pass setup |
| `lib-prereq.sh` | shared helpers (sourced, not run) | the installers |

## Scope + conventions

- **Debian/Ubuntu (apt) only.** On another OS each installer fails loud (exit 3)
  and tells you to install manually -- it does not guess a package manager.
  `tofu` and the ISO builder have portable upstream options; see each script.
- **`sudo`** is used only for the actual package install / group change / profile
  edit. The `--check` and `--dry-run` modes never touch the system, never call
  sudo, and never reload a service.
- **The AppArmor one is the trap, not a formality.** libvirt's stock
  `abstractions/libvirt-qemu` only grants qemu the DEFAULT pool path
  (`/var/lib/libvirt/images`). VR1 uses a custom pool parent, so AppArmor blocks
  qemu even with perfect POSIX permissions -- the domain DEFINES, then fails to
  start with a bare "Permission denied" that never mentions AppArmor. It cost a
  session on 2026-07-12. `install-apparmor-libvirt.sh` reloads apparmor and
  restarts libvirtd ONLY on the run that actually adds the rule, never on an
  already-good host.
- **`tofu`, not `opentofu`.** The OpenTofu installer uses the deb method on
  purpose: every runbook step and `scripts/opentofu-validate.sh` call the `tofu`
  command, which the `opentofu` snap may not expose.
- Run via `bash scripts/prereqs/<name>.sh` (these are not marked executable, per
  this repo's convention). Harness: `tests/prereqs/run-tests.sh`.
