The Cost of Poor Homelab Docs: Restore Notes You Can’t Find During an Outage

The outage is never the hard part. The hard part is the note you wrote six months ago that lives on the box that just died. I have stood in a closet with a good backup and a dead Wiki.js, and I have stood there with a printed passphrase that turned out to be last year’s passphrase. Poor homelab docs do not fail in a review. They fail when the only light is a phone torch and the only machine that knew the VLAN ID is the one you are trying to bring back.

I treat backups as restore rehearsals. I still lose Saturday to a sentence I never wrote down. This is the cost: not the missing screenshot of a compose file, but the missing path to the thing you need while the house is dark.

The wiki that is also the patient

Bookstack on the NAS is a fine place for how I set up Immich. It is a terrible place for how I unlock the NAS. I have done this. I have also put the Borg repo passphrase hint in a Markdown file on the same dataset the repo lives on. That is not a hint. That is a compliment to the disk that failed.

Obsidian on the laptop is better until the laptop is at work and you are home. A git remote helps if git is not on the same UPS as the lab. A phone copy helps if you can unlock the phone when you are tired. I have unlocked neither on a night I would rather not retell.

The rule I use now is rude and short: the restore note must survive the thing it restores. If the note needs power, DNS, and a container you named “docs,” it is a hobby page. It is not an outage document.

What has to be findable in twenty minutes

Not the novel. Not the architecture diagram you made for fun. The list that gets the household a network again:

• Where the last-good router image lives, and its checksum.
• WAN type: DHCP, PPPoE, a VLAN the ISP pretends you do not need to know.
• The admin path that is not “the bookmark on the dead PC.” An IP. A failsafe key combo if you use OpenWrt.
• Which switch port is the WAN, which is the AP, which is the camera VLAN. Tape on the jack beats a wiki table.
• UPS load order: what you unplug so the NAS gets ten more minutes.
• Where the backup actually is: USB in a drawer, restic to a friend, Borg to a bucket whose endpoint you can type from memory or from paper.
• How you unlock that backup. Not “it’s in Bitwarden” if Bitwarden is Vaultwarden on the NAS.

If a line is not useful with the lab off, it does not belong on the outage page. Put it in the wiki for later. I keep two piles on purpose. Mixing them is how the outage page becomes a blog.

I thought I printed the key

I have lost a Borg repo to a key I thought was printed. The paper in the fire safe was a recovery sheet from a password manager I had already rotated. The current key was in a keepass file whose copy was on the disk I was restoring. That is not bad luck. That is a docs problem wearing a crypto costume.

restic is the same story with a different mascot. A green forget policy and a missing password is a museum. I have pruned on a Tuesday and discovered on a Sunday that the only printed password was for the old repo ID. The dashboard was still green. The note was still wrong.

Print the current secret, date it, and destroy the last sheet. Or do not print it and accept that you will call a friend who holds the sealed envelope. What I will not do again is assume last year’s envelope is this year’s key because both say “Borg” in my handwriting.

Secrets versus findability

A one-pager on the fridge is a gift to anyone who enters the house. A one-pager in a lockbox is a gift to you at 2 a.m. if you can open the lockbox when you are shaking. I use a small cash box whose combination is not stored in the lab. The combination is a thing two adults in the house can recite. That is a household decision, not a security blog.

I do not put cloud admin passwords on that sheet. I put the path: which manager, which item name, and a second factor that is not an SMS to a dead phone if I can help it. If the vault is self-hosted on the dead host, the sheet has the emergency kit or the printed master — dated — or I have already lost.

People will tell you to memorize. I have memorized a passphrase and then changed it because a guide said rotate. Memory is not a backup of the note. The note is a backup of memory.

Labels beat literature

A switch with tape — WAN, AP, IoT, unused — has saved me more often than a Bookstack chapter titled “Network.” When the lights are out you are not browsing. You are matching colors. I label PSUs with wattage. I label the USB that holds the last-good Proxmox backup with a date, not with “important.”

Rack photos on a phone album called “lab” are a document. I take them after every cable change. I have skipped that and then traced a loop with a tone generator I borrowed from a neighbor. The photo is cheaper.

Hostnames on a sticky under the chassis beat DNS when DNS is the patient. I still run DNS. I still write the IP on the tin.

Where I keep the outage page now

One printed sheet in the lockbox. One photo of that sheet in an encrypted album that is not on the NAS — a phone backup to a consumer cloud I already pay for, or a second phone. One USB with a text file and the last-good images, in the same box. The USB is not the backup of the family photos. It is the boot and the notes.

I still have Bookstack. I use it for how Immich’s ML workers behave and which compose override pins a version. I do not use it for the first twenty minutes. If Bookstack is up, the outage is already a different outage.

Git on a tiny VPS is a reasonable third copy if the VPS is not your only DNS and not your only mail. I have used a private repo that is just outage.md. I have also used a repo that grew into the whole lab diary and then I could not find the PPPoE line. Keep the file stupid. One heading. A date at the top. If you need a search box, you already lost the plot.

The drill that finds the docs

A restore drill that starts from a running wiki is a tutorial. A restore drill that starts with “unplug the NAS, now find the note” is the real cost check. I do this twice a year. I time how long until I am holding the current passphrase, not a passphrase. If I cannot do it in twenty minutes without the lab, the docs failed. The backup software did not get a vote.

I also drill the household. Someone else should be able to read the sheet and plug the WAN back into the labeled port. If only I can decode my handwriting, I have written a puzzle. I rewrote the sheet in dull sentences after I watched a partner squint at “PVE host / vmbr0 / don’t touch.”

The drill is when you discover the printer was out of toner the month you “printed” the new key. Paper that does not exist is the same as a wiki on a dark disk.

What I stopped writing down

Package lists. Every sysctl I ever tried. The novel about why I chose Caddy over Traefik that year. Those belong in git if they belong anywhere. During an outage they are noise. Noise is how you miss the VLAN ID that is three lines below a paragraph about MTU.

I stopped documenting “temporary” port forwards. They were never temporary. They also were never on the outage sheet, which is correct, because the outage sheet should not invite you to recreate a hole. If a forward is required for a family service, it is a product and it gets a line. If it is a experiment, it dies with the power loss. That is a feature.

Tools I will name and then ignore

Wiki.js, Bookstack, Outline, a Hugo site, Notion, Obsidian, a Google Doc. I have used four of those. They are for the Tuesday you still have coffee. For the outage I want a .txt, a date, and a box I can open without a certificate. If your personality needs a pretty wiki, keep it. Do not let it be the only copy of the twenty-minute list.

Password managers are documents too. Bitwarden, Vaultwarden, KeePass, 1Password’s emergency kit. The product is not the vault. The product is the path to the vault when the host is dead. I will not pretend a self-hosted vault is available in a power cut. I will pretend a printed kit in a box is, if I dated it.

The cost, in hours I can count

The last time the notes were wrong I spent three hours reconstructing a PPPoE password from an ISP chat that wanted a billing PIN I had in a manager on the dead host. The circuit was up. The house was not, because I was the router. The backup of the VM was fine. The docs were a story I told myself in June.

That is the bill. Not a SaaS invoice. A Saturday, a partner who wanted Wi-Fi, and a version of me who had written “later” on a sticky that later never arrived.

The decision

Write the twenty-minute page. Put it where the lab cannot take it down. Date the secrets. Drill from a dark NAS, not from a browser tab. Keep the pretty wiki for the rest. If you cannot find the restore note during an outage, you did not document a homelab. You documented a hope. I still like Bookstack. I like a lockbox more when the lights go.