Server Health Dashboard

When you're running multiple apps on a single VPS, you need to know what's happening on that machine. Is the CPU spiking? Is a container eating all the RAM? Did Nginx stop responding?

I could have installed Grafana, Prometheus, or any number of off-the-shelf monitoring tools. But that would have defeated the purpose. I wanted to understand how monitoring actually works — where the numbers come from, how they get from the kernel to a chart on a screen, and what it takes to build something real-time.

So I built my own dashboard from scratch. No frameworks, no monitoring libraries. Just Node.js talking directly to the Linux kernel, the Docker Engine, and Nginx — then streaming it all to a browser over WebSockets.

It lives at admin.zacharystocks.com and monitors the very server it runs on.

Every decision on this project came back to one question: where does the data actually come from?

Monitoring tools feel like magic until you realize there's no magic involved. CPU usage? It's a text file. Container stats? It's an HTTP request to a Unix socket. Nginx traffic? A single line of config exposes it. The trick is knowing where to look and how to read what you find.

Here's what I decided early on:

Custom Node.js, no frameworks. Consistent with everything else on this server. The HTTP server, routing, static file serving, and WebSocket handling are all built by hand. Express would have saved some lines, but wouldn't have taught me anything.

Read from the source. Instead of shelling out to tools like top or htop and parsing their output, I read directly from /proc — the pseudo-filesystem where the Linux kernel exposes system information in real time. It's what those tools read under the hood anyway.

Docker Engine API over the Unix socket. Docker exposes a full REST API at /var/run/docker.sock. You can make HTTP requests to it just like any other API — you're just sending them over a socket instead of a network port.

In-memory ring buffer for history. No database for metrics storage. A ring buffer holds the most recent 10 minutes of readings and automatically discards anything older. Simple, fast, zero dependencies.

WebSockets for real-time streaming. Instead of the frontend polling for updates every few seconds, the server pushes new data to all connected clients the moment it's collected.

Linux exposes system information through /proc, a pseudo-filesystem that doesn't exist on disk — it's generated on the fly by the kernel. Every file in /proc is a window into what the system is doing right now.

The dashboard reads from four sources:

/proc/stat for CPU usage. This file contains cumulative CPU time counters measured in "jiffies" (typically 1/100th of a second). The counters track how much time the CPU has spent in different states: user processes, system calls, idle, waiting on I/O, and more. Since the numbers are cumulative, you can't just read them once — you need two readings and calculate the delta to get a percentage. The collector takes a baseline reading, waits, then takes another and computes the difference.

/proc/meminfo for RAM. This gives you total memory, free memory, available memory, buffers, and cache. One important insight: MemFree looks alarmingly low on healthy Linux systems because the kernel aggressively uses free RAM for file caching. MemAvailable is the number that actually tells you how much memory is usable.

/proc/loadavg for system load. Three numbers representing the 1, 5, and 15-minute load averages. The collector normalizes these against the CPU core count so you can tell at a glance whether the system is overloaded — a load of 2.0 on a 2-core machine means something very different than 2.0 on an 8-core machine.

df for disk usage. Disk stats aren't cleanly exposed in /proc, so this is the one place the collector shells out to an external command. It filters out virtual filesystems so you only see real storage.

Since the dashboard runs inside a Docker container, the host's /proc is mounted read-only into the container at /host/proc. The path is configurable via an environment variable so the same code works both in development and in production.

With the system metrics handled, the next question was: how do I monitor each Docker container individually?

Docker runs a daemon in the background that manages all your containers. That daemon exposes a full REST API — the same API that the docker CLI uses. Every time you run docker ps or docker stats, the CLI is just making HTTP requests to this API under the hood.

The difference is where that API lives. Instead of listening on a TCP port, it listens on a Unix socket at /var/run/docker.sock. A Unix socket works like a network connection, but between processes on the same machine — no network stack involved, faster, and more secure since it's not reachable from the outside.

