rpi-monitor

Lightweight web dashboard for Raspberry Pi system monitoring, built with Flask and Docker Compose.

rpi-monitor solves a simple problem: checking essential host metrics from a browser without logging into the device every time via SSH or running heavy monitoring stacks.

The application reads real Linux host data from /proc, /sys and the host root filesystem in read-only mode, then exposes:

• a responsive dashboard
• a JSON API
• a health endpoint for container checks

Features

• Lightweight Flask application
• Responsive web UI with automatic refresh
• JSON API at GET /api/system
• Health endpoint at GET /health
• Real host metrics through read-only bind mounts
• Docker Compose based deployment
• Minimal dependency footprint

What It Monitors

• CPU temperature
• Uptime
• Load average
• RAM usage
• Disk usage
• Hostname
• Board model
• Kernel version

Stack

• Python 3.11
• Flask
• Gunicorn
• Docker Compose

Requirements

• Docker
• Docker Compose plugin
• Linux host access to /proc, /sys and /

Configuration

This project expects a local .env file that is not committed to the repository.

1. Create your local environment file from the example:

cp .env.example .env

2. Edit .env with values valid for your machine:

RPI_MONITOR_BIND_IP=<your-host-ip>
UI_REFRESH_INTERVAL_MS=5000

Configuration variables:

• RPI_MONITOR_BIND_IP: host IP address used to publish port 8081
• UI_REFRESH_INTERVAL_MS: frontend refresh interval in milliseconds

The real .env file is local-only and should not be pushed.

Getting Started

1. Move into the project folder:

cd rpi-monitor

2. Build and start the service:

docker compose up -d --build

3. Check container status:

docker compose ps

4. View logs if needed:

docker compose logs -f rpi-monitor

Access

Once the container is running, the service is available on the host IP configured in .env on port 8081.

Examples:

• Dashboard: http://<your-host-ip>:8081/
• Health: http://<your-host-ip>:8081/health
• API: http://<your-host-ip>:8081/api/system

Useful Commands

docker compose logs -f rpi-monitor
docker compose restart rpi-monitor
docker compose down

Quick checks:

curl http://<your-host-ip>:8081/health
curl http://<your-host-ip>:8081/api/system

How It Works

• Docker Compose starts a single Flask-based service.
• The container mounts /proc and /sys from the host in read-only mode.
• The application reads Linux virtual files to collect live system metrics.
• Disk usage is calculated from the mounted host root filesystem.
• The frontend polls the JSON API every few seconds and updates the dashboard.

Project Structure

.
├── app/
│   ├── main.py
│   ├── system_metrics.py
│   ├── static/
│   └── templates/
├── DOCS/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md

Notes

• The application is designed for local or private network usage.
• If a metric is unavailable, the API returns null and the UI shows N/A.
• Local machine-specific configuration belongs in .env, not in the repository.