A home network that documents itself.
Everything overhead is a homelab — a cluster of computers in one house, running the services a household actually uses, from movie streaming to smart-home control. What makes it unusual is that the entire system is described by a single Git repository, and the map above is drawn straight from it. This guide explains what you're looking at: how to read the wires, what each machine is for, and the two ideas that hold it together.
01 How to read the map hover any box to trace just its wires
Every line is a real pathway between two services, coloured by the kind of traffic it carries. Hover a box to light up only its connections and dim the rest; the switches in the top bar turn each traffic type on and off. Four are shown by default — the ones running constantly.
Showing by default: metrics · logs · alerts · probe. Flip the other four on from the traffic switches in the top bar to see encryption, DNS, login and the Git heartbeat overlaid.
02 The seven machines each box in the map is a host
Most of the boxes on the map are a single physical computer; a couple are the network gear — the firewall and the switching fabric — that everything else routes through, drawn here because the lab watches them just as closely as the servers. One machine is the deliberate exception: the Raspberry Pi 5 appears as two boxes. Its monitoring stack and its scheduled control jobs share a single board, but they reboot, fail, and get tinkered with on entirely different schedules — so it is clearer to read them as two separate hosts.
The storage box, and the things that need to sit next to storage. It holds the movie and photo libraries and plays them back, manages downloads, and runs the smart-home hub. Its processor has no video-acceleration chip, so streaming is done in software — which is why it's kept deliberately uncrowded: every spare cycle is one a transcode can use.
The observability core — the upper of the two Pi 5 boxes. Prometheus gathers every number, Loki holds every log, Vector pipes logs into it, and Grafana draws the graphs. A dozen small “exporters” translate each device into numbers Prometheus can read. If you want to know the state of anything in the lab, you look here.
The same Pi 5, in its other role. This is the desk you actually tinker at, and the home of the scheduled jobs that keep the Git repository honest — the hourly sync, the weekly snapshot, the daily dashboard export. Because it's the machine that gets poked and rebooted, the lab is built so that nothing critical to noticing problems depends on it staying up.
The machine you never touch. It carries the jobs that must keep working when everything else is being worked on: network DNS, the HTTPS front door, the uptime monitor, push notifications, and the routing of alerts. It even holds a tiny self-heal that can restart a stuck service on the router. It runs all this precisely because it survives a reboot of the collection point.
The one heavyweight x86 box, always on. It's home to the modded Minecraft server and acts as the spare-capacity pool for anything too demanding for a Raspberry Pi. Its two monitoring agents report back to the collection point like every other host.
The front gate between the house and the internet. It runs no apps — it routes and filters traffic — but it streams its firewall logs into the collection point and its configuration is snapshotted into the repo every week, so even the gateway is version-controlled.
Not servers — the wiring and Wi-Fi every other machine talks through. They appear on the map because the lab pings them constantly: if a switch or access point stops answering, you want to know before anything plugged into it does.
03 Two ideas that shape everything
Collect everything in one place.
Monitoring is pull-based: one box — the collection point — reaches out and asks every machine for its numbers and logs, rather than each machine having to know how to reach the dashboards. Adding a new host is a one-line change: point the central scraper at it, and it shows up on the map. This is the heaviest traffic in the lab, and why it's on by default above.
Keep the alarm on its own circuit.
The thing that tells you something is broken must not share a fate with the thing
you're most likely to break. So alerting lives on pi4 — the machine nobody
touches — while metrics and logs live on the Pi you actively tinker with. Reboot the
collection point and the alarm keeps watching; it can even nudge a stuck router back to life.
04 The repo is the source of truth GlassBaby/homelab @ main
The entire lab is defined as code in one Git repository: every container, every config file, and every scheduled job exists first as version-controlled text. Nothing runs that the repository does not describe, which makes the repo itself — not any single machine — the authoritative record of how the system is meant to behave. To answer the question “what is this lab?” you read the repository, not the running hosts.
The mechanism that keeps that claim true is a closed loop, not a one-way deploy. Configuration is committed and rolled out to the hosts in the usual direction; an hourly job then runs the reverse, reading the running state of each machine and committing it back. When something drifts — a value changed by hand, a container updated in place — the next sync records the difference as a commit. The gap between what the repo declares and what is actually running is therefore always measurable, and never silent.
Two properties follow from this design. First, secrets are SOPS-encrypted before they are ever written to Git, so the repository can hold the complete system without exposing a single credential. Second, the map at the top of this page is not maintained by hand — it is generated from the same repository on every reindex. The diagram is a direct read of the source, which means it cannot disagree with the code that produced it: if the picture looks wrong, the repository is wrong.
describe in code
Every service is a compose file and a config, kept as plain text in the repo.
pull reality back
An hourly timer captures what's actually running and commits it, so the repo stays truthful.
secrets stay sealed
Passwords and keys are SOPS-encrypted before they're stored, plus weekly config snapshots.
the map is the code
This topology is re-indexed from main — what you see is exactly what the repo says.