How to Document a Homelab: What to Write Down and Where to Keep It

Cover graphic: How to Document a Homelab: What to Write Down and Where to Keep It

Core takeaway

  • Write down what the machine cannot tell you: why each service exists, which ports are open on purpose, where the passwords are kept, and how to rebuild from nothing.
  • Keep one copy that survives the lab: notes stored only on the server they describe disappear on the day you need them.
  • Leave the passwords out: record where they are kept, not what they are.
  • Update the note in the same sitting as the change: a change is not finished until its note is.

Disclosure: con1ainer.com participates in affiliate programs. This article contains no affiliate links. See the Affiliate & Commercial Disclosure.

A homelab runs happily for months with nothing written down. That is the trap. While you are building it, everything makes sense, because you are holding the whole picture in your head. Six months later you open the container list, find one called test2 listening on port 8443, and cannot say whether anything depends on it.

The server can tell you what is running. It cannot tell you why, what breaks if you stop it, or where the password lives. Documentation is the record of those things. If you are still deciding what to build, start with What Is a Homelab? A Beginner’s Guide to Hardware and Setup and come back once something is running.

Here is how that usually goes.

The Short Answer

Keep one page for the lab that answers five questions:

  1. What hardware do I have, and where is it?
  2. How is the network laid out, and what can be reached from outside?
  3. What is running, and why?
  4. Where are the keys: passwords, recovery codes, licences?
  5. If this machine died tonight, how would I rebuild and restore it?

If you can answer all five from a page you wrote down, you have documented the lab. Everything else is detail.

What Memory Loses First

Your systems and your notes hold different information. A running server will show you the current state with a few commands. What it cannot show is intent, and intent is what you forget first.

The machine will tell youOnly your notes will tell you
Which containers are runningWhy each one exists, and who uses it
Which ports are listeningWhich of them you opened on purpose, and which are forwarded from the router
How full each disk isWhat is on each disk, and which data cannot be replaced
What the config files sayWhy a setting was changed from its default
Nothing about credentialsWhere the passwords and recovery codes are kept

The Five Things Worth Writing Down

1. Hardware

One line per machine: what it is, where it sits, what is inside it, when you bought it, and when the warranty ends. Label the drives or note their serial numbers, because when a disk fails you need to know which physical drive to pull. If you run a UPS, note which machine is plugged into which outlet; Best UPS for a Home Server covers sizing it.

2. Network

Write down the address plan: which devices have reserved addresses, what each one is called, and where DNS is handled. Then write down what is reachable from outside your home, how it is reached, and why you picked that method. The trade-offs are in How to Access a Home Server Safely; the note should record which one you chose.

3. Services

One row per service: which machine runs it, which port it uses, where its data lives, why it exists, and what stops working if you turn it off. That last column is the one that saves you. If you run containers, keep the compose files together in one folder with a short comment above each service. They are documentation as well as configuration, and Docker on a VPS: A Practical Starting Point shows a layout that works the same on a home machine.

4. Access and secrets

Record which password manager holds your credentials, where the emergency copy is, where the recovery codes are stored, and which device holds your two-factor codes. Also note whether anyone else could get in if you could not. Do not copy the passwords themselves into the page. A notes file with passwords in it is a second, weaker vault.

5. Rebuild and restore

Write the steps in order, as if for someone who has never seen the lab: install the system, restore the configuration, restore the data, check that it works. Note where the backups are and the date you last restored from them. If you have not restored from them yet, write that down too. VPS Backup Strategy: How to Back Up a VPS and Actually Restore It explains the restore test, and the same logic applies at home.

A Template You Can Copy

This is a starting point in plain text. Paste it into any notes app or a file called README.md, replace the examples with your own entries, and delete what does not apply.

# Homelab notes
Last reviewed: 2026-11-06

## 1. Hardware
| Machine | Role | Inside | Location | Bought / warranty ends |
|---|---|---|---|---|
| mini-01 | main server | N150, 16 GB RAM, 500 GB NVMe | shelf, office | 2026-03 / 2029-03 |

## 2. Network
- Router: model, admin address, where the config backup is
- Reserved addresses: 192.168.1.10 mini-01, 192.168.1.11 nas
- DNS handled by: router / mini-01
- Reachable from outside: nothing / list each one, how, and why

