SysDash 📊🖥️

Bash • JSON Telemetry → Live Dashboard → Printable Report

A lightweight, cross-platform (best-effort) system monitor that collects host telemetry with a Bash script and serves a modern HTML/CSS/JS dashboard + a printable report page. Designed to run locally, inside Docker, or on lab machines with minimal setup.

---

Table of Contents

• 🧾 Overview
• ✨ Features
• 🧱 Core Components
• 🚀 Getting Started
• 🧭 Command Reference
• 🔁 Data & Runtime Flow
• 📦 Output Files
• ⚙️ Configuration
• 🐳 Docker Usage
• 📈 Report & Charts
• 🛠️ Dependencies
• 🏗️ Project Structure
• 📝 Notes & Limitations
• 🧯 Troubleshooting

---

🧾 Overview

SysDash is a small “collector + web UI” toolkit:

• A Bash collector gathers system information (CPU/RAM/storage/network/load/temps/GPU/SMART when possible)
• Writes latest.json (current snapshot) and appends to history.jsonl (true JSONL: one JSON per line)
• A local HTTP server serves the dashboard and report from a public/ directory

It’s meant to be portable and “best effort”: on some platforms (especially Docker Desktop on macOS/Windows), temperature telemetry may not be exposed.

---

✨ Features

• Live Dashboard (auto refresh) reading from GET /latest.json

• Printable Report Page reading from GET /history.jsonl and rendering simple charts (CPU/RAM/Storage/GPU)

• True JSONL History (safe for streaming and plotting)

• Cross-Platform Best-Effort Support

  • Linux: best results (hwmon, procfs, iproute2, etc.)
  • macOS: basic CPU/RAM/load (temps typically limited)
  • Docker/WSL: depends on host exposure of /sys and vendor tools

• GPU Telemetry (best-effort)

  • NVIDIA via nvidia-smi (requires GPU-enabled container/runtime)
  • AMD via rocm-smi (if available)
  • Fallback via /sys/class/drm/.../hwmon temps

• SMART Health Snapshot (if smartctl is available and permitted)

• Team Metadata (team name + members included in JSON and UI)

---

🧱 Core Components

🧠 Collector (Bash)

• Snapshot: writes to data/latest.json
• History: appends compact single-line JSON to data/history.jsonl
• Interval loop: runs every N seconds

🌐 Web Dashboard (HTML/CSS/JS)

• index.html shows:

  • Host info, CPU details + temp badge, RAM & storage bars
  • GPU list (if detected)
  • Filesystem snapshot from df
  • SMART status list (if accessible)
  • Network interfaces and IPs
  • System uptime/load/process count

🧾 Report Page (HTML + Canvas Charts)

• report.html:

  • Loads history.jsonl live from the server

  • Draws charts for:

    • CPU temp (°C)
    • RAM used (%)
    • Root storage used (%)
    • GPU temps (up to first 3 GPUs)

  • Has Print / Save PDF button (browser print dialog)

---

🚀 Getting Started

1) Save the Script

Make sure the script is executable:

chmod +x sysdash.sh

2) Collect Once (creates JSON files)

./sysdash.sh once

3) Start the Collector Loop (default interval = 3s)

./sysdash.sh start 3

4) Start the Web Server (default port = 8765)

./sysdash.sh serve 8765

5) Open the Dashboard

./sysdash.sh open 8765

Then visit:

• Dashboard: http://localhost:8765/
• Report: http://localhost:8765/report.html

---

🧭 Command Reference

./sysdash.sh start [intervalSeconds]   # start collector loop
./sysdash.sh stop                      # stop collector loop

./sysdash.sh serve [port]              # start local web server
./sysdash.sh unserve                   # stop local web server

./sysdash.sh open [port]               # open dashboard in browser
./sysdash.sh once                      # collect one snapshot (latest.json + history append)

./sysdash.sh report                    # ensure report.html is in place (loads history live)
./sysdash.sh status                    # show collector/server status

./sysdash.sh dockerfiles               # generate Dockerfile + docker-compose.yml
./sysdash.sh help                      # show help

---

🔁 Data & Runtime Flow

┌──────────────────┐
│  sysdash.sh once  │  → writes data/latest.json
└─────────┬────────┘    appends data/history.jsonl (1 JSON per line)
          │
          ▼
┌──────────────────┐
│ sysdash.sh start  │  → background collector loop every N seconds
└─────────┬────────┘
          │
          ▼
┌──────────────────┐
│ sysdash.sh serve  │  → serves /public over HTTP (python http.server)
└─────────┬────────┘
          │
          ├───────── GET /latest.json  → dashboard live tiles
          │
          └───────── GET /history.jsonl → report charts (canvas)

