Skip to content
NovaVMS Manual

Update gateway firmware

Update gateway firmware

Use this to deploy a new novavms-gateway binary to a production gateway. Update one gateway at a time — multi-site installs should do them serially, not in parallel, so at least one gateway is always serving.

Procedure

  1. Confirm a maintenance window is agreed. Target: off-hours for the site (typically 02:00–05:00 local).

  2. If the site has a redundant gateway, confirm it is Online and covering the same cameras. If no redundant gateway, notify operators: cameras will show Offline for ~60 s.

  3. Cordon the gateway — in Gateways → (this gateway) → Disable. New sessions stop; existing ones finish.

  4. Wait 30 s for in-flight recordings to flush. Check the gateway’s logs show no recording in progress entries.

  5. SSH to the gateway host and run the update script:

    Terminal window
    sudo /opt/novavms-gateway/update.sh

    The script pulls the latest binary, stops the service, swaps the binary at /opt/novavms-gateway/novavms-gateway, and restarts via systemctl.

  6. Watch journalctl -u novavms-gateway -f for connected to cloud websocket and video tunnel established. Expect both within 15 s.

  7. In Gateways → (this gateway), confirm the green Online dot and the new version string. Heartbeat age should be < 30 s (US-GW-7).

  8. Un-cordon the gateway — click Enable. Cameras cascade back through pending to online within 1–3 s each (US-CAM-16).

  9. Open Live view on 2–3 bound cameras and confirm first frame renders. Check FPS against the baseline you noted pre-update.

Common variations

  • Raspberry Pi bare-metal gateway — update.sh builds the ARM64 binary in /tmp/novavms-src. Budget an extra 2–3 minutes for the build on Pi 4.
  • Docker-based gateway (TUTK_PM_TEST profile) — use docker compose -f docker-compose.gateway.yml pull && up -d instead of update.sh. Build step takes 2–5 minutes.
  • macOS launchd gateway — replace systemctl steps with launchctl bootout / launchctl load per com.novavms.gateway.plist.

If this didn’t work

  • Gateway stays Offline after restart → check journalctl -u novavms-gateway for auth failures; re-pair if API key was rotated.
  • New version not shown → cloud caches version for 15 s; refresh the Gateways page.
  • Cameras stuck pending > 2 min after un-cordon → Camera stuck in pending.