Skip to content
NovaVMS Manual

Zero-touch provisioning for a remote gateway

Use zero-touch provisioning (ZTP) when you cannot be on-site to run the pairing CLI. With ZTP you prepare the gateway on a bench, ship it to the customer, and the customer (or a generic IT contact) powers it on. The gateway pairs itself on first boot. If you are on-site with a laptop, use First gateway install instead.

There is no separate “provisioning bundle” flow today. The current cloud UI ships a single Add Gateway dialog (US-GW-1) that generates a 6-character pairing code; ZTP here is built on top of that same code, flashed onto the gateway’s config before you ship the hardware. If a first-class bundle UI ships later, Step 1 and Step 2 will need to be rewritten.

Prerequisites

  • Operator (or Admin / Owner) access to the NovaVMS org. Per D81, operators can generate pairing codes.
  • The customer’s site record already exists in the org. If not, create it first — see Create a site.
  • The destination LAN runs DHCP and has outbound HTTPS (443) to the cloud server. See Network requirements.
  • A physical gateway on your bench, running a clean Raspberry Pi OS Lite (64-bit), Ubuntu 22.04 / 24.04 LTS, or Debian 12. See Step 1 of First gateway install for the imaging flow — there is no NovaVMS-published OS image.

Step 1 — Generate a pairing code bound to the target site

  1. Open Gateways in the NovaVMS UI.
  2. Click Add Gateway.
  3. Enter the gateway name (for example the customer site name), pick the destination Site from the dropdown, then click Generate Pairing Code.
  4. Copy the 6-character code. It is valid for 10 minutes; regenerate if the code expires before you flash the bench unit.

Step 2 — Flash the pairing code into the gateway config

On your bench, run the gateway binary once in pairing mode so the config file captures gateway_id, api_key, and the ice_servers list returned by the cloud.

Terminal window
sudo /opt/novavms-gateway/novavms-gateway \
  --config /etc/novavms/gateway.yaml \
  --pair <CODE> \
  --name "<Customer site name>"

Replace <CODE> with the 6-character code from Step 1 and <Customer site name> with the same name you typed in the UI. On success the binary prints pairing successful with the gateway ID and exits. The config file at /etc/novavms/gateway.yaml now contains the API key and cloud URL.

Step 3 — Ship and boot on-site

Package the gateway. Brief the on-site contact that there is no interaction required:

  • Plug the PoE+ uplink into the designated switch port.
  • Power on. The NovaVMS gateway runs as a systemd service and starts on boot.
  • Watch for the onboard LED to go solid green. Typical time from DHCP lease to online in the cloud is 30–90 seconds on a healthy LAN — bounded below by the 30-second heartbeat interval (PRD-GW §8) plus the 5-second UI debounce (US-GW-7), and above by go2rtc startup + DHCP lease.

The on-site contact needs no NovaVMS credentials and no knowledge of the pairing code.

Step 4 — Verify in the dashboard

  1. Open the Gateways page in the NovaVMS UI.
  2. The gateway you pre-paired appears. Wait for its status badge to turn green Online.

The gateway is now ready to accept discover_cameras commands. From this point the workflow is the same as a hands-on install.

Common variations

  • Site has no internet when the gateway boots. The gateway retries the WebSocket connect with exponential backoff (1s, 2s, 4s, 8s, capped at 30s) and buffers local events for up to 1 hour (D16). Once the uplink comes up, it pairs on its own — no on-site intervention needed.
  • Pairing code expired before the gateway shipped. Generate a new code in the UI. The gateway’s config still has gateway_id and api_key from the successful bench pairing, so the code expiry only matters if Step 2 has not completed yet. If the bench --pair run failed and the code expired, generate a fresh code and rerun Step 2.
  • Wrong site selected during Step 1. Finish the install, then move the gateway: Gateways → (this gateway) → Edit → Site. The gateway itself does not need to be re-paired. See US-GW-5.

If this didn’t work

  • If the gateway row never appears in the UI, or it appears but stays Registered instead of going Online, see Gateway won’t pair.
  • If the gateway went online once and then dropped, see Gateway shows Offline.