A homelab grows one piece at a time: a VM to try out a service, a firewall rule added one evening, a disk replaced in a hurry. After a year, the configuration exists only in the memory of whoever built it, and memory is not reliable. On the day something breaks, or a family member has to restart the router while you are away, documentation makes the difference between ten minutes and a lost afternoon.
What to document
You do not need a corporate manual. A few categories of information, kept up to date, are enough.
Hardware inventory
For each physical device:
- model, serial number, purchase date and place, warranty expiry;
- main components: CPU, RAM, disks with serial number and slot position;
- management IP address and MAC address;
- where it physically sits and which socket or UPS it is plugged into.
Network
- a list of networks and VLANs with their purpose, address range and gateway;
- an addressing plan: which addresses are static, which are assigned by DHCP, which are reserved;
- switch ports: what is connected to each port and on which VLAN;
- the most important firewall rules, with the reason they exist.
Services
For each service:
| Field | Example |
|---|---|
| Name and purpose | family photo archive |
| Where it runs | «media» VM on host pve1 |
| How to reach it | internal name, port, any reverse proxy |
| Where the data is | path on the NAS, container volume |
| Backup | which job, how often, where |
| Dependencies | database, network storage, local DNS |
| Updating | how it is done, what to check first |
Credentials
The documentation does not contain passwords. It only says where they are: for example, the matching entry in the password manager. For emergency credentials, such as the backup encryption key, it is worth keeping a printed copy in a safe place.
The runbook: instructions for the worst day
A runbook is a step-by-step procedure for a specific operation, written so that someone unfamiliar with the system could follow it, or you yourself a year from now under stress. The most useful runbooks at home:
- full recovery after a host failure: reinstalling the hypervisor, connecting storage, restoring VMs from backups, in the right order;
- replacing a failed disk in the NAS or pool;
- what to do when the Internet is down: which devices to restart and in what order, who to call;
- renewing certificates or keys that expire;
- instructions for the family: a simple printed page with the two or three operations they can do on their own.
A runbook is only worth something if it has been tested. In my work I verify it by actually running it at least once, correcting any steps that turn out to be ambiguous.
The tools
Text files in a repository
The simplest and most durable solution: Markdown files in a folder under Git. They can be read with any editor, searched with grep, and keep a history of changes. If Compose files and configurations live in the same repository, documentation and configuration stay close together.
Self-hosted wiki
Tools such as BookStack or Wiki.js offer a web interface, search and organisation into chapters. They are handy if several people consult the documentation. One risk not to underestimate: if the wiki runs in the homelab, on the day of the failure it is unreachable. You need a periodic export in a format readable offline.
NetBox
NetBox is an open source tool created to document networks and data centres: racks, devices, cables, IP addresses, VLANs, circuits. In a homelab it may seem excessive, but it becomes useful as the number of addresses and ports grows, because it also works as IPAM, meaning IP address management, and stops you assigning the same IP twice.
Network diagrams
A drawing is worth many lines of text. Diagram tools such as draw.io, also available as a self-hosted version, let you represent routers, switches, VLANs and hosts. Save the diagram in an editable format, not only as an image, or it will never be updated.
Keeping it up to date
Documentation ages faster than hardware. A few habits help:
- update while working, not afterwards: a line written during configuration costs less than reconstructing it from memory;
- a change log, with the date and a short description of each intervention;
- generate automatically whatever you can: lists of VMs, DHCP-assigned addresses, container versions;
- periodic review, for example every quarter, comparing the documentation with reality.
A copy outside the homelab
Documentation is needed most when the homelab is not working. It must therefore exist elsewhere too: on the laptop, in an encrypted archive on another device, and for the essential pages, on paper.
In short
- An inventory of hardware, network and services covers most needs.
- Passwords do not belong in the documentation, only a pointer to where they are.
- Write and test runbooks for recovery, disk replacement and Internet outages.
- Markdown files in Git are the most durable base; NetBox helps as networks and addresses grow.
- The documentation must be readable even when the homelab is down.
