initial POC

README.md

@@ -1,2 +1,68 @@
-# cheap_system_monitor
+# Cheap System Monitor
 
+A small Linux system monitor for Ubuntu and Raspberry Pi OS (including the
+Raspberry Pi 5). It stores metrics in a fixed-size RRD database and produces
+PNG graphs for the last 3 hours, 1 day, 2 weeks, and 1 year.
+
+It collects:
+
+- processor load averages (1, 5, and 15 minutes)
+- CPU user, system, and nice usage
+- total network receive/transmit throughput
+- disk usage for `/` and up to two additional mountpoints
+- memory usage
+
+## Install
+
+Python 3 is already included in supported distributions. Install RRDTool,
+clone/copy this directory, and run the installer:
+
+```sh
+sudo apt update
+sudo apt install rrdtool
+sudo ./install.sh
+```
+
+Edit `/etc/cheap-system-monitor.conf` to choose network interfaces,
+mountpoints, and the graph directory. For example, use
+`mountpoints = /, /boot/firmware, /mnt/data` to monitor two additional disks;
+every configured path must be mounted and accessible.
+Restarting is unnecessary after configuration changes—the next timer runs use
+the new values. If the RRD has already been created, do not change the order of
+mountpoints unless you intentionally want the historical graph labels to refer
+to different disks.
+
+The generated PNG files and a responsive, auto-refreshing `index.html` are
+placed in `/var/www/html/system-monitor` by default.
+With a web server installed, such as nginx or Apache, they can be served
+directly; otherwise they can simply be opened or copied as PNG files.
+
+## Check operation
+
+```sh
+systemctl list-timers 'cheap-system-monitor*'
+journalctl -u cheap-system-monitor.service -n 20
+rrdtool info /var/lib/cheap-system-monitor/system.rrd
+```
+
+Run either job manually with:
+
+```sh
+sudo systemctl start cheap-system-monitor.service
+sudo systemctl start cheap-system-monitor-graphs.service
+```
+
+The first meaningful network rate appears after two collection samples. A new
+installation naturally needs time to accumulate history; RRD archives are
+consolidated to five-minute samples for two weeks and hourly samples for a year.
+
+## Run from the source tree
+
+For development or a non-system installation, copy the example configuration,
+change its paths to writable locations, then use:
+
+```sh
+cp cheap-system-monitor.conf.example cheap-system-monitor.conf
+python3 system_monitor.py --config cheap-system-monitor.conf
+python3 generate_graphs.py --config cheap-system-monitor.conf
+```