Runbook — Edge Gateway Install

Status: v1 · Owner: Data Platform / Field Ops · Phase 3 §5.8 deliverable.

The Atlas edge gateway agent (apps/edge-agent) bridges field data (BACnet/IP, or a simulator for bench testing) to the Atlas ingest API, with local store-and-forward so readings survive connectivity loss.

Prerequisites

A host with Node.js ≥ 20 (edge device or VM).
Network reachability to the Atlas URL.
A tenant API key with the ingest.write scope — create it in the app: Admin → API Keys → New key (copy the plaintext once).
(Optional, for BACnet) the node-bacnet driver and a reachable BACnet/IP device.

Install & run

# On the gateway host
git clone <repo> && cd <repo>
corepack enable && pnpm install --filter @atlas/edge-agent...

cd apps/edge-agent
cp gateway.env.example gateway.env
#   set ATLAS_URL, ATLAS_API_KEY, GATEWAY_NAME, POINTS, SOURCE, UPLINK
node --env-file=gateway.env --import tsx src/index.ts

Run it under a process supervisor in production (systemd unit or a container). Example systemd unit:

[Unit]
Description=Atlas Edge Gateway
After=network-online.target

[Service]
WorkingDirectory=/opt/atlas/apps/edge-agent
EnvironmentFile=/opt/atlas/apps/edge-agent/gateway.env
ExecStart=/usr/bin/node --import tsx src/index.ts
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Verifying flow

Start the agent; logs show uplinked N reading(s) each interval.
In the app, open Data → Telemetry for the configured POINTS data point — live values appear (via SSE).
Pull the network cable / block the Atlas URL: logs switch to uplink failed — buffering N; readings accumulate in BUFFER_FILE.
Restore connectivity: the buffered backlog is flushed on the next successful uplink and the buffer is cleared.

Troubleshooting

Symptom	Cause / fix
`ATLAS_API_KEY is required`	Set the env var to a key with `ingest.write`.
Uplink 401	Key revoked / wrong scope — reissue with `ingest.write`.
`BACnet source requires the node-bacnet driver`	Install `node-bacnet` and set the device config, or use `SOURCE=simulator`.
`MQTT uplink requires a broker`	Use `UPLINK=rest`, or stand up EMQX/Mosquitto for the MQTTS path.
Buffer file growing	Atlas unreachable — readings are being preserved; they flush on reconnect.