Add nixos-anywhere deploy instructions to README

README.md

@@ -57,6 +57,54 @@ Supabase compose, Kong, Caddy, ingester, Vite dev server). NixOS required.
 
 ## Deployment
 
+There are two distinct phases. **Initial provisioning** turns a blank box into a
+NixOS host (`nixos-anywhere`, run once per machine). **Updates** push new
+closures to a host that already runs NixOS (`deploy-rs`, run on every change).
+
+### Initial provisioning (`nixos-anywhere`)
+
+`deploy-rs` only *updates* a machine that already runs NixOS — it copies a
+prebuilt closure and activates it. A fresh box (e.g. a stock Debian image with
+only a `root` user) has no Nix store and no NixOS generation to switch to, so
+`deploy-rs` fails with `nix-store: command not found`. Use
+[`nixos-anywhere`](https://github.com/nix-community/nixos-anywhere) to install
+NixOS over SSH first; after that, `deploy-rs` takes over for all subsequent
+deploys.
+
+`nixos-anywhere` SSHes in as `root`, kexecs into an in-memory NixOS installer,
+partitions and formats the disk per the host's [`disko`](https://github.com/nix-community/disko)
+config, installs `nixosConfigurations.<host>`, and reboots into NixOS. **This
+wipes the target disk.**
+
+Prerequisites, per host, before running it:
+
+1. **A real disk layout.** Hosts currently import the fictional
+   `nix/hosts/placeholder-hardware.nix` (it only exists so `nix flake check`
+   evaluates). Replace that import with a `disko` config describing the actual
+   disk device (`/dev/sda` vs `/dev/vda`/nvme) and firmware (UEFI vs legacy
+   BIOS). `disko` replaces the hand-generated `hardware-configuration.nix`.
+2. **Root SSH access** to the box. The `deploy` user and its authorized keys are
+   created by `nix/hosts/common.nix` during the install, so deploy-rs access
+   works automatically once NixOS is up.
+3. **Host secrets key** present so sops-nix can decrypt at first boot — see
+   [`nix/secrets/README.md`](nix/secrets/README.md). Otherwise services that
+   read `/run/secrets/*` (e.g. the ingester) fail to start after reboot.
+
+Then, from the repo root:
+
+```
+# installs NixOS onto the target, wiping its disk
+nix run github:nix-community/nixos-anywhere -- \
+  --flake .#mqtt-ingest root@ingest.gebos.online
+```
+
+Repeat with `.#db-host root@db.gebos.online` and `.#app-host root@app.gebos.online`.
+Provision `db-host` first if you intend to deploy updates immediately afterward
+(see the ordering note below). Once a host has rebooted into NixOS, never run
+`nixos-anywhere` against it again — use `deploy-rs`.
+
+### Updates (`deploy-rs`)
+
 `deploy-rs` from a Gitea Actions runner on push to `main`. Closures are built
 once, copied to each host, activated with auto-rollback. Order: `db-host` →
 `app-host` → `mqtt-ingest`.