Initial import of verae-ops from zapier monorepo

05-dedicated-hardware.md

@@ -0,0 +1,59 @@
+# 5. Dedicated hardware
+
+NS1-style: a box that already runs NATS on **127.0.0.1:4222** (never a public bind), plus optional extra hosts for SSH workers.
+
+## This host (control + edges)
+
+1. Node 22+, git (SSH port **2223** to Forgejo).
+2. `nats-server -js` listening **127.0.0.1:4222** only (cluster later on a private NIC).
+3. Clone `zappier-edge`, `verae-middleware`, `verae-fleet`.
+4. systemd units (below) or `verae-fleet serve` which keepFloor-spawns workers.
+5. Caddy/nginx for public HTTPS to `:3000` / `:3100`.
+6. Operator console: `127.0.0.1:3850` — SSH tunnel if you are off-box:
+   `ssh -L 3850:127.0.0.1:3850 -L 4222:127.0.0.1:4222 user@ns1`
+
+## systemd (middleware)
+
+```
+[Unit]
+Description=verae-middleware
+After=network.target nats.service
+
+[Service]
+WorkingDirectory=/opt/verae/verae-middleware
+Environment=PORT=3100
+Environment=NATS_ENABLED=true
+Environment=NATS_URL=nats://127.0.0.1:4222
+Environment=VERAE_API_BASE_URL=https://api.veraetime.net
+ExecStart=/usr/bin/node src/index.js
+Restart=on-failure
+User=verae
+
+[Install]
+WantedBy=multi-user.target
+```
+
+zappier-edge similar with `PORT=3000` and `WorkingDirectory` of that clone.
+
+## Extra machines
+
+Add to fleet `machines.json`:
+
+```json
+{
+  "id": "ns1",
+  "kind": "ssh",
+  "user": "marchon",
+  "host": "70.88.205.138",
+  "port": 22,
+  "identityFile": "~/.ssh/id_ed25519",
+  "capacity": 8,
+  "roles": ["tree-node", "archive-worm"]
+}
+```
+
+Never commit private key bytes. Optional `machines.secrets.json` is gitignored.
+
+## NATS 3-server cluster on metal
+
+Three boxes, private IPs, same `cluster_name`, routes to each other, `listen` on the private IP only. Clients (`NATS_URL`) list all three URLs. Target architecture: https://zapier.georgelambert.org/overview/03-nats-cluster.pdf