build a free grafana + prometheus monitoring stack for your homelab

why you should actually know what's happening on your own boxes

most homelab people find out something's wrong when a vm falls over, a disk fills up, or their nas starts acting weird at 2am. that's reactive. the fix is boring and free: a monitoring stack that tells you cpu, memory, disk, and network behavior in real time, before it becomes a problem. this is also exactly how production environments at real companies work, scaled down to whatever you're running in a closet.

the stack: what each piece actually does

three tools, one job, split cleanly.

prometheus is the brain. it pulls metrics from targets on a schedule and stores them as time series data. it doesn't generate metrics itself, it just scrapes them.

node-exporter is the sensor. it runs on each machine you want to watch and exposes raw system stats (cpu load, memory usage, disk io, network throughput) on a simple http endpoint. prometheus scrapes this endpoint.

grafana is the face. it queries prometheus and turns all those numbers into dashboards you can actually read without squinting at raw json.

spinning it up

the whole thing comes up with one command if you've got a docker-compose.yml defining the three services:

docker compose up -d

the -d just runs it detached so it doesn't hog your terminal. behind the scenes this pulls three images, wires them together on a shared docker network, and starts them. prometheus listens on port 9090, node-exporter on 9100, grafana on 3000.

confirming it's actually collecting data

don't trust a green "running" status, check the actual output. node-exporter exposes raw metrics as plain text, so you can hit it directly:

curl localhost:9100/metrics

if that returns a wall of text with lines like node_cpu_seconds_total and node_memory_MemAvailable_bytes, your exporter is healthy and prometheus has something to scrape. if it times out or connection refuses, check that the container is actually up with docker ps before you go further.

making it readable: grafana dashboards

raw metrics mean nothing to a human at a glance, so this is where grafana earns its keep. log into grafana at localhost:3000, add prometheus as a data source pointing at http://prometheus:9090 (the docker service name, not localhost, since they're talking to each other inside the compose network), then import a pre-built dashboard instead of building one from scratch.

dashboard id 1860, "node exporter full," is the community standard. import it, select your prometheus data source, and you instantly get cpu, memory, disk, network, and uptime panels for every host you're monitoring. no query writing required to get started.

the part everyone skips: locking it down

this is where a useful homelab tool turns into an open door if you're not paying attention. a few things to fix immediately:

change the default grafana login. admin/admin is the first thing anyone scanning your network tries. set a real password on first login, don't put it off.

keep ports 9090 and 9100 off the public internet. prometheus and node-exporter have no authentication by default. anyone who can reach port 9100 can read detailed system metrics about your machine, and anyone who can reach 9090 can query your entire metrics history. bind these to localhost or your internal lan only, never forward them through your router.

only expose grafana if you have to, and put something in front of it. if you want dashboard access from outside your network, use a reverse proxy with tls and ideally a vpn like wireguard or tailscale instead of a raw port forward. check what's actually reachable with a quick scan from outside your network, or at minimum review your router's port forwarding rules.

segment it. if this stack lives on the same subnet as your other devices, a compromised monitoring container can see a lot of your network. a dedicated vlan for homelab infrastructure isn't paranoid, it's just good hygiene.

the takeaway

this stack gives you real visibility into your own systems for zero dollars, and that visibility is the whole point of defense: you can't protect what you can't see. but monitoring tools are also attack surface. set a real password, keep the scrape ports internal only, and treat this stack with the same care you'd give any other service holding data about your network. build it, lock it down, then actually look at the dashboards once in a while.