Setting Up Your Virtual Node

Virtual nodes are packaged as a ready-to-use Docker image. Before you install one, make sure your system meets these basics:

• Host system with Docker installed (Linux required)
• Resources: At least 1 GHz CPU, 1 GB RAM, and 1 GB of storage
• Network access to your building automation devices
• Internet access to connect with the Novant Cloud
• Admin rights on the host system

Once you’ve checked these off, you’re ready to install.

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.1
    platform: linux/amd64  # adjust if your host uses ARM
    restart: always
    network_mode: host
    volumes:
      - {host_dir}:/data/

Key Things to Know

• Platform (CPU architecture): This field tells Docker which build of the image to use. Virtual nodes support:

  • linux/amd64
  • linux/arm64
  • linux/arm

  In most cases, you can leave the value as linux/amd64 since it’s the most common architecture. If your system uses an ARM-based CPU (arm64 or arm), update the value to match your host. This ensures the correct image is used and avoids slower emulation.

• Storage location: Replace {host_dir} with a folder on your host machine where data can be saved. (This folder must be non-volatile so information isn’t lost when the container restarts.)

• Network mode: network_mode: host is required for the node to properly talk to devices on your network.

• Automatic restart: restart: always makes sure the container restarts automatically after a firmwware update.

• Persistent data: The /data/ directory inside the container will always map back to your chosen host folder.

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

License Installation

After your virtual node is running, you’ll need to add 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 contents of your virtual node license file.
3. On your host system, create a folder for secrets (if it doesn’t already exist) and add the license file:

$ mkdir -p {host_dir}/secrets/
# Paste license content into:
{host_dir}/secrets/node.license