DevOps

Building a VPS Metrics Dashboard

A lightweight, self-hosted VPS monitoring solution with Python, Docker, and a web dashboard.

Introduction

Monitoring your VPS shouldn't require complex setups or expensive services. I wanted something simple, lightweight, and self-hosted that would give me real-time visibility into my servers without the overhead of Prometheus, Grafana, or cloud-hosted solutions.

So I built metrics-dashboard - a complete VPS monitoring solution that runs in a single Docker container and provides a beautiful web frontend.

What It Does

The metrics-dashboard consists of two components:

  1. Python Metrics Agent - A high-performance system metrics collector that reads directly from /proc for accurate, real-time data
  2. Web Dashboard - A responsive frontend that displays metrics with 2-second auto-refresh

Features

The Python agent collects:

All metrics are exposed via a simple JSON API with optional token authentication.

Quick Start

The easiest way to get started is with the standalone setup:

bash

That's it. The dashboard will be available at http://localhost:8080.

Architecture

Manual Deployment

If you prefer manual setup or want to integrate into an existing docker-compose:

1. Add to docker-compose.yml

yaml

2. Configure Caddy

caddyfile

3. Start and Access

bash

Dashboard: http://localhost:8080 API: http://localhost:8080/api/metrics?token=YOUR_SECRET_TOKEN

API Response

The /metrics endpoint returns comprehensive system data:

json

Why This Approach

Benefits

  • Zero external dependencies - No databases, no message queues, no complex services
  • Lightweight - Single Python container, minimal resource usage
  • Secure - Token-based API authentication, read-only container access
  • Real-time - 2-second refresh with delta-based rate calculations
  • Beautiful - Clean, modern frontend design
  • Easy deployment - Single docker-compose up command

Trade-offs

  • Single-server monitoring (not distributed)
  • No historical data storage (real-time only)
  • Basic alerting (can be added via external tools)

For my use case, these are features, not bugs. I wanted something simple that shows me what's happening now, not a complex time-series database.

Customization

The frontend is just HTML, CSS, and JavaScript. Edit frontend/index.html to customize:

  • Refresh interval
  • Color schemes
  • Layout and components
  • Additional charts or visualizations

Production Tips

If deploying to production:

  1. Change the default API token in the Caddyfile
  2. Use HTTPS with Caddy's automatic Let's Encrypt
  3. Restrict network access - don't expose the API publicly
  4. Monitor the agent - add health checks and restart policies
  5. Secure the Docker socket - the agent only needs read-only access

Live Demo

See it in action at agent.hyperflash.uk

Conclusion

Sometimes you don't need a complex monitoring stack. A well-designed single-purpose tool can give you better visibility with less overhead.

The metrics-dashboard is intentionally simple - it does one thing well: show you what's happening on your VPS right now.