Hello, how do you document your home lab? Whether it’s a small server or a big one with firewall and more nodes. I have a small pc with Proxmox and there I have a VM with OpnSense. After I’ve entered my VPN as a interface in OpenSense, I noticed that I slowly lose the overview with the different rules that I have built in my firewall. And I know that my setup is relatively easy in comparison to others here in this community. I want to have a quick Overview at the various VMs, like the Lxc container, Docker containers that I have in this and the IP addresses that I have assigned to them. I search for a simple an intuitiv way for beginners.
Obsidian synced via git.
I just created a note in Obsidian with the Excalidraw plugin.
I use obsidian and ezcalidraw also, I didn’t realize we can put one in the other
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)
- VM1
I used to do Visio drawings, but they were always out of date.
- Hypervisor1
I download the YouTube tutorials I followed, upload them to my UAT Jellyfin server, and then when my server is having issues I can’t get to the videos!
A flawless system really
It’s really a wild growth over the years. My current approach is twofold. Netbox to manage devices/VMs and associated info with service deployments using Ansible. You can use the info from Netbox as an Ansible inventory directly.
Previously I tried network diagrams (too low detail) and spreadsheets (terrible to modify) to document machines. And for serviced I’d have an install page on my wiki (apologies, the codeblocks are somewhat broken atm)
I run Netbox for documentation only. But your approach is what I actually wanted to do, if I just had plenty of time.
I use netbox too - and if you’re careful about it, you can actually use terraform to create the netbox details. I use one manifest file to handle deployment to Proxmox, set up DNS in PowerDNS, and create the relevant netbox entries.
The way you go about it on your wiki, is almost the same process/format, tho not as fancy . I’ll even throw in a couple links to tuts I found useful for that particular segment in the notes.
I just try to make everything as self documented as possible. Eg. no stray scripts, everything is either implemented in other software (eg. my main wireguard peer in systemd-networkd, without any non-obvious external dependencies) or tracked as a part of an arch pkg with a simple PKGBUILD. I usually either have very simple nets (eg. my VPN’s net only consists of four peers, in the order main - secondary - laptop - phone) or leave it to DHCP and SLAAC. I try to avoid using ports for local servers as much as possible and use unix sockets. Stuff like LVM/Luks pretty much documents itself.
Here: https://wiki.gardiol.org/
Based on Dokuwiki and my own experience. Mostly started to track what and why I do stuff, and published because I truly believe in a free internet.
I started to put it all in my selfhosted bookstack and that works well for me. I also automated a good part of my setup with Ansible, so I can just check how the Playbook did things if I forgot.
Trillium notes
But what about the documentation to host the note server?
I run nixos, so my entire homelab servers setup is stored in my github. I can rebuild a server and restore backups from that (and sops keys). I significantly prefer this to having to remember and note a huge bunch of things to setup a computer - this way a rebuild on new oc is only a few hours tops
If it need documentation means things are over the line when comes to complexity and I should scale down / simplify. :)
Complexity and over-engineering are a serious problem, I really try to keep it as simple as possible so I don’t have to waste time managing it, dealing with updates and potential security issues. Simple code/infrastructure breaks less and has less potential insecure points.
There’s no such thing as too simple to document. If you spent time learning how to install it, you’ll need to relearn it if you want to make any changes in the future. If you don’t leave at least some notes as to why you make some decisions, you’ll have to redo your work.
It’s also good to make notes on every configuration setting. That forces you to understand why the settings are the way they are. If you have a -f in a docker config and you don’t have any understanding of why that’s there, you might not know if it’s a development flag for getting things set up, or if it’s a critical part of your environment.
It is especially important if any of those parts are exposed to the public Internet. You might have a config set to allow unauthenticated connections and not know it.
i mean charitably you could say that your code / architecture should be self documenting, versus having to rely on READMEs / wikis
in effect, if you change the code you are by definition also changing the documentation, since the file names/function names/hierarchy is clear and unambiguous
It’s also good to make notes on every configuration setting.
I do save my settings for the various programs in a git repository…
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’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?
It’s not just for my home server but for EOL or other issues I used bitwarden emergency access options for passwords. Of anything happens to me my wife can request access to my vault and if I don’t deny it in a certain timeframe she will have full access to it.
I did that after my brother in law got in an accident and fell into a coma. I’m very grateful he had all his password saved in chrome on his unlocked laptop because if not it would have made the period insanely more difficult for my sister.
Simple things like paying the bills would I been insanely more difficult and stressful and you don’t need extra stress in this period.
My solution is other people in the house don’t rely on anything in my setup, other than the router which runs some basic telemetry and fraud/phishing domain blocking but that’s all.
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 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.
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.
