Skip to content
NovaVMS Manual

First gateway install

By the end of this tutorial you will have a Raspberry Pi 5 running as a NovaVMS gateway, paired to your org’s cloud, and discovering one ONVIF camera on the same LAN. This is the happy path — a fresh Pi, a PoE HAT, a PoE+ switch, and one camera. Edge cases (dual-NIC, VLAN trunk, airgapped pairing) live in the how-to guides.

What you will need

  • Raspberry Pi 5 (8 GB) with the official PoE+ HAT fitted.
  • A 32 GB or larger microSD card (A2 class).
  • A PoE+ (802.3at) switch port with outbound internet on the LAN.
  • One ONVIF camera on the same LAN, powered and reachable by IP.
  • A laptop with an SD-card reader, on the same LAN as the Pi.
  • A pairing code from a NovaVMS admin. 6-character uppercase, 10-minute expiry. See US-GW-1.

Step 1 — Flash the microSD card

NovaVMS does not publish its own OS image. Flash a standard 64-bit Raspberry Pi OS Lite and add the NovaVMS gateway service in Step 4.

  1. On your laptop, open Raspberry Pi Imager.
  2. Pick Raspberry Pi 5 as the device.
  3. Pick Raspberry Pi OS Lite (64-bit) from the OS list.
  4. Click the gear icon. Set the hostname (for example novavms-gateway), enable SSH, pre-seed the novavms user and your SSH public key, and set the Wi-Fi or wired connection details if you need them.
  5. Pick the SD card. Confirm it is the right one — this erases it.
  6. Click Write.

Step 2 — Boot the Pi

  1. Insert the SD card into the Pi 5.
  2. Plug the Cat6 from the PoE+ switch into the Pi 5’s RJ45.
  3. Wait 45 seconds. The Pi’s onboard LED turns solid green when the gateway service is up.

Step 3 — Find the Pi on the LAN

  1. If you set the hostname novavms-gateway in Step 1 and your router supports mDNS, run:

    Terminal window
    ping novavms-gateway.local

  2. If mDNS works, the Pi replies. Note the IP.

  3. If ping fails, check your router’s DHCP lease table for the hostname you chose, or scan the LAN with nmap -sn.

Step 4 — Provision the gateway from your workstation

NovaVMS provisions gateways over SSH from a workstation, not via a curl-piped install script on the gateway itself. From the NovaVMS repo on your laptop, run:

Terminal window
./scripts/deploy-gateway.sh provision novavms@<pi-ip> --name "First-Gateway"

The script SSHes to the Pi, installs Go 1.25.5 to /usr/local/go, downloads go2rtc to /opt/novavms-gateway/go2rtc, clones the repo into /tmp/novavms-src, builds the gateway binary as /opt/novavms-gateway/novavms-gateway, writes config to /etc/novavms/gateway.yaml, and registers a systemd unit. Budget 3-5 minutes on Pi 5 (ARM64 build).

Step 5 — Pair with the cloud

  1. Ask your admin to open Gateways → Add Gateway in the NovaVMS web UI and generate a pairing code.

  2. Copy the 6-character code.

  3. From your workstation, run:

    Terminal window
    ./scripts/deploy-gateway.sh pair novavms@<pi-ip> <CODE>

  4. Replace <CODE> with the code from step 2.

  5. On success, deploy-gateway.sh shows pairing successful with the gateway ID, then starts the systemd unit and prints the status. The cloud URL (cloud_url) and gateway identity (gateway_id, api_key) are now persisted to /etc/novavms/gateway.yaml. Internally the script SSHes to the Pi and runs sudo /opt/novavms-gateway/novavms-gateway --config /etc/novavms/gateway.yaml --pair <CODE> (the --pair is a flag, not a sub-command).

Step 6 — Confirm the online dot

  1. Ask your admin to open the Gateways page.
  2. Your gateway appears with a green dot within 30 seconds.

Step 7 — Discover your first camera

  1. Ask your admin to click your gateway row, then click Discover cameras.
  2. The gateway scans the LAN for ONVIF cameras. Scan takes 30-60 seconds.
  3. The camera appears in the discovery list. Enter its ONVIF credentials and click Add.

Step 8 — See live video

  1. In the web UI, click the new camera.
  2. The Live tab plays a stream within 5 seconds.

You have finished

A Pi 5 gateway is paired and streaming one camera. Next, install the rest of the cameras on site: