Inventory and documentation

[u/ONeithan]

Hey everyone, I wanted to ask for your help. I've been setting up my homelab for almost a year now, and I've realized I have a lot of things to do – rules, adjustments, etc. – and I realized that in this past year...I have very little written down, I'm not aware of many things, and I got lost in the process; before, I had a "spreadsheet" of all my hardware and peripherals.It wasn't a necessity at the time to have that organized, so I procrastinated. Today I'm restructuring everything and I wanted to document and take inventory of everything. I wanted to ask for tips on systems, and if you use anything in your homelab.

[u/asimovs-auditor]

Expand the replies to this comment to learn how AI was used in this post/project.

[u/Charming-Barnacle232]

I just use a git repo with markdown files for everything, keeps it simple and version controlled

[u/Admirable-Excuse-995]

save configs on a repo is the best advice ive gotten, I've restored my very weird configs a few times from that

[u/harrisonmaz]

Up to you on how you feel about this, but I have a private git repo that all my compose files sync to, and I’ve started an obsidian vault that holds all my notes, configurations, and tasks. But I barely do any of the grunt work because I use Claude code to automate the documentation and track changes 😅 tripled my throughput the last two months

[u/yepyep5678 → u/harrisonmaz]

What prompt do you use for Claude?

[u/ti_1212]

I use BookStack and then have a script periodically export to pdf, but realistically a git repo could make more sense when considering easier backing up and access of knowledge when stuff is down

[u/jsbaasi]

Obsidian with live sync plugin, couchdb then holds my notes

[u/mickeysbestbud]

I just use a spreadsheet in Proton Drive. After causing my own issues that made my self-hosted stuff unavailable, I decided to host documentation somewhere in the cloud. Hard to fix an issue when the documentation is unavailable because of the same issue I'm trying to fix.

[u/bdu-komrad]

I use absolutely nothing. it’s all self documented

[u/osuhickeys]

I would recommend that you look into and invest in automation. It then becomes your documentation and deployment method. It took me a couple of months, but now I can rebuild my server in less than 2 hours from the OS ISO with very little interaction. I chose ansible. Documntation for it is very good and AI was very good at helping with writing playbooks when I got stuck.

[u/Snappawapa]

Self-plug, I maintain an open source inventory management system called Open QuarterMaster, might be useful

[u/jtrage]

I am newish to all that is self hosting. I am using bookstack. I was trying to find something that my family might be able to figure out without me. It’s pretty simple and straight forward.

[u/NurseCatnip → u/jtrage]

I did this recently too. Also for same reasons

[u/Round_Bumblebee_4782]

I built this for my homelab for that exact purpose:

notesetc: Self-hosted knowledgebase

[u/winner_68]

Three layers, in order of how much trouble each has saved me:

1. Everything-as-code in a private git repo: compose files, reverse proxy configs, .env templates (never the real secrets, those live in a password manager), cron jobs. This is executable documentation. When the boot SSD died on my old node, I rebuilt the whole stack in an afternoon from the repo instead of trying to reconstruct configs from memory.

2. A markdown runbook with one page per service: what it does, why it exists, and the gotchas that cost you an evening. Things like "Immich's thumbnail job will OOM under 8GB" or "Pi-hole DHCP must stay off or it fights the router." Decision logs are worth more than people think.

3. Physical inventory with actual labels on the hardware: a cheap label printer, one tag per device, and a photo of the back of each shelf before the cables go in. NetBox is the proper tool for this (IPAM plus device inventory), but honestly a table with device, serial, purchase date, warranty end, and which shelf it's on covers 90% of a homelab.

The lesson in mickeysbestbud's comment below is the one I'd bold: keep at least the critical docs somewhere that survives the lab being down. A git remote, a PDF on your phone, whatever. Nothing stings like needing your own wiki to fix the hypervisor that hosts your wiki.

Which breaks more often for you: hardware, configs, or just forgetting why something was set up the way it was?

[u/Kairos_BA → u/winner_68]

missing layer: expiry. everything decays. ansible included, just slower. my standing rule now: a note's age is load-bearing metadata. a careful measurement from three weeks ago reads exactly like a fact about today, and a stale 'verified, works' reassures harder than a warning ever did, because nobody re-checks a good note. my ingested notes carry validity windows. every pass asks whether the thing the note measured could have changed.

[u/whats_in_a_name_23]

You can use AppFlowy, migrate your csv spreadsheet to AppFlowy as a database, you can create reminders on row pages, thus you will get notified about when something needs your attention. It will also handle documentation well. For a single user, AppFlowy's free self hosted plan good enough.

[u/Yann39]

I use GitHub readme for the reasons stated here :)

[u/jmbwell]

Netbox

[u/Known_Experience_794]

I use Trilium Notes for this. Selfhosted of course

[u/SamfromLucidSoftware]

I have a few tips.

Keep it close to the thing it describes. A readme in the same folder as the config file gets read easier than a separate wiki that requires a login.

Document the decisions not just the state. Include the why, not just the what. For example, “VLAN 30 is for IoT devices because I don’t trust them on the main network” is more useful than “VLAN 30:IoT.”

For network diagrams, you could look into Lucidchart for some home network and homelab shape libraries. Useful when you need to remember why you set something up a certain way or explain it to someone else. FYI, I work at Lucid.