NixOS’s declarative configurations basically document themsleves: add some comments and you’re good to go and can back then up to wherever whenever

A combination of Logseq (what, why, how) and KeePass for IPs and passwords (obviously)… I use the heirarchy in Keepass to show a device and then the services on it and then their configs, ie

• Hypervisor1
  • VM1
    • root user details
    • that webUI details
  • VM2 (Etc)

I used to do Visio drawings, but they were always out of date.

I just created a note in Obsidian with the Excalidraw plugin.

Jokes aside, I do keep some harder to remember stuff written down in a README.md in my repo, but mainly most things are undocumented

I build my infrastructure with the terraform, Ansible and helm charts. The code is it’s own documentation as well as comments in that code explaining why I’ve done things if it’s not obvious.

Not much, really. I do comment changes to config files and such.

I’m curious how everyone documents their core/critical configs to allow the non-technical in our homes work with it if needed. For instance if I’m on work travel and the Pi-hole goes down for whatever reason my wife wouldn’t be able to use pretty much anything online. I can remote in and fix it but that could be hours/a day or two later. Same then for the proxmox stack that everything runs on.

Along the same lines, how are folks documenting for EOL? It may not be a happy thought but we are all going to go someday, so what is your plan and how have you ensured loved ones can access/save important data?

Obsidian synced via git.

95% of my homelab lives on a single server, and everything I do is within containers. So, my documentation is just keeping all my compose files in a git repo and writing in comments when necessary. It’s fairly self-documenting, and I haven’t found the need to break out of just using containers for everything, besides a couple things like setting up mergerfs or cockpit, but that’s all plug and play nowadays with stuff like https://projectucore.io/

Of course, I don’t have any other things set up in my physical layout or network stack… but all that stuff would probably just go into an entry in my notes (obsidian/wiki.vim).

I generally just make notes in Obsidian, mostly about switch ports, VLANs, IP assignments and that kind of thing.

Also try to save snippets of commands or config edits I needed to get something obtuse working in case I need to do it again later.

Lol.

I tried since the very beginning to build everything in ansible and terraform, so everything is in the code or in its associated README files.

But apart from that I have a hodge podge of dozens of note documents in Obsidian.

The Ansible playbooks I use to deploy it are the documentation.

I had that same problem, then I saw some YouTube videos where the guy recommended using Ansible to do stuff and it’s been night and day, not only it’s reproducible so if I ever want to move a service to another machine all I have to do is move a couple of roles around and possibly copy stuff over to keep the data but also it acts as documentation, because if I ever forget something I can look at the code.

Also I decided to write the roles myself instead of relying on pre-existing ones, so there’s some logic to how my stuff gets deployed and it’s easy to extend for any new stuff I want to add.

I’ve moved to an “infrastructure as code” approach, not using any fancy tools in particular, primarily just bash shell scripts. Basically almost everything I setup or do gets documented via shell scripts, I write them as I go when I’m learning to install something new, and before I commit to something to new, I take extra care to make sure the scripts are idempotent so that when I want to do make any changes, all I need to do is add it to the appropriate script and re-run it.

The idempotent part takes some effort sometimes, but is not actually as hard as it seems, particularly if you don’t mind that it sometimes spends some wasted time doing things that have already been done, and occasionally spits out some harmless error messages because something is already done, but I also try to minimize that when I can. The consequences of doing too much by re-running are rarely serious. Yeah sometimes the scripts can break, but as long as they fail properly (set -euo pipefail) it’s usually pretty obvious how to fix it and it won’t leave too much of a mess.

Doing this has transformed my homelab from a mess of unknowable higgledy-piggledy spaghetti-services that was always teetering one small failure away from total collapse and frantic rebuilding, into something repeatable and reproducible that I can actually … wait for it … test. Just firing up a Linux ISO in a VM is all I need to test everything I’m doing in a perfect sandbox, and I can throw it away when I’m done with no regrets. Plus it makes rolling out new servers, and more importantly, decommissioning old ones, a breeze, you know exactly what’s on them and how it was set up, because it was all in your scripts. Combined with good data backups (which are also set up in the scripts) and restores (which I also test with scripts) it really takes the drama and stress out of migrations and even hardware failures.

Yeah there are probably easier ways to accomplish what I’m doing using some of the technologies like terraform, ansible and nix/flake that people have mentioned, and I’ve dabbled with those, but for me, the shell script approach strikes a nice balance of not just documenting but also learning the process myself so that I understand enough of what it’s doing to effectively debug it when something goes wrong, and it works on almost everything and in most cases requires no installation or setup. Bash is everywhere. I even have an infrastructure-as-code setup for my Steam Deck to install stuff and get it set up the way I want.