---

📦 Output Files

Default paths (relative to the script folder):

Data

• data/latest.json — latest snapshot (pretty JSON)
• data/history.jsonl — rolling telemetry history (true JSONL)

Runtime

• data/collector.pid — background collector PID
• data/server.pid — server PID
• data/server.port — chosen port

Web

• web/index.html, web/styles.css, web/app.js — dashboard
• web/report.html — report page

Logs

• logs/collector.log
• logs/server.log

The server serves a public/ folder that symlinks (or copies) the latest JSON and web files:

• /latest.json
• /history.jsonl
• /index.html, /styles.css, /app.js, /report.html

---

⚙️ Configuration

You can customize SysDash with environment variables:

# Directories
export SYSDASH_DATA_DIR="/path/to/data"
export SYSDASH_WEB_DIR="/path/to/web"
export SYSDASH_LOG_DIR="/path/to/logs"

# Runtime defaults
export SYSDASH_PORT=8765
export SYSDASH_INTERVAL=3

# Team info (shown in UI + JSON)
export SYSDASH_TEAM_NAME="Team"
export SYSDASH_TEAM_MEMBERS="Alice,Bob,Charlie"

Then run normally:

./sysdash.sh start
./sysdash.sh serve

---

🐳 Docker Usage

SysDash can generate Docker files for you:

./sysdash.sh dockerfiles

Build & Run (Docker Compose)

docker compose up --build

This exposes port 8765 by default.

Important: The provided compose config uses privileged: true and mounts /dev, /sys, and /proc to maximize telemetry. Review security implications before using on shared or production systems.

GPU Temps in Docker (NVIDIA)

• Requires a GPU-enabled Docker runtime (e.g., --gpus all) and nvidia-smi availability inside the container.
• Docker Desktop on macOS/Windows often limits access to host sensors; results vary.

---

📈 Report & Charts

The report is always available as report.html and loads history live from the server:

• Open: http://localhost:8765/report.html
• Print: click Print / Save PDF (browser print dialog)

The report reads up to the last ~600 lines from history.jsonl and plots:

• CPU temp (°C) — if available
• RAM usage (%)
• Root storage usage (%)
• GPU temps (up to first 3 GPUs) — if available

---

🛠️ Dependencies

On Host (recommended)

SysDash runs with “best effort” even when some tools are missing, but you’ll get better telemetry if you have:

• bash, python3 (for http.server)

• df, ps, awk, sed, tr

• Linux extras (optional but helpful):

  • ip (iproute2) for network JSON output
  • lm-sensors (sensors) for CPU temp reads
  • smartctl (smartmontools) for SMART health
  • nvidia-smi for NVIDIA GPU temp/util

In Docker (generated Dockerfile)

Installs:

• bash, python3, coreutils, util-linux, pciutils, iproute2, procps, smartmontools, lm-sensors

---

🏗️ Project Structure

.
├── sysdash.sh
├── data/
│   ├── latest.json
│   ├── history.jsonl
│   ├── collector.pid
│   ├── server.pid
│   └── server.port
├── web/
│   ├── index.html
│   ├── styles.css
│   ├── app.js
│   └── report.html
├── public/                # served folder (symlinks/copies)
└── logs/
    ├── collector.log
    └── server.log

---

📝 Notes & Limitations

• Temperatures are best-effort.

  • Docker Desktop (macOS/Windows): CPU temps are commonly not exposed to containers
  • WSL: CPU temps often unavailable; NVIDIA GPU temps may work with proper setup

• SMART status may require elevated permissions (e.g., sudo, privileged container, or device access)

• Network interface details depend on ip (Linux) or ifconfig (macOS)

• This is a local telemetry tool—not hardened for multi-user / internet exposure.

---

🧯 Troubleshooting

Dashboard shows “Offline”

• Make sure the server is running:

  ./sysdash.sh status

• Re-run:

  ./sysdash.sh serve 8765

CPU temperature is “N/A”

Common reasons:

• Running in Docker Desktop (macOS/Windows): host sensors not passed through
• No access to /sys hwmon/thermal entries
• lm-sensors not installed / not configured

Try on Linux host directly, or ensure /sys is mounted read-only into the container if you’re using Docker.

GPU list is empty

• NVIDIA: ensure GPU runtime is enabled (--gpus all) and nvidia-smi works inside container
• AMD: requires rocm-smi availability
• Otherwise SysDash falls back to sysfs hwmon GPU temps when available

SMART shows “UNKNOWN (need permissions?)”

• On Linux host, try:

  sudo smartctl -H /dev/sda

• In Docker, you may need privileged: true and /dev mounted (already present in the generated compose), but some systems still restrict SMART passthrough.

---