Skip to content
NovaVMS Manual

Install a gateway

Use this procedure for a gateway that will stay at the site — Raspberry Pi 5, Intel NUC, or an Ubuntu/Debian box. The gateway talks to cameras on the LAN and tunnels video to the cloud over TCP 443.

What you will need

  • The gateway unit: Pi 5 (8 GB) + PoE HAT, Intel NUC, or equivalent per Supported hardware.
  • Power: PoE+ (802.3at) on the switch port, or 12 V DC injector + barrel jack.
  • One terminated Cat6 drop from the gateway location back to a PoE-capable switch port.
  • A pairing code from the admin: 6-character uppercase alphanumeric, 10-minute expiry (US-GW-1).
  • Optional for first boot: USB keyboard, HDMI cable, a monitor.

Procedure

  1. Unbox the gateway and confirm the model matches the work order.
  1. Mount the gateway. Horizontal shelf, 600 mm above floor minimum, away from direct heat. For rack mounts use the vendor’s 1U or half-rack kit. Torque rack screws to 1.8 N·m.
  1. Connect Ethernet. Terminate the Cat6 drop with T568B at both ends. Test with a cable meter — end-to-end continuity on all 4 pairs, no shorts.

  1. Apply power. For PoE+: plug the Cat6 into the gateway’s PoE-in RJ45 and bring up the switch port with PoE enabled. For DC: plug the 12 V barrel jack.

  2. Wait for first boot. Pi 5 takes 30-45 seconds; NUC takes 20-30 seconds. The gateway’s front LED stays solid green when the WebSocket to the cloud is up.

  1. Open a laptop on the same LAN. Run ping <gateway-ip>. The IP comes from the site IP plan or DHCP lease table.

  2. Provision the gateway from your workstation. There is no NovaVMS-published OS image and no one-line installer script — the gateway host runs a clean Pi OS, Ubuntu 22.04+, or Debian 12, and you provision it over SSH with the repo script. From the NovaVMS repo on your laptop, run:

    Terminal window
    ./scripts/deploy-gateway.sh provision <ssh-user>@<gateway-ip> --name "<Site-Gateway>"

    The script installs Go 1.25.5, downloads go2rtc, clones the repo into /tmp/novavms-src, builds the gateway binary, and writes a systemd (Linux) or launchd (macOS) unit. Installs to /opt/novavms-gateway/novavms-gateway, config at /etc/novavms/gateway.yaml, data at /var/lib/novavms-gateway/. See scripts/deploy-gateway.sh:81-222 for the full sequence.

  3. Pair the gateway. Replace <CODE> with the 6-character code from the admin:

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

    The script SSHes to the gateway and runs the local binary with --pair <CODE> against the cloud URL already in /etc/novavms/gateway.yaml. On success the binary saves gateway_id and api_key back to that file, then deploy-gateway.sh starts the systemd unit.

  4. Confirm the heartbeat. The admin’s Gateways page shows a green dot for this gateway within 30 seconds. Ask them to confirm.

  1. Close up. Lock the rack door or replace the shelf cover. Tag the gateway with its asset ID and the site code.

Variations

  • Airgapped install. Pairing always requires a one-time round trip to the cloud (the cloud mints the api_key), so a fully airgapped first boot is not supported. The closest workflow is bench-pair before shipping — see Zero-touch provisioning for a remote gateway.
  • Pre-provisioned gateway. If the unit was paired at the office, skip step 8 — power-on is all that is needed. Verify step 9 still passes.
  • Silent pairing via QR. Not supported. Pairing is always a 6-character code entered on the gateway CLI; there is no QR ingestion path in the gateway binary or the camera input.

If this didn’t work