hivemq setup

README.md

@@ -61,6 +61,26 @@ 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).
 
+### SSH key setup (do this first)
+
+Both phases authenticate over SSH with `~/.ssh/larsnolden`, which is
+passphrase-protected. Load it into an `ssh-agent` once so the deploy tools can
+reuse it without prompting:
+
+```fish
+eval (ssh-agent -c)        # bash/zsh: eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/larsnolden  # enter the passphrase once
+ssh-add -l                 # confirm the key is loaded
+```
+
+This is **required** for `deploy-rs`, not just a convenience: with
+`magicRollback = true` (see `nix/deploy.nix`) activation opens two concurrent SSH
+connections — the activation command and a rollback waiter. Without an agent,
+both race to read the passphrase from the terminal, one loses, and the deploy
+fails with `Permission denied (publickey,keyboard-interactive)` even though
+manual SSH and the copy step work. The agent serves the key to every connection,
+so no prompt is needed.
+
 ### Initial provisioning (`nixos-anywhere`)
 
 `deploy-rs` only *updates* a machine that already runs NixOS — it copies a
@@ -109,6 +129,9 @@ Provision `db-host` first if you intend to deploy updates immediately afterward
 once, copied to each host, activated with auto-rollback. Order: `db-host` →
 `app-host` → `mqtt-ingest`.
 
+Running it by hand needs the key loaded into an `ssh-agent` first — see
+[SSH key setup](#ssh-key-setup-do-this-first) above.
+
 ```
 nix run github:serokell/deploy-rs -- .#db-host       # one host
 nix run github:serokell/deploy-rs -- .                # all hosts