How to Document Your Home Lab (The Right Way)

It is something that we all hate to do, I know I do. But, it is something that you will always be glad that you have – documentation. Even with our very “in flux” home labs, documentation is a great thing to have and something you don’t want to skimp on. Even if you only have a single mini PC with a few VMs running, good documentation, keeps things organized, and MAJORLY helps when you need to troubleshoot. Let’s take a look at how to document your home lab the right way.

Why Documenting Your Home Lab Matters

I think most realize the importance of documentation, but let’s just consider a few key points on why it is extremely important, especially with a home lab. I would even argue, as “in flux” as most home lab environments are, documentation is even more important!

Take a look at the following key points that documentation helps with:

• Troubleshooting: You can retrace your steps if things break or you have a major issue
• Reproduce your steps: It makes things much easier to replilcate if you want to reproduce your steps
• Learning: They say when you write something down it reinforces the concepts and information in your own memory, which helps with learning
• Automation: Documenting things helps to identify patterns and other areas where scripting or other information may be extremely beneficial.
• Learning compliance: By getting into the habit of documenting things in your home lab, you will be much better positioned to tackle compliance requirements in production environments.

Start with an Inventory

Many may hold off on documentation, simply because they just don’t know where to start. It may seem daunting to know where you dive into documenting your lab environments. However, the most basic first step to documenting any IT system is having a good inventory of all the components, both hardware, and software.

Take a look below at a few ideas of things you will want to take note of and document:

• Hostnames, IP addresses, MAC addresses
• Make, model, serial numbers
• BIOS/UEFI versions
• Firmware and driver versions
• Operating systems and versions
• Installed software and services
• Rack or room location (if you have more than one location)

Tools to Use:

There are many tools that can help with this first step. Most may start out with the oldest method of simply keeping a spreadsheet. However, there are many open-source and free tools available out there that can help to keep track of things.

• Google Sheets / Excel: The simplest way to get started, just start putting things in a spreadsheet
• phpIPAM: For getting your IP address information, keeping track of VLANs, IPs, MAC addresses, etc, phpIPAM is a solution that is great for this and I have used this successfully in my lab environment for quite some time now
• NetBox: Another great open-source solution for tracking networks, devices, and you can even keep track of your racks, gear, locations, etc

Use Diagrams to Visualize Architecture

If you are like me, having a picture is definitely worth a thousand words, especially as time goes along and your memory starts to fade on exactly how things are connected or why certain things are where they are. Drawing a diagram is a great way to overcome this and have the visual representation of your lab environment that you need to keep things documented and tidy.

Recommended Diagram Tools:

There are many drawing tools out there that are either free or commercial products that have a free version of their tool

• Draw.io (diagrams.net): Free and easy to use
• Excalidraw: Free solution that you can even self-host
• Lucidchart: Offers more polished visuals, a pay-for tool, but has a free version
• Obsidian Canvas: Markdown-based and great for power users that use Obsidian
• Visio: Classic enterprise tool from Microsoft

Diagram Examples:

What are some examples of great things to document using a diagram?

• Network topologies (LAN, VLANs, WAN)
• VM to virtual host mappings
• Application dependency mapping – which applications or self-hosted resources depend on what containers, VMs, etc
• Storage layout NAS, shares, targets, etc

Keep Track of Configuration Files

Be sure to keep track of your configuration files that are important in the environment. Using a Git repo is a great way to document your config files, as it keeps up with versioning and changes for you and allows you to roll back changes to files, etc.

Use Git to track changes in:

• Firewall rules (pfSense, OPNsense)
• Docker Compose files
• Kubernetes YAML manifests
• Ansible playbooks
• Proxmox VM config files

Recommended Tools:

• Git + GitHub / GitLab / Gitea: Private repos for your lab that you can self-host, outside of GitHub
• VS Code: Arguably the best editor with Git integration

Create a Knowledge Base or Wiki

Having a knowledge base or Wiki, acts like a “second brain” that allows you to recall and search information that you have stuffed in from various projects, etc

Note the following self-hosted options you can take advantage of for this purpose:

• Wiki.js: a modern and Markdown-based tool
• BookStack: Really good UI and it is easy to use
• DokuWiki: Flat-file based and it is easy to use
• Obsidian: Very popular open-source tool that you can self-host with Git
• HedgeDoc: Great for collaborative Markdown notes
• Gitbook: Commercial tool, but has a free offering for one user which may be all you need for home lab

