Skip to main content

Installation Guide

How an EmberNet edge node goes from bare hardware to a working, enrolled node.

Installation is a white-glove process. Fireball Industries provisions edge nodes with EmberRTOS already on them, and the platform services come up as part of that image. This page describes what happens and what you are responsible for, rather than handing you an installer to run unattended.

Before you start​

  • Hardware meeting the system requirements
  • A separate data disk, not just the OS disk
  • Outbound HTTPS on port 443
  • Working DNS and NTP
  • A Microsoft Entra ID tenant, with SSO configured
  • For real-time nodes, a decision on which machines need the RT kernel, made before provisioning rather than after

What the process looks like​

  1. Provisioning. The node is imaged with EmberRTOS. First boot reads a configuration medium and applies site-specific settings: hostname, networking, and any keys the node needs. See EmberRTOS (Standard) for how that mechanism works.
  2. Cluster formation. A single-node site is a cluster of one. A multi-node site joins additional nodes to the first.
  3. Platform services. These come up as containerized workloads on the node: telemetry ingestion, time-series storage, the console, the alert engine, the API, and the mesh agent. There is no manual orchestration step.
  4. Mesh enrollment. The node generates an identity, dials out to the mesh, receives its certificates and policy, and becomes reachable to authorized services. Nothing dials in. See Zero-Trust Networking.
  5. Tenant setup. The tenant is created and bound to directory groups so its users resolve to the right roles and scope.

Networking each node​

  • Give each node a static address or a DHCP reservation. Nodes whose addresses move create avoidable churn in storage and cluster membership.
  • Confirm outbound 443 actually works from the node, rather than assuming it from the firewall policy.
  • Confirm the clock. Skew shows up as certificate and enrollment failures, which is a confusing way to discover an NTP problem.

Tenant configuration​

There is no local administrator account to create, and no password to set. Access comes from your identity provider:

  1. Create the tenant with a name and contact
  2. Map directory security groups to roles, and record the group object IDs
  3. Confirm a test user lands in the expected view

If users authenticate successfully but see nothing, the group claim is nearly always the cause. SSO Integration covers that specifically.

Validating​

Work through these in order; each one depends on the one above it.

  • Every platform service reports healthy
  • The console loads and you land in the view your role should give you
  • Mesh connectivity is established and the node appears in the fleet
  • Storage volumes are Healthy, not Degraded
  • Telemetry is arriving from at least one real device
  • A test alert reaches its configured channel

The storage check is the one worth doing deliberately on a new site. A cluster with fewer nodes than replicas will report Degraded forever, and it is much cheaper to find that on day one. See Storage.

If something goes wrong​

Next steps​