flatrender/services/node-agent/deploy/README.md

FlatRender Node Agent — Deployment

This folder turns a Windows machine with After Effects into a FlatRender render node: connected to the control plane over an encrypted WireGuard mesh, running the agent as an auto-restarting Windows service.

deploy/
├── build-windows.ps1            Cross-compile the agent → dist\ (run on your dev box)
├── agent.env.example            Agent config template → copy to agent.env
├── install-service.ps1          Register the agent as a Windows service (sc.exe)
├── uninstall-service.ps1        Remove the service
├── wireguard-node.conf.template WireGuard client config → fill in → wg-flatrender.conf
└── setup-wireguard.ps1          Install + start the WireGuard tunnel as a boot service

The node only ever dials out to the control plane. It needs no public IP and no inbound firewall rules — home ADSL, CGNAT, or any datacenter all work.

---

Architecture

                 WireGuard mesh 10.66.0.0/24
   ┌─────────────────────────────┐         ┌──────────────────────────────┐
   │  Control plane  10.66.0.1   │◄───────►│  Render node  10.66.0.11     │
   │  ─ gateway :8088            │  encrypted   ─ wireguard tunnel (svc)  │
   │  ─ render-svc (orchestrator)│  tunnel  │   ─ node-agent (svc)         │
   │  ─ MinIO (templates/exports)│         │   ─ After Effects + aerender  │
   └─────────────────────────────┘         └──────────────────────────────┘

The agent: claims a job → downloads the .aep bundle from MinIO → binds user customisations (JSX) → renders with aerender.exe → uploads the MP4 → reports complete. It heartbeats every 5 s and streams live preview frames while rendering.

---

1. Control plane: one-time WireGuard server setup

On the Linux host that runs the V2 stack (gateway + MinIO):

# Install
sudo apt install -y wireguard

# Generate the server keypair
wg genkey | tee server.key | wg pubkey > server.pub

# /etc/wireguard/wg0.conf
cat >/etc/wireguard/wg0.conf <<'EOF'
[Interface]
Address = 10.66.0.1/24
ListenPort = 51820
PrivateKey = <contents of server.key>

# One [Peer] block per render node (append as you add nodes):
# [Peer]
# PublicKey = <node-1 public key>
# AllowedIPs = 10.66.0.11/32
EOF

sudo systemctl enable --now wg-quick@wg0
sudo wg show          # prints the server public key for the node config

Open UDP 51820 to the internet (the only inbound port the control plane needs for the mesh). The gateway (:8088) and MinIO stay bound to the WG interface — they are never exposed publicly.

Each time you add a node, append its [Peer] block and sudo wg syncconf wg0 <(wg-quick strip wg0).

---

2. Build the agent (on your dev machine)

# Requires Go 1.25+. Produces dist\flatrender-node-agent.exe + the deploy kit.
cd services\node-agent\deploy
.\build-windows.ps1

Copy the whole dist\ folder to each render node (e.g. C:\flatrender\).

---

3. Render node: WireGuard

# On the node, generate its keypair (WireGuard GUI → Add Tunnel → it shows the keys,
# or use the bundled wg.exe):  wg genkey | wg pubkey

1. Copy wireguard-node.conf.template → wg-flatrender.conf.
2. Fill the four placeholders:
   • NODE_PRIVATE_KEY — this node's private key
   • NODE_NUMBER — unique mesh octet (11, 12, 13, …) → Address = 10.66.0.11/32
   • SERVER_PUBLIC_KEY — from wg show on the control plane
   • SERVER_PUBLIC_ENDPOINT — the control plane's public IP/host
3. Add this node's public key + AllowedIPs = 10.66.0.11/32 as a [Peer] on the server (step 1).
4. Install the tunnel (elevated PowerShell):

.\setup-wireguard.ps1 -ConfigPath .\wg-flatrender.conf
ping 10.66.0.1          # should reply over the tunnel

---

4. Render node: agent service

# Configure
Copy-Item agent.env.example agent.env
notepad agent.env       # set NODE_ID, NODE_HMAC_SECRET, ORCHESTRATOR_URL=http://10.66.0.1:8088, AE_PATH

Get NODE_ID by creating the node in the admin panel (/admin/nodes → add), or via POST /v1/nodes. NODE_HMAC_SECRET must equal the render-svc value in .env.v2.

# Install + start the service (elevated)
.\install-service.ps1

# Verify
curl http://localhost:7777/health
Get-Service FlatRenderNodeAgent

The node now appears Ready in /admin/nodes and starts claiming jobs.

---

Operations

Task	Command
Health	curl http://localhost:7777/health
Service status	Get-Service FlatRenderNodeAgent
Restart	Restart-Service FlatRenderNodeAgent
Stop	Stop-Service FlatRenderNodeAgent
Update binary	Stop service → replace exe → Start service
Change config	Edit agent.env → Restart-Service FlatRenderNodeAgent
Remove	.\uninstall-service.ps1
Tunnel status	& 'C:\Program Files\WireGuard\wireguard.exe' show

The service auto-restarts on crash (3× at 5 s intervals) and auto-starts at boot. WireGuard comes up first, so the agent always has a path to the gateway.

Mock mode

Leave AE_PATH empty in agent.env to run the mock renderer — useful to smoke-test the claim → download → upload → complete pipeline on a node without an AE licence.

Troubleshooting

• Node never goes Ready: tunnel down (wireguard.exe show) or wrong ORCHESTRATOR_URL.
• 401 / signature errors: NODE_HMAC_SECRET mismatch with render-svc.
• Jobs claim but fail at download: MinIO not reachable over the mesh — confirm MinIO is bound to 10.66.0.1 and the presigned host in render-svc points at the mesh IP.
• AE hangs: a stale aerender.exe/AfterFX.exe — the agent force-kills these before each launch; confirm AE opens manually and isn't stuck on a "Crash Repair" dialog.