What should you include in these types of how-to guide tools?

• How-to guides (e.g., “How to add a new Proxmox node”)
• Troubleshooting steps that you have figured out maybe from a previous incident
• OS installation guides
• Container image details and configs
• Upgrade and patch notes, failure notes, etc

Document your network

Networks tend to grow complex fast and can become confusing if not documented. There are many must-have details that should be documented, so you have this information for troubleshooting or if you experience an outage for one reason or another:

Think about documenting the following information and details:

• VLAN IDs and their purposes
• Subnets and reserved IPs
• DHCP scopes and static addresses
• Firewall rules and NAT configurations
• Wi-Fi SSIDs and passwords

Tools that can help:

Several tools can help with this task of documenting your network and keeping an accurate record of your network:

• Unifi Controller: The Unifi network controller has a built-in topology mapper, and can easily have pages printed from in a browser
• NetBox: mentioned earlier, but a great tool for this purpose
• Nmap: Running periodic scans with Nmap can help mapping OSes or any other unknown endpoints or resources in your network

I like the great visuals that Unifi gives you. I have even printed out these pages to have easy visuals of network uplinks, etc.

Automation

Automation can help create built-in documentation as you create the automation scripts themselves. By their very nature, Infrastructure as Code (IaC) tools document your infrastructure in the code itself.

Note the following tools that can be beneficial:

• Terraform: Define cloud or on-prem infrastructure declaratively
• Ansible: Automate configuration management and provisioning
• Packer: Automate VM image creation

Store your scripts in Git and add README files to explain what each script does.

Create backups of your configs and documentation

If you document your lab but don’t back up the documentation, you’re still vulnerable. For instance, if you document everything in a solution you are self-hosting, if your lab goes down, your documentation is locked away in the offline infrastructure of the lab itself when you may need it the most.

Think about keeping backups in the following locations:

• External drives (versioned with restic or borg)
• Cloud storage (Google Drive, Dropbox, or S3)
• Synology / TrueNAS NAS with snapshots

Create backup jobs that grab a copy of your documentation folders.

Label Everything

This is something that I am not very good at – labeling. It is a good idea to label things like cables, ports, servers, and switches. You think you will remember 6 months later what a cable uplinks or which server is sitting on the right and which one is on the left, but you won’t.

I have started documenting in port strings and port descriptions which ports uplink what and if they uplink to another switch, which switch port on the other switch it uplinks to. This just makes life easier months down the road.

But, don’t forget the physical labeling too, like power cables, network cables, USB cables, or anything else that is plugged into a lab resource that you might forget about later.

• Ethernet and power cables
• VLAN tags on ports
• Server names on physical devices
• Storage bay assignments

I use a label printer that makes printing legible labels much easier. This is the label printer I have for my lab, the Dymo LetraTag (Amazon affiliate link below):

• https://amzn.to/43L9hDN

Keep a change log

Be sure to document your changes and things you are testing or experimenting with. You will be surprised at how helpful this will be in keeping up with things and troubleshooting an issue a few days later that you didn’t realize was related to changes you may have recently made.

Keep up with things like:

• Date
• What changed
• Why it changed
• Who made the change
• Any issues making the change?

Even a simple CHANGELOG.md file goes a long way kept in your favorite repository solution.

Think about where you host your documentation

This is a similar point to what was stated in an above section. Keep your documentation where you can access it easily. I love self-hosting documentation tools. However, think about whether or not it can be easily accessed off your network, or if your home lab environment is down, can you still get to critical documentation that you need to use to troubleshoot?

Ideas to host your documentation:

• You can host your wiki on your home server (as long as you have a backup location)
• Sync a Markdown folder with Syncthing as an example
• Use a lightweight static site generator like MkDocs and serve it via Nginx for an easy self-hosted solution

Wrapping up

Documenting your home lab is a worthwhile investment of time as it makes sure you have the information you need at a later time to troubleshoot and reproduce your environment if needed. There are many great open-source tools avaialble out there that can be beneficial to getting everything documented. Keep in mind that if you store all your documentation in a self-hosted solution, you may be in a catch 22 if your home lab goes down and you need to access documentation to troubleshoot. Your documentation may be found in a VM, container, or storage that isn’t accessible if it is offline. Keep secondary copies in another location that is easy to access. What are you using for your home lab documentation? Let me know in the comments.