Skip to content
NovaVMS Manual

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. From your workstation (with the NovaVMS repo checked out), run the deploy script in update mode:

    Terminal window
    ./scripts/deploy-gateway.sh update <ssh-user>@<gateway-ip>

    The script SSHes to the gateway, pulls the latest code into /tmp/novavms-src, builds an ARM64 or AMD64 binary with CGO_ENABLED=0, stops the systemd unit, swaps /opt/novavms-gateway/novavms-gateway, restarts the service, then runs status. There is no on-host update.sh — the gateway is always updated remotely. See scripts/deploy-gateway.sh:334-375.

  6. Watch the script’s tailing output (or run ./scripts/deploy-gateway.sh logs <target> 50) 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 — deploy-gateway.sh update builds the ARM64 binary in /tmp/novavms-src on the Pi itself. Budget 3–5 minutes on Pi 4, 2 minutes on Pi 5.
  • Docker-based gateway — docker-compose.gateway.yml does not ship a published image; it has a build: step. From a Git checkout, rebuild and recreate with bash scripts/build-gateway-image.sh && docker compose -f docker-compose.gateway.yml up -d. The build script exports a source revision and timestamp as BUILD_VERSION; TARGETARCH can be set for ARM hosts. docker compose pull is a no-op here because no image: field is set.
  • macOS launchd gateway — deploy-gateway.sh update handles macOS automatically: do_stop/do_start in the script call launchctl bootout system/com.novavms.gateway and launchctl load -w /Library/LaunchDaemons/com.novavms.gateway.plist per scripts/deploy-gateway.sh:385-399.

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.