Planning a Deployment¶

This guide covers everything you need to know before deploying Normal Framework at a site. Use it as a checklist to make sure your hardware, network, and licensing are ready.

Hardware Sizing¶

NF runs on modest hardware. The primary factors that affect sizing are the number of points being polled and the data retention period.

Storage notes:

• Redis (NF's data store) keeps point metadata and recent time-series in memory. Plan for roughly 1 KB per point of RAM for metadata.
• Time-series retention is configurable. The default keeps data locally before forwarding to a cloud or historian. Size storage based on your retention window and polling frequency.
• A persistent volume is required at /var/nf (soft state) and Redis's /data directory. Both should be on reliable storage with backups.

Network Requirements¶

Protocol Access¶

NF communicates with building devices over standard protocols. Ensure network access between the NF host and your device networks:

NF Service Ports¶

Upstream Connectivity¶

If you plan to use cloud features, NF needs outbound HTTPS access to:

Network Topology Recommendations¶

graph TB
    subgraph "Building Network"
        A[BACnet/IP Devices] --- B[Building Network Switch]
        M[Modbus Devices] --- B
    end
    B --- C[NF Host]
    C --- D[Upstream / Corporate Network]
    D --- E[Normal Portal]
    D --- F[Cloud / Historian]

• Dedicated NIC or VLAN for BACnet traffic is recommended on medium and large sites to isolate building automation traffic.
• If BACnet devices span multiple subnets, configure a BBMD or use BACnet/SC.
• For remote management, consider Tailscale for secure access without opening inbound firewall rules.

Choosing a Deployment Method¶

NF Gateway Appliance¶

Normal Software offers a pre-built hardware gateway that ships with NF pre-installed and configured. This is the fastest path from purchase to data collection.

What you get:

• Industrial-grade IoT gateway hardware (ARM64-based)
• NF, Redis, and all services pre-installed
• BLE-based initial configuration via the NF Config mobile app (iOS) -- configure WiFi, network settings, and view diagnostics without needing a laptop
• Over-the-air updates managed via Balena fleet management
• Enterprise auto-provisioning -- the device self-licenses on first boot

Setup flow:

1. Connect the gateway to your building network (Ethernet) and power it on.
2. Open the NF Config mobile app and connect to the gateway via Bluetooth.
3. Configure network settings (WiFi, static IP, or DHCP) if needed.
4. The gateway auto-provisions its license and appears in your Normal Portal fleet.
5. Access the management console from any browser on the same network.

When to choose the gateway:

• You want a plug-and-play experience with no OS or container management
• You're deploying across multiple sites and want fleet-managed updates
• Your team doesn't have Linux/Docker expertise on-site
• You want BLE-based setup without needing to connect a laptop

Contact Normal Software to order gateways for your deployment.

Minimum Docker Host Requirements¶

• Docker Engine 20.10+ (or Podman 4.0+)
• Linux kernel 4.18+ (for full BACnet support)
• network_mode: host support (standard on Linux; not available on Docker Desktop for Mac/Windows -- use a Linux VM for production)

Licensing¶

NF requires a license to operate. There are three license types:

Getting a License¶

1. Sign up at portal.normal-online.net to create your organization.
2. Create a license for your deployment (demo, subscription, or enterprise).
3. Activate using one of two methods:
   • Manual activation: Generate an 8-character code in the portal, then enter it in the NF management console. See Licensing for the full flow.
   • Auto-provision (enterprise): Set the AUTO_PROVISION_KEY environment variable and devices self-register on first boot.

Pre-Deployment Checklist¶

Use this checklist before you begin installation:

• [ ] Hardware provisioned -- CPU, RAM, and storage meet the sizing guidelines above
• [ ] Operating system ready -- Linux host with Docker installed
• [ ] Network access verified -- NF host can reach building devices on the required protocol ports
• [ ] Upstream connectivity -- NF host can reach portal.normal-online.net over HTTPS
• [ ] License ready -- Portal account created and license available for activation
• [ ] Firewall rules -- TCP 8080 open for management console access from your workstation/browser
• [ ] Backup plan -- Persistent volumes identified for /var/nf and Redis /data; backup schedule in place
• [ ] Credentials -- Decided on console authentication method (CONSOLE_USERNAME/CONSOLE_PASSWORD or OIDC)

What's Next?¶

Once you've checked the boxes above, proceed to deployment:

• Quick Start -- Deploy NF and collect your first data in 30 minutes
• Docker Deployment -- Detailed Docker setup reference
• Licensing -- Full licensing activation walkthrough