Reading earlier comments in this community made me consider documenting the workings of my homelab to some extent, ie. docker configuration, credentials, ports and links of my services. I’ve tried to make it consistent and organised but it still feels half baked and insufficient. Everyone suggests documenting everything you do in your homelab but don’t state how. Since I’ve hardly had experience running my own server, I would really appreciate observing the blueprint of some other fellow selfhoster for copying or taking inspiration from rather than considering documentation to be ‘left as an exercise for the reader’.
Edit: I already have a note-taking solution with me. What I wish to ask is to know what needs to be documented and what the structure of the documentation should be to accommodate the information.
You must log in or # to comment.
Ansible is my config and documentation in one.
It’s reproducible, idempotent and I don’t need anything else.
I write all code myself, that makes it even easier to read.
I agree with the advice that says “Document your setup such that you could recreate it from your notes from scratch” but I’d take it another step further — consider that someone may have to do some work on your system when you are unable or unavailable. The kind of thing you’d keep with your will, or power of attorney. Just a suggestion.
…and to my family I bequeath my entire collection of Linux iso’s
You jest but if I left my wife my Home Assistant setup undocumented she would pee on my grave.
LOL, well I’m single tho I’ve known my ladyfriend for over 40 years. I offered to set up a server at her house, and connect the two, but she has no interest rifling through all my lab for anything of interest in the case of my passing.
I’m happily married with a kid, and we recently went through the estate planning process. When I brought up IP stuff and digital properties, their advice was pretty much “Hmm… you should pick someone who understands what you’re talking about, get their approval in advance, and then add them as your legacy contacts and document the heck out of everything”. Realistically nobody is going to want my GitHub stuff or anything like that, but I would like my kid to have access to most* of my files after I pass. I am of course excluding the kind of content that “real friends” delete while your body is still warm.
It’d be nice to donate all my equipment to some kid who is very interested. That would be something I’d be interested in.
My documented plan includes that kind of donation for my amateur radio equipment, but I’m going to let my survivors handle the home lab.
This is what I like about git ops and infra/config as Code personally.
Ideally everything is an a tofu/ansible/helm chart and git lab pipeline/Fleet job. I add comments for anything that I had to learn to make work to those files. Follow good commit hygenine (most of the time). And bam I can almost a year later half asleep stumble back into a thing I did.
Document everything as if it were a step by step tutorial you will give to someone so that they can duplicate your deployment without any prior knowledge. I’ll even include urls to sites I consulted with to achieve production deployment.
ETA: I absolutely care nothing about points. Up voting and down voting used to be a way to weed out bad info. So it always leaves me wondering 'Did I give erroneous advice? What was the reason for the down vote? I mean, if you down voted and said ‘I down voted you because I hate your guts’, I can deal with that.
I believe it is traditional to do so written in blood in the style of an apocalypse log, dealer’s choice for who’s blood. Make sure it’s disjointed and nearly incomprehensible, but that everything is there.
Bonus points if you print the config files and write your documentation on them after stapling them to the walls
(Bookmarked for when I have the mental capacity to …)
Do y’all also document backup/restore procedures?
How often do you test it?Frankly, with my screwed up brain, I document everything. I can turn around twice in my lab and my brain will flat line. When I first started, I would always tell myself that I’d remember stuff. Not anymore.
I created a script for Linux that automatically backs up to a NAS drive, once every two weeks, as a complete image, and I keep 5 on deck. Testing usually happens once every 3 months or so. I also have Duplicati backups that are stored offsite on my VPS.
If you can’t remember what something does, cut it off. If you know remember it, put it back on the document it.
I have a repo for the infra files (compose files and terraform files just for playing). I store the docs in the same repo in MD files. As for the secrets, I’m using docker swarm, so I can store the needed passwords there. otherwise Vaulwarden is my go to, <ad> self hosted, lightweight password manager, compatible with bitwarden clients </ad> I’m a little paranoid if the note-service got db corruptions, I might loose too much info, so git is the way (personal opinion).
edit: add the related MD file next to the compose file, one folder per service, the source and the doc will be coupled in one place.
I created something similar to this. It got a lot of love during interviews later down the line. https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Fi.redd.it%2Fvmd34mabi4r91.jpg&f=1&ipt=2dde77fd04d48156bc514ad4b1f090c8473f4e666ead0e16906eeed55a79aca6
Dude that is a respectable lab you have there! Much envy
That is a behemoth of a homelab you have set up there. My jaw would’ve dropped out if it could.
I have a simple pile of Markdown files that I edit with Obsidian. I like the simple text file format because it keeps my documentation forwards-compatible. I use OpenWRT at the heart of my network, so I keep I right there in root’s home. Every long while I back it up to my general Documents which is then synced between my high-storage devices with SyncThing.
Thanks for your response. I already have Joplin synced with my server as a solution for my documentation. However I meant to ask how you structure your documentation, know what and how to mention, and organise it for future reference.
Don’t know if this helps since dokuwiki lets me link pages, but I have a main page where I just do a one paragraph description of every big thing in use.
each page has:
- an in depth description,
- how it’s set up,
- a list of features i use,
- how it connects to other services,
- and a miscellaneous for everything else
I’ll also add any notes in the misc section in case I need to reference them later. If a service is mentioned, I’ll create a page for it and link to it every time I mention it. That way nothing is more than a few clicks away and the documentation grows naturally as long as you don’t have any monolithic application. Example: (main -> Docker -> Project_Ozone_2 -> custom configurations Or main -> Joomla -> wysiwyg ->JCE Editor)
I also had a professor tell me to just write everything down first and then focus on formatting to find what kind of structure suits your needs best.
That’s the neat part, I don’t!
I have a docker-compose file, which is somewhat self-documenting, especially since I give everything descriptive names. Creds go in bitwarden anyway.
But then, my environment isn’t that complex, and I don’t have anything so custom that I need notes to replicate it.
I felt like we were brothers for the entire first sentence, then you had to ruin it.
I write homelab docs mostly for user guidance like onboarding, login, and service-specific stuff. This helps me better design for people by putting myself in their shoes, and should act as a reference document for any member to come back to.
Previously I built an Mkdocs-Material website with a nice subdomain for it, but since the project went on maintenance mode, I’m gonna migrate all docs back to a Forgejo wiki since it’s just Markdown anyways. I also run an issue tracker there, to manage the homelab’s roadmaps and features since it’s still evolving.
I find this approach benefiting compared to just documenting code. I’m not an IaC person yet, but I hope when I am, the playbooks should describe themselves for the nitty-gritty stuff anyways. I do write some infra notes for myself and perhaps to onboard maintainers, but most homelab developments happen in the issue tracker itself. The rest I try to keep it simple enough for an individual to understand
I’ve been documenting my homelab experiments, set ups, configurations, how-to’s, etc in both Trilium and Silverbullet. I use Silverbullet more as a wiki and Trilium for journal style notes. I just got into self hosting earlier this year, so I’m by no means an expert or authority on any of this.
So my Silverbullet set up contains most of my documentation on how to get things set up. I have sections for specific components of the homelab (Proxmox general set up, general networking, specific how tos for getting various VMs and LXCs set up for specific applications, specific how tos on getting docker stacks up and running, etc.)
I didn’t document shit the first two times I set up and restarted my entire homelab, but by the third time I learned. And from there I basically just wrote down what I did to get things running properly, and then reviewed the notes afterword to make sure I understood what I wrote. This is never a perfect process, so in the following attempts of resetting my server, I’ve updated sections or made things more clear so that when I’m coming at this 8 months later I can follow my guide fully and be up and running.
Some of my notes are just copy pasted directly from tutorials I originally followed to get things set up. This way I just have an easily accessible local copy.
When I troubleshoot something, I document the steps I take in Trilium using the journal feature, so I can easily track the times and dates of when I did what. This has helped me out immensely because I forget what the fuck I did the week before all the time.
I learned all this through trial and error. You’ll figure out what needs to be documented as you go along, so don’t get too caught up trying to make sure you have a perfect documentation plan in place before deploying anything.
I’m one of those people who never really took notes on things or wrote shit down for most my life. Mostly because I’ve been doing shit that doesn’t require extensive documentation, so it was a big learning curve.
Edit: Forgot to mention that I also have a physical paper journal that I’ve scrawled various notes in. I found it easier to take quick notes on paper while I’m in the middle of working on something, then I transcribe those notes digitally in either Silverbullet or trilium.
I have half a mind to make a homepage where I have everything documented in some kind of blog type structure. Maybe VitePress. Makes it searchable and everything. 👌
Libreoffice calc/MS Excel. Old school tracking and extremly flexible for documentation. I have been doing this for the last decade, both at home and at my workplace. My team loves it, tho YMMV.
