Quick Start¶

This guide takes you from zero to a working NF instance with data flowing in about 30 minutes, using the NF installer and Docker.

Prerequisites¶

• A Linux host -- Ubuntu 22.04+, Fedora 42+, or any system with Docker or Podman already installed (see Planning a Deployment for sizing). A Mac with Docker Desktop works for evaluation only.
• A Normal Portal account
• Network access to your building's BACnet, Modbus, or Fox devices (or just follow along without devices to explore the UI)

Step 1: Install NF¶

Run the installer from the NF SDK:

curl -fsSL https://raw.githubusercontent.com/normalframework/nf-sdk/master/install.sh | sh

The installer installs Docker if it isn't already present, then prints a sign-in link:

── Sign in to Normal ──

  Sign in to Normal to set up this site and authorize the download:

    https://portal.normal-online.net/activate?code=ABCD-EFGH

Open the link on any machine, sign in, choose Free demo or an existing license, set the site name and location, and click Activate. The installer then pulls the nf-full and redis images, writes docker-compose.yml and .env to /opt/nf (~/nf for rootless Docker/Podman and macOS), starts NF, and licenses the box -- no activation code or registry login needed.

Re-running the installer upgrades in place: it keeps your ports and data and pulls the latest images. Set NF_TAG to install a specific version, or NF_PORT to change the console port. See the NF SDK README for all options.

Enterprise and offline installs¶

To install without the portal -- for example on an air-gapped site, or from CI -- run the installer with --offline and supply your registry pull credentials:

curl -fsSL https://raw.githubusercontent.com/normalframework/nf-sdk/master/install.sh \
  | sh -s -- --offline

It prompts for the credentials (or reads NF_USERNAME and NF_PASSWORD), pulls Enterprise images from normalframework.azurecr.io, and does not activate a license; Enterprise images don't need one.

Using the compose files directly¶

The installer is a wrapper around the compose files in the SDK's compose/ directory: linux.yml (host networking, the default), linux-rootless.yml, and macos.yml (bridge networking, evaluation only). To manage the deployment yourself, start one of them with docker compose; they read REGISTRY (default normal.azurecr.io, the GA registry; set normalframework.azurecr.io and docker login to it for Enterprise), NF_TAG, NF_PORT, NF_DATA_DIR and NF_REDIS_DIR from the environment or a .env file. If the host can reach the registry but not GitHub, point the installer at a local copy with NF_COMPOSE_FILE.

Step 2: Access the Management Console¶

When the installer finishes, it prints the console address -- http://<your-host-ip>:8080 by default. If port 8080 was already in use, the installer picks another port and prints it.

You should see the NF dashboard with the site map and status cards.

To view logs or restart NF:

cd /opt/nf && sudo docker compose logs -f
cd /opt/nf && sudo docker compose up -d

(Use ~/nf, without sudo, for rootless and macOS installs.)

Step 3: Check Your License¶

A box installed with the sign-in link is licensed automatically. Check Settings > License for a "Licensed" status.

Offline and CI installs of GA images come up unlicensed. To license one manually:

1. Log in to Normal Portal.
2. Navigate to your organization and create a license (or select an existing one).
3. Click Activate and choose your instance. The portal generates an 8-character activation code (valid for 15 minutes).
4. In the NF management console, go to Settings > License and enter the activation code.

Step 4: Review Your Site¶

Sites represent buildings or physical locations, and provide context like timezone and location. The sign-in creates a site with the name and location you entered. To review it or add more:

1. Go to Sites in the left navigation.
2. Click Add Site, or select an existing site to edit it.
3. Enter:
   • Name: Your building name
   • Address: The street address (timezone and coordinates auto-fill if address lookup is available)
4. Click Save.

Step 5: Configure a Network Port and Discover Devices¶

BACnet¶

NF automatically uses the default network interface for BACnet communication. You only need to add a network port in Settings > BACnet > Network Ports if your BACnet devices are on a different network adapter than the default.

1. Go to Discovery in the left navigation.
2. Click New Scan and run a device discovery. NF sends a BACnet Who-Is broadcast and populates the device list.

1. Select the devices you want to scan and click Scan Objects. NF reads all objects from each device and imports them as points.

Modbus¶

1. Go to Modbus > Connections and click Auto-detect.
2. Enter the device IP addresses, a range or a subnet, and start the scan. NF identifies devices and matches them to a built-in profile.
3. Check the preview values, select the devices, and click Import selected. For devices without a built-in profile, see Modbus to create one.

Fox (Niagara)¶

1. Go to Settings > Fox Connections.
2. Add a connection to your Niagara station.
3. See Fox for connection setup details.

Step 6: Verify Your Points¶

After discovery, your points appear in the Object Explorer.

1. Go to Object Explorer in the left navigation.
2. You should see your discovered devices and their objects listed.
3. Click on any point to see its current value and properties.

Step 7: Configure Polling¶

By default, discovered points don't poll automatically. Set up data collection:

1. In the Object Explorer, select points you want to poll (use filters or multi-select).
2. Right-click and select Set Poll Period.
3. Choose an interval (e.g., 60 seconds for most sensors, 300 seconds for slower-changing values).

Points with active polling show live values updating in the explorer.

What's Next?¶

You now have NF deployed, licensed, and collecting data. Here's where to go from here:

Troubleshooting¶

Can't access the management console on port 8080?

• Use the address the installer printed -- it moves the console off 8080 if that port was taken
• Verify the containers are running: cd /opt/nf && sudo docker compose ps
• Ensure your firewall allows TCP on the console port

No devices found during BACnet discovery?

• Confirm the NF host is on the same subnet as BACnet devices (or that a BBMD is configured)
• Check that UDP 47808 is not blocked
• Try a directed discovery to a specific device IP instead of broadcast

License activation code not working?

• Codes expire after 15 minutes -- generate a fresh one in the portal
• Ensure the NF host can reach portal.normal-online.net over HTTPS