## 3. Services
| Service | Runs on | Port | Data lives in | Why it exists | Breaks if stopped |
|---|---|---|---|---|---|
| Media server | mini-01 | 8096 | /srv/media | family movies | TV app |

## 4. Access
- Password manager: which one, and where the emergency copy is
- Recovery codes: where they are stored
- Two-factor device: which phone or key
- Anyone else who can get in: nobody / name

## 5. Rebuild
1. Install the operating system from: ...
2. Restore compose files from: ...
3. Restore data from: ... (last tested: date)
4. Check: list of things to open and confirm

## Change log
- 2026-11-06: moved DNS to mini-01 (reason)

Prefer paper? The same five sections as a printable two-page fill-in sheet:

Where to Keep It

The tool matters less than one rule: at least one copy has to be readable when the lab is down.

OptionGood forWatch out for
Markdown files in a folder under version controlA history of every change, works offline, and plain text outlasts any appYou have to commit changes, and the folder needs a copy off the lab
A notes app you already useNo setup at allWeak on tables, and usually no change history
A self-hosted wiki such as BookStack or Wiki.jsSearch and easy navigationIt is one more service to maintain, and if it runs on the lab it is unreachable exactly when the lab is down
A spreadsheetThe hardware and service tablesPoor for step-by-step rebuild instructions
A printed pageThe rebuild steps and recovery information, kept somewhere in the houseGoes stale, so print only what rarely changes

Keeping It Current

Documentation fails from neglect, not from a bad format. A few habits keep it alive without becoming a second job:

  • Write the note in the same sitting as the change. Two rough lines now are worth more than a perfect page you never get to.
  • Record why, not only what. “Opened port 8443 for the dashboard, close it when the test is done” is a note. “Port 8443 open” is a puzzle.
  • Keep a one-line change log. Date and what changed. It costs ten seconds and answers “when did this start?” later.
  • Do a ten-minute check once a month. Compare the running services and open ports against your services table. Every mismatch is either an undocumented service or a leftover you can remove.
  • Run a cold-read test. Pick one service and try to restore it using only the page. Wherever you had to guess, the page is missing something.

Mistakes That Make Notes Useless

  • Keeping the notes only on the lab itself. They are unreachable when you need them most.
  • Putting passwords in the page. Record where they are, not what they are.
  • Relying on screenshots. They cannot be searched, compared or edited, and they go out of date without anyone noticing.
  • Recording what but not why. The list of running services is easy to rebuild. The reasons are not.
  • Waiting for the perfect tool. A text file started today beats a wiki you set up next month.

Frequently Asked Questions

How much should I write down?

Enough that you could rebuild each machine from the page without remembering anything. A useful rule: if a fact took you more than five minutes to work out the first time, write it down.

Should I put passwords in my homelab documentation?

No. Record which password manager holds them and where the emergency access is kept. A notes page full of passwords is a second vault, and a weaker one.

What is the best tool for documenting a homelab?

The one you will actually update. Plain markdown files are hard to beat because they open anywhere, can be searched, and work with version control. A wiki is fine too, as long as a copy is readable when the lab is down.

How often should I update the documentation?

When something changes, in the same sitting. On top of that, a short monthly check of the running services and open ports against the page catches anything that slipped through.

My homelab is already a mess. Where do I start?

Begin with what is exposed and what cannot be replaced: what is reachable from outside, where the backups are, and where the passwords are kept. Then list what is running and give each service one line, marking the ones you do not recognise as unknown. Write the rebuild steps last, once you know what you are rebuilding.

Can homelab documentation be generated automatically?

Partly. Tools can list hardware, containers and open ports, which makes a good starting point. They cannot record why something exists. Treat generated lists as raw material for your notes, not as the notes.

Do I need this for a lab with only one machine?

Yes, in a smaller form. One page that answers the five questions is enough, and it is the page you will be glad of the first time something breaks.

Write It Down Today

Documentation is not a project to finish. It is a habit of leaving a trail for the person who will be looking at this lab in six months, who is you, and who will have forgotten everything.

One test is enough:

If this machine died tonight, could you rebuild it from the page alone?

If the answer is no, you know what to write next. Once the notes exist, give the backups the same attention: VPS Backup Strategy covers copies you can restore, and How to Access a Home Server Safely covers what to record about anything reachable from outside.

Leave a Comment