92 lines
3.2 KiB
Markdown
92 lines
3.2 KiB
Markdown
# Systant
|
|
|
|
A comprehensive Elixir-based system monitoring solution with real-time dashboard, designed for deployment across multiple NixOS hosts.
|
|
|
|
## Components
|
|
|
|
- **Server** (`server/`): Elixir OTP application that collects and publishes system metrics via MQTT
|
|
- **Dashboard** (`dashboard/`): Phoenix LiveView web dashboard for real-time monitoring
|
|
- **Nix Integration**: Complete NixOS module and packaging for easy deployment
|
|
|
|
## Features
|
|
|
|
### System Metrics Collection
|
|
- **CPU**: Load averages (1/5/15min) and utilization monitoring
|
|
- **Memory**: System memory usage and swap monitoring
|
|
- **Disk**: Usage statistics and capacity monitoring for all drives
|
|
- **System Alarms**: Real-time alerts for disk space, memory pressure, etc.
|
|
- **System Info**: Uptime, Erlang/OTP versions, scheduler information
|
|
|
|
### Real-time Dashboard
|
|
- Phoenix LiveView interface showing all connected hosts
|
|
- Live system metrics and alert monitoring
|
|
- Automatic reconnection and error handling
|
|
|
|
### MQTT Integration
|
|
- Publishes comprehensive system metrics every 30 seconds
|
|
- Uses hostname-based topics: `systant/${hostname}/stats`
|
|
- Structured JSON payloads with full system data
|
|
- Configurable MQTT broker connection
|
|
|
|
## Quick Start
|
|
|
|
### Development Environment
|
|
```bash
|
|
# Enter Nix development shell
|
|
nix develop
|
|
|
|
# Run both server and dashboard together (recommended)
|
|
just dev
|
|
|
|
# Or run components individually
|
|
just server # Start systant server
|
|
just dashboard # Start Phoenix LiveView dashboard
|
|
|
|
# Other development commands
|
|
just deps # Install dependencies for both projects
|
|
just compile # Compile both projects
|
|
just test # Run tests for both projects
|
|
just clean # Clean both projects
|
|
```
|
|
|
|
#### Hivemind Process Management
|
|
The project uses Hivemind for managing multiple processes during development:
|
|
- Server runs on MQTT publishing system metrics every 30 seconds
|
|
- Dashboard runs on http://localhost:4000 with real-time LiveView interface
|
|
- Color-coded logs for easy debugging (server=green, dashboard=yellow)
|
|
|
|
### Production Deployment (NixOS)
|
|
```bash
|
|
# Build and install via Nix
|
|
nix build
|
|
sudo nixos-rebuild switch --flake .
|
|
|
|
# Or use the NixOS module in your configuration:
|
|
# imports = [ ./path/to/systant/nix/nixos-module.nix ];
|
|
# services.systant.enable = true;
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Default MQTT configuration (customizable via environment variables):
|
|
- **Host**: `mqtt.home:1883`
|
|
- **Topics**: `systant/${hostname}/stats` and `systant/${hostname}/commands`
|
|
- **Interval**: 30 seconds
|
|
- **Client ID**: `systant_${random}` (auto-generated to avoid conflicts)
|
|
|
|
## Architecture
|
|
|
|
- **Server**: `server/lib/systant/mqtt_client.ex` - MQTT publishing and command handling
|
|
- **Metrics**: `server/lib/systant/system_metrics.ex` - System data collection using `:os_mon`
|
|
- **Dashboard**: `dashboard/lib/dashboard/mqtt_subscriber.ex` - Real-time MQTT data consumption
|
|
- **Nix**: `nix/package.nix` and `nix/nixos-module.nix` - Complete packaging and deployment
|
|
|
|
## Roadmap
|
|
|
|
- ✅ **Phase 1**: System metrics collection with real-time dashboard
|
|
- 🔄 **Phase 2**: Command system for remote host management
|
|
- 🔄 **Phase 3**: Home Assistant integration for automation
|
|
|
|
See `CLAUDE.md` for detailed development context and implementation notes.
|
|
|