To talk to it from Node.js, you make a standard HTTP request but tell it to use the socket path instead of a hostname and port. No Docker SDK needed, no libraries — just Node's built-in http module pointed at a different kind of address.

The collector hits two Docker API endpoints:

/containers/json returns a list of all containers with their status, names, image info, and when they were created. This is the equivalent of docker ps.

/containers/{id}/stats?stream=false returns a single stats snapshot for a specific container — CPU usage, memory consumption, network I/O, and more. The stream=false parameter is important: without it, Docker keeps the connection open and streams stats continuously, which isn't what we want for a polling-based collector.

To make this work, the Docker socket is mounted into the dashboard container via docker-compose.yml:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

This gives the dashboard container the ability to query (and potentially control) Docker on the host. It's a powerful capability and a real security consideration — the dashboard can see every container on the system.

Nginx has a built-in module called stub_status that exposes basic traffic metrics. Enabling it is a single location block in the Nginx config — I set it to only respond to requests from localhost so it's not publicly accessible.

The module returns a plain text response with active connections, total accepted connections, total handled requests, and how many connections are currently reading, writing, or waiting. It's not much, but it's enough to see traffic patterns and spot anomalies.

The collector fetches this endpoint over HTTP, parses the text response, and calculates a request rate by comparing the current total against the previous reading.

The REST API

With all three data sources wired up — system metrics from /proc, container stats from the Docker socket, and traffic data from Nginx — the next step was exposing them through clean API endpoints:

• /api/system — CPU, memory, disk, load average, uptime
• /api/containers — status, memory usage, and restart count for each Docker container
• /api/nginx — active connections, request rate, and connection states
• /api/metrics — a combined snapshot of everything above in one response

Each endpoint returns JSON. At this point the dashboard was already useful — you could curl any endpoint from the terminal and get a clear picture of the server's state. But the real goal was a live UI, and that required solving two more problems: storing history and streaming updates.

The API endpoints gave me snapshots, but a dashboard needs history. "What's the CPU at right now?" is useful. "What has the CPU looked like over the last 10 minutes?" is a chart.

The Ring Buffer

A ring buffer is a fixed-size circular array. You write to it sequentially, and when you reach the end, it wraps around and starts overwriting the oldest entries. At 5-second intervals with 120 slots, it holds exactly 10 minutes of history — and memory usage never grows.

Think of it like a circular track: you keep writing forward, and old data drops off the back. No database, no cleanup jobs, no growing memory footprint. When the buffer is full, the write position wraps back to index 0 and the oldest reading disappears.

A collector module runs on a setInterval — every 5 seconds it gathers a complete metrics snapshot from all sources and pushes it into the ring buffer. The REST API endpoints then read from the buffer instead of collecting fresh metrics per request.

WebSocket Streaming

Normal HTTP is request-response: the client asks, the server answers, the connection closes. If the frontend wanted live updates through HTTP, it would have to poll — sending a new request every 5 seconds. That works, but it's wasteful.

WebSocket is a different protocol. It starts as an HTTP request (the "upgrade handshake") and then stays open as a persistent two-way connection. Once connected, the server pushes data to the client whenever it wants — no polling, no repeated handshakes.

The dashboard uses the ws package for this. When a client connects over WebSocket, two things happen: first, the server sends the full ring buffer contents so the frontend can populate its charts with historical data immediately. Then, every 5 seconds when the collector runs, it broadcasts the latest snapshot to every connected client.

The result: you open the dashboard and charts are already populated with 10 minutes of history. New data points appear in real time without the page ever making another HTTP request.

With data flowing through the WebSocket, the frontend's job was to visualize it. The UI is a single HTML page with Chart.js handling the graphs.

The layout is split into three areas:

System gauges at the top show CPU usage, memory usage, and disk usage as real-time values that update every 5 seconds. These give you an instant read on overall server health.

Container cards show each Docker container's status, uptime, memory consumption, and restart count. If a container is down, the card reflects that immediately. This replaced what PM2 monitoring would have handled before I migrated to Docker.

