Fleet Management
Overview
Fleet Management is the central control plane for all distributed edge gateways. Instead of SSH-ing into each device individually, Fleet Management provides a single dashboard to register, monitor, and manage all devices remotely.
Key Features
Device Dashboard
The dashboard provides a real-time overview of all registered edge devices:
- KPI Cards — Total devices, online, warnings, offline, updating (auto-refreshing)
- Device Table — Sortable, filterable, paginated list of all devices with status, site, health score, and last heartbeat
- Device Detail Drawer — Click any device to view CPU/RAM/disk usage, running connectors, and event history
- Configurable Auto-Refresh — Choose update interval (5s, 10s, 30s, 60s, or off)
Device Registration
- Click Register Device in the dashboard
- Enter a Device Name and Site (select existing or create a new one)
- After registration you receive:
- A registration token (valid for 24 hours)
- A ready-to-use install command
Run the install command on the target device to set up the agent automatically:
curl -sSL http://<management-host>/api/fleet/agent/install.sh | \
REGISTRATION_TOKEN=<token> \
DEVICE_ID=<uuid> \
MANAGEMENT_URL=http://<management-host> bash
The device appears in the dashboard within seconds.
Monitoring
Each device sends a heartbeat at a regular interval (default: every 30 seconds) containing:
- System Metrics — CPU, RAM, and disk usage
- Device Information — OS, kernel, architecture, uptime
- Connector Status — List of all running ALP-CONNEX connectors with name, type, and status
Health Score
Each device receives a Health Score (0–100) calculated from its system metrics:
| Factor | Healthy | Warning | Critical |
|---|---|---|---|
| CPU Usage | < 70% | 70–90% (−15) | > 90% (−30) |
| RAM Usage | < 75% | 75–90% (−10) | > 90% (−25) |
| Disk Usage | < 80% | 80–90% (−10) | > 90% (−25) |
| Connector Status | All running | — | Proportional penalty up to −20 |
The health score determines the device status:
| Status | Meaning |
|---|---|
| Online | Health score ≥ 80 |
| Warning | Health score < 80 |
| Offline | No heartbeat for 2× the heartbeat interval (default: ~60 seconds) |
| Updating | Update command in progress |
Remote Commands
Commands can be sent to devices from the dashboard and are executed on the next heartbeat:
| Command | Description |
|---|---|
| Restart Connectors | Restarts all connector containers on the device |
| Update | Pulls a specified image and restarts the target container |
| Configure | Pushes a configuration payload to the device |
Command status is tracked in the device's event log.
Site Management
Devices can be assigned to sites. Sites are created during device registration and allow filtering and grouping in the dashboard.
Agent Installation
Prerequisites
- Docker must be installed on the target device
- Root access for installation
- Network connectivity to the management server
Automated Installation
The easiest way: copy the install command from the UI and run it on the device. The script will:
- Check prerequisites (Docker, architecture)
- Download the agent Docker image from the management server (~8 MB)
- Create the configuration under
/opt/connex-agent/ - Start the agent as a Docker container
Agent Configuration
| Setting | Required | Default | Description |
|---|---|---|---|
MANAGEMENT_URL | Yes | — | Management server URL |
REGISTRATION_TOKEN | First start | — | One-time token from the UI |
HEARTBEAT_INTERVAL | No | 30 | Seconds between heartbeats (10–300) |
STACK_VERSION | No | dev | Reported software version |
Persistent Data
The agent stores its data under /opt/connex-agent/data/:
| File | Purpose |
|---|---|
device-id | Unique device identifier |
device-secret | Authentication key (assigned during initial registration) |
device-config.json | Configuration pushed from the server |
Troubleshooting
Device not appearing in dashboard
- Check agent logs:
docker logs connex-agent - Management URL reachable?
curl http://<host>/api/fleet/devices/stats - Registration token expired? (24h validity)
Device shows "Offline"
A device is marked offline if no heartbeat has been received for over 2 minutes:
- Is the agent container running?
docker ps -f name=connex-agent - Check network connectivity to the management server
No connectors reported
The agent discovers connectors by inspecting running Docker containers. Requirements:
- Docker socket must be mounted
- Connector containers must use the ALP-CONNEX naming scheme