Documenting Your Home Lab Setup Effectively

Automation 2026-02-09 · 6 min read documentation organization wiki git best-practices

Every homelabber has been there: you set something up six months ago, it's been running perfectly, and now it needs a change. You stare at the configuration, trying to remember why that one weird iptables rule exists, what the NFS mount options do, or which VLAN ID goes to the IoT network. You don't remember, because you didn't write it down. You thought you'd remember. You never remember.

Documentation is the least exciting part of running a homelab and the most valuable when things break or need changing. The challenge isn't convincing people to document — everyone agrees it's important. The challenge is finding a system that's easy enough to maintain that you actually use it.

What to Document

Not everything needs documentation. Focus on things that are hard to reconstruct from the running state of your systems.

Always Document

Network topology and IP assignments. Which IPs are assigned to what. VLAN IDs and their purposes. Subnet ranges. DHCP scopes. Firewall rules and why they exist. This information is scattered across multiple devices and is miserable to reconstruct.

Service inventory. What runs where. Every container, VM, and bare-metal service. Which port it's on. What storage it uses. What depends on what. When you need to take down a server for maintenance, you need to know what will break.

Credentials and access. Where accounts exist. How to access management interfaces (IPMI, iDRAC, switch consoles). API keys and tokens. These should be in a proper secrets manager or password vault, not plain text in your docs, but the fact that they exist and where to find them should be documented.

Non-obvious configuration choices. Why you set the ZFS recordsize to 1M on the media dataset. Why that one VM has CPU pinning. Why the backup job runs at 3 AM Tuesday instead of midnight. The "why" is always harder to reconstruct than the "what."

Recovery procedures. How to rebuild your DNS server if it dies. How to restore from backups. What order to bring services up after a power outage. You won't be thinking clearly during an incident — having a checklist to follow is invaluable.

Skip Documenting

Things that are self-documenting. If your entire deployment is in Docker Compose files or Ansible playbooks checked into git, the config files ARE the documentation. Don't duplicate that into a wiki.

Step-by-step install guides for well-documented software. You don't need to write your own Proxmox installation guide. Link to the official docs and document only what you customized.

Transient state. Current disk usage, today's uptime, or which pods are running. Monitoring tools handle this better than static docs.

Where to Keep Documentation

The best documentation system is the one you'll actually update. Here are the practical options.

Git Repository (Recommended)

A git repo of markdown files is the simplest approach that works long-term:

homelab-docs/
├── README.md              # Overview and quick reference
├── network/
│   ├── topology.md        # Network diagram and VLANs
│   ├── ip-assignments.md  # Static IP allocations
│   └── firewall-rules.md  # Firewall rule documentation
├── services/
│   ├── inventory.md       # What runs where
│   ├── proxmox.md         # Proxmox cluster notes
│   ├── truenas.md         # NAS configuration
│   └── kubernetes.md      # k3s cluster setup
├── procedures/
│   ├── backup-restore.md  # How to restore from backups
│   ├── power-outage.md    # Recovery after power loss
│   └── new-vm.md          # Standard VM setup checklist
└── diagrams/
    └── network.drawio     # Editable network diagram

Advantages:

Version controlled — you can see what changed and when
Works offline — no dependency on a running service
Plain text — searchable with grep, readable everywhere
Survives your homelab going down (push to GitHub/GitLab)
Editable in any text editor

This is the approach that survives a total homelab failure. If every server is off, your git repo on GitHub is still accessible from your phone.

Self-Hosted Wiki

If you prefer a web interface for reading and editing:

Wiki.js — Modern, runs in Docker, supports markdown and a visual editor. Git-backed storage available. Good search.

services:
  wikijs:
    image: ghcr.io/requarks/wiki:2
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      DB_TYPE: sqlite
      DB_FILEPATH: /data/wiki.db
    volumes:
      - ./data:/data

BookStack — Organized into shelves, books, and chapters. Good for structured documentation. Requires a database (MySQL/MariaDB).

Outline — Clean, modern wiki with real-time collaboration. Heavier to run but a polished experience.

The downside of any self-hosted wiki: if your homelab is down, your documentation might be too. Mitigate this by backing up the wiki data to an external location, or by using Wiki.js's git sync to keep a copy in a remote repository.

