Setting Up Your Virtual Node

Host Requirements

Virtual nodes are packaged as a ready-to-use Docker image. Before installing one, make sure your system meets the following prerequisites:

• Host system with Docker installed (Windows, Mac, Linux)
• Network access to your building automation devices
• Internet access to connect with the Novant Cloud
• Admin rights on the host system

Resource Requirements

Virtual nodes run as containerized services and should be sized based on expected load. The table below outlines baseline and higher-capacity configurations to help you choose appropriate system resources before deployment.

Configure with Docker Compose

The easiest way to run a virtual node is with Docker Compose, which keeps all settings in a single file.

1. Create a folder on your system for the virtual node (for example: ~/novant-node/).
2. Inside that folder, create a file named docker-compose.yaml.
3. Add the following content:

version: "3"
services:
  novant-vnode:
    image: ghcr.io/novant-io/vnode-base:0.4.2
    platform: linux/amd64
    restart: always
    network_mode: host
    volumes:
      - {host_data_dir}:/data/

Key Things to Know

• Platform (CPU architecture): Virtual nodes support linux/amd64, linux/arm64, and linux/arm. Most systems use amd64. If your host uses an ARM-based CPU, update the platform value to match — this avoids slower emulation.

• Storage location: Replace {host_data_dir} with a folder on your host machine where data can be saved. This folder must be non-volatile so data isn’t lost when the container restarts. See the platform-specific install guides for example paths.

• Network mode: network_mode: host is required for full network access, including BACnet device discovery and broadcast-based protocols. This mode is only supported on Linux. On Windows and Mac, Docker Desktop runs containers inside a virtual machine, which means network_mode: host does not provide true host network access. The node will still function, but discovery features that rely on broadcast traffic (such as BACnet Who-Is) may not work. In those environments, devices may need to be added manually by IP address.

• Automatic restart: restart: always is required so the container restarts automatically after a firmware update. Without this, the node will stay down after an update until manually restarted.

License Installation

Before starting your virtual node, you’ll need to install its license so it can connect to Novant Cloud.

1. In the Novant Cloud interface, go to your project’s Settings > Nodes tab.

2. Copy the license text shown for your virtual node.

3. On your host system, create a folder for secrets (if it doesn’t already exist) and add the license file:

   mkdir -p {host_data_dir}/secrets/

4. Paste the license content into:

   {host_data_dir}/secrets/node.license

Start the Container

Navigate to the folder where you created docker-compose.yaml (e.g., ~/novant-node/):

cd ~/novant-node
docker compose up -d

docker compose -f /path/to/docker-compose.yaml up -d

Stopping and Restarting

You can manage the container at any time with Docker Compose commands (run them from the same folder as your docker-compose.yaml):

# Stop the container (shuts it down, keeps data intact)
docker compose down

# Restart the container (useful after edits or updates)
docker compose restart

# Bring it back up (if it was stopped)
docker compose up -d

Post-Installation Verification

If your node is not coming online or you’re having trouble communicating with devices, see the Troubleshooting guide.