Greetings Lemmings,
I realize that self-hosting for many is just a hobby. Something they do for fun. And the topic of today is usually a “not-so-fun” part of the IT industry.
Jump Scare Warning
Documentation
I have for so long just let my lab grow organically. And months down the road an issue pops up with a service, and I have no idea how I set something up, and may not have documented it. Whether that be comments inside of configuration files, or via other means.
I have gotten marginally better at documenting within the config files or code that I am writing. However, I don’t want just that as an option. So I spun myself up a Bookstack container.
I am slowly going through and creating what would amount to a full blown wiki for my setup. Doubly I can use this as part of my resume.
So I ask of you; what ways do you prefer to document? How do you keep yourself honest, and actually stick to it.
Edit: I created bash scripts that are run by a systemd service and timer. At least for my docker box.
I know that feeling. Broke something in my reverse proxy and setting it back up again was painful. I know that certain things had needed special treatment, but how/what/where? Lost 🥲 Going to migrate to infrastructure as code for my documentation now
I have a low tech solution. I use this https://github.com/gamosoft/NoteDiscovery
Every time a thought comes to my mind, I create a new document and add a tag to it. I come back to it from time to time.
just make random files with notes and then grep, the most efficient approach for crazy chaotic homelab imho lol
some day llms will be able to parse your homelab notesI just break things enough times until I internalize the knowledge into my soul.
Kidding aside, I do wish I was more disciplined about documentation.
It could have really helped me earlier in the week in fact. I figured out something really clever a couple of months ago, promptly wiped the computer. And now I can’t recreate it. I’ve come up with a halfway solution, but it’s not as elegant as it used to be.
To be honest with you, this is a really good use case for a large language model - self hosted or other wise. You know Karpathy’s LLM-wiki method?
I dont but I am interestes in learning something new
Here’s the OG
https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
And the clanker write up https://blog.starmorph.com/blog/karpathy-llm-wiki-knowledge-base-guide
Thank you!
Hope it helps!
Terraform and Ansible. LLMs make Infra as code easy, and the best part is they can output beautiful Markdown and HTML documentation (use a CDN for the CSS).
I used to have a set of notes (in a text file) with commands and links to install everything I was running. But it wasn’t bulletproof. After updating my hardware and having to redo everything from those notes, which took a whole weekend, I decided to look for a better way.
Now everything in my homelab is deployed with Ansible. So I don’t have documentation per se, but its kind of self-documented. If my server was fully wiped tomorrow I could reinstall everything in minutes with one command.
I am taking precautions to have my setup easily deployable no matter the hardware. The only real documentation becomes mountpoints and such for external storage.
For DNS and Reverse Proxy entries, I have those automated. Any time I spin up a new docker container, that information is deployed with labels. Also entries into my homepage.
The .env files contain any variable I would want to store to make my setup portable, shareable and not have to worry about leaking any of my information. Not that it would be end of the world considering nothing really leaves my network unless it is through my VPN.
Traditionally I open a README.md in the dir the application lives in after I configure something I will open my browser history, and dump every link I clicked into the file.
I then copy paste a choice selection of my shell history into the file.
This is the bare minimum. It’s easy to do, takes like 5 minutes, and you will be happy to have it in 8 months. I would make the argument that anyone who tells you to do anything else can suck it. Do the readme first, any “better” documentation second.
Getting Into the habit of doing this matters more than a good documentation system. You will be lazy and try to get around to documenting something later. Don’t let it be later. Shitty link dumps are still gold mines for your future self
I am of that camp, lazy, when it comes to documentation. I have lucked out, as of now after years most if not all of what I need setup has been kept in the ol noggin. But I am building out documentation as we speak. Slowly but surely.
I do like the README.md approach.
