Linux Fleet Management System

A complete, end-to-end Web-based Linux Fleet Management System with real-time observability, remote command execution, and centralized node management.

Architecture Overview

Browser -> Frontend (5173) -> Backend (8080) -> PostgreSQL/Redis
                                    |
                            (REST & WebSocket)
                                    v
                                Agent (9200) <- (native /proc scraping)
                                    ^
Prometheus (9090) ------------------|
     |
     v
(HTTP SD from Backend:8080/api/v1/internal/prometheus-targets)
     ^
     |
Grafana (3001)

Quick Start

1. Copy the environment variables:

   cp .env.example .env
   # Ensure FLEET_JWT_SECRET is set to a secure string in .env

2. Start the infrastructure via Docker Compose:

   docker compose up -d

3. Access the web interfaces:

   • Frontend: http://localhost:5173 (Login: admin / admin)
   • Grafana: http://localhost:3001 (Dashboards -> Fleet)
   • Prometheus: http://localhost:9090

Building the Agent

The agent is a statically linked C++ binary designed to be deployed to target Linux nodes without dependencies.

cd agent
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

Onboarding a Node

1. Log into the Fleet Manager Frontend.
2. Navigate to the Nodes page.
3. Click Add Node and enter the node details (Hostname, IP Address).
4. Copy the generated curl command.
5. SSH into the target node and run the command as root.
6. The agent will install via systemd, connect back via heartbeat, and appear Online in the dashboard within 30 seconds.

Verifying Metrics

• Go to the Metrics page in the Frontend to see the embedded Grafana dashboard.
• Verify that Prometheus is discovering your nodes by checking the "Prometheus Active Scrape Targets" table.
• Verify backend logs (docker compose logs -f backend) to confirm agent heartbeats and scraping success.

Environment Variables

Variable	Description	Default
POSTGRES_DB	Database name for PostgreSQL container	fleetdb
POSTGRES_USER	Database user for PostgreSQL container	fleet
POSTGRES_PASSWORD	Database password for PostgreSQL container	fleetpass
FLEET_JWT_SECRET	Secret key for JWT signing	(required)
FLEET_PROMETHEUS_URL	URL of the internal Prometheus server	http://prometheus:9090
FLEET_ALLOWED_IPS	CIDR blocks allowed to hit internal endpoints	172.0.0.0/8
FLEET_LISTEN_PORT	Port the backend listens on	8080
FLEET_REDIS_HOST	Hostname of the Redis cache	redis
FLEET_REDIS_PORT	Port of the Redis cache	6379
VITE_API_URL	Base URL for the frontend API client	http://localhost:8080

Observability Principles

This project strictly adheres to modern observability principles:

• USE Method: The agent surfaces Utilisation, Saturation, and Errors across CPU, Memory, Disk, and Network via raw /proc parsing.
• Four Golden Signals: The Grafana dashboard is heavily oriented toward visualizing load and capacity using accurate rate() aggregations.
• Prometheus Conventions: All metrics use standard Prometheus naming (e.g. node_cpu_seconds_total, node_memory_MemTotal_bytes).
• Push vs Pull: High-resolution metrics are pulled statelessly by Prometheus, while low-frequency status (heartbeat) and ad-hoc commands use push/REST patterns.