Time-series charts plot CPU and memory over the 10-minute window stored in the ring buffer. When the page loads, the WebSocket connection fires and the server sends the full buffer contents — so the charts populate with history instantly rather than starting from a blank canvas and slowly filling in.

The Chart.js update cycle was the interesting part. When a new WebSocket message arrives, the frontend parses it, pushes the new data point onto the chart's dataset, and calls chart.update('none'). The 'none' parameter skips the animation — important for real-time data where you're updating every 5 seconds. With animation enabled, the chart would constantly be in motion and harder to read.

The Nginx section shows active connections and a request rate counter, giving a sense of how much traffic the server is handling at any given moment.

Everything is served as static files from the dashboard's public/ directory — plain HTML, CSS, and vanilla JavaScript. No build step, no bundler, no frontend framework.

A monitoring dashboard that's open to the internet is a security problem — it tells an attacker everything about your infrastructure. The dashboard needed authentication, and it needed to cover both the HTTP routes and the WebSocket connection.

HMAC Cookie Authentication

The auth system uses a password check combined with a signed session cookie. When you visit the dashboard, the server checks for a valid session cookie. If it's missing or invalid, you're redirected to a login page.

The cookie is signed using HMAC (Hash-based Message Authentication Code) with a server-side secret. When a login succeeds, the server creates a session value, computes its HMAC signature, and sets both as a cookie. On subsequent requests, the server recalculates the HMAC and compares it to the one in the cookie — if they don't match, the cookie has been tampered with and is rejected.

This works for WebSocket connections too. The initial WebSocket handshake is a regular HTTP request, so it includes cookies. The server validates the cookie during the upgrade handshake and rejects the connection before it's established if the auth check fails.

The password and signing secret live in a .env file that never touches version control — a lesson learned the hard way about how Docker Compose handles environment variables and special characters.

Discord Webhook Alerts

The final piece: getting notified when something goes wrong without staring at the dashboard 24/7.

The alert system runs threshold checks on each metrics snapshot. If CPU exceeds 90%, memory passes 85%, disk crosses 90%, or any container goes down, the system fires a notification to a Discord channel via a webhook URL.

Webhooks are elegantly simple. Discord gives you a URL. You POST a JSON payload to that URL with a message. Discord displays it in the channel. No bot framework, no OAuth, no library — just a single HTTPS request from Node's built-in https module.

To avoid alert fatigue, the system tracks which alerts are currently active and only sends a notification when an alert transitions — fires when a threshold is crossed, and resolves when it drops back below. No repeated messages every 5 seconds while CPU is high.

This project taught me more about how Linux works than anything else I've built.

Before the dashboard, /proc was just a mysterious directory. Now I know it's where the kernel publishes real-time system data as plain text files — and that every monitoring tool in existence is just reading from the same source. Understanding that removed an entire layer of mystique around DevOps tooling.

The Docker Engine API was a similar revelation. I'd been using the docker CLI as a black box. Learning that it's just an HTTP client talking to a Unix socket changed how I think about Docker — it's not magic, it's an API like any other, just with a different transport mechanism.

WebSockets were the first time I'd built anything truly real-time. The shift from request-response to persistent connections opened up a whole new category of things I can build — chat, live collaboration, multiplayer games. The ring buffer pattern for bounded-memory history storage is something I'll use again.

Building auth from scratch — HMAC signing, session cookies, protecting both HTTP and WebSocket routes — forced me to think about security at every layer rather than trusting a middleware package to handle it.

What's running now

The dashboard is live at admin.zacharystocks.com, monitoring the server that hosts this portfolio and every other app I've built. It collects metrics every 5 seconds, streams them to any connected browser, and pings me on Discord if something goes sideways.

What's next

Future ideas include container management (restart, stop, and remove containers directly from the dashboard), process-level monitoring via /proc/[pid]/stat, long-term metrics storage in SQLite, and web analytics integration. The foundation is there — each of those is an extension of something already built.