Netbox (For Network Documentation)

If your homelab has grown complex enough that network documentation is its own challenge, Netbox is purpose-built for this. It's an IPAM (IP Address Management) and DCIM (Data Center Infrastructure Management) tool that tracks:

IP addresses and subnets
Devices, interfaces, and connections
Racks, sites, and power
VLANs and VRFs
Cables and circuit connections

# Install via Docker
git clone https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
docker compose up -d

Netbox is overkill for a 5-device homelab, but once you have 15+ devices across multiple VLANs, it becomes genuinely useful. It's also a great learning tool if you work in networking professionally.

Documentation Templates

Service Entry

For each service in your inventory, capture:

## Grafana

- **Host**: docker-host-1 (192.168.1.50)
- **Port**: 3000
- **Storage**: /opt/grafana/data (Docker volume)
- **Depends on**: Prometheus (192.168.1.50:9090)
- **Backup**: Included in nightly Docker volume backup
- **Access**: https://grafana.homelab.local (admin/vault)
- **Notes**: Using provisioned dashboards from /opt/grafana/provisioning/

IP Assignment Table

| IP             | Hostname     | Device/Service       | MAC               | Notes          |
|----------------|-------------|---------------------|-------------------|----------------|
| 192.168.1.1    | gateway     | OPNsense router     | aa:bb:cc:dd:ee:01 | DHCP server    |
| 192.168.1.10   | pve1        | Proxmox node 1      | aa:bb:cc:dd:ee:02 | Dell R730      |
| 192.168.1.11   | pve2        | Proxmox node 2      | aa:bb:cc:dd:ee:03 | HP DL380 Gen10 |
| 192.168.1.50   | nas         | TrueNAS SCALE       | aa:bb:cc:dd:ee:04 | 4x 8TB RAIDZ1  |
| 192.168.1.53   | pihole      | Pi-hole DNS          | aa:bb:cc:dd:ee:05 | RPi 4B         |

Network Diagram

For diagrams, use tools that produce editable source files:

draw.io / diagrams.net — Free, has a desktop app, saves as XML. The most popular option for homelab diagrams.
Excalidraw — Whiteboard-style, good for quick sketches. Saves as JSON.
Mermaid — Text-based diagrams that render in markdown. Good for simple network topologies:

graph TD
    Internet --> Router[OPNsense Gateway]
    Router --> Switch[Core Switch]
    Switch --> PVE1[Proxmox Node 1]
    Switch --> PVE2[Proxmox Node 2]
    Switch --> NAS[TrueNAS]
    Switch --> AP[WiFi AP]

Building the Habit

The hardest part of documentation is doing it consistently. Some practical strategies:

Document while you build. Don't plan to "come back and document it later." You won't. Keep a notes file open while you're setting things up and jot down what you're doing and why. Polish it later (or don't — rough notes are better than no notes).

Use your git commit messages. If your configs are in git (they should be), write meaningful commit messages. fix: add MTU 9000 to NFS VLAN interface for jumbo frames is documentation in itself.

Automate what you can. Scripts that generate inventory lists, pull IP assignments from your DHCP server, or export firewall rules to markdown reduce the manual documentation burden.

Review quarterly. Set a calendar reminder to review your docs once a quarter. Read through the service inventory. Update anything that's changed. Delete anything that's no longer relevant. Stale documentation is sometimes worse than no documentation because it misleads.

Keep it close to the code. If you have a Docker Compose file for a service, put the documentation in a README.md in the same directory. If you have Ansible playbooks, put notes in the playbook comments. Documentation that lives next to the thing it documents is more likely to get updated when the thing changes.

The Minimum Viable Documentation

If you do nothing else, maintain these three documents:

Network map and IP table — Where everything is and how to reach it
Service inventory — What runs where and what depends on what
Recovery runbook — How to bring your lab back from a total failure

These three documents cover the scenarios where missing documentation hurts the most: "I need to find something on my network," "I need to understand what's running," and "everything is broken and I need to fix it."

You don't need a perfect documentation system. You need a good-enough system that you actually use. A messy markdown file in a git repo, updated when you remember, is infinitely more valuable than an elaborate wiki that's six months out of date.