Like soup-to-nuts. I know I need to document what I’m doing and I’ve started several times, but then I never go back and make updates. I don’t know if it’s just the ADHD or if I’m just going about it or thinking about it in the wrong way.
So I’m curious about:
- what you use for your documentation
- how you organize it
- what information you include
- how you work documentation into your changes/tinkering flow
Edit: Dang, folks! You all have given me a lot to read through, think about, and explore. Thank you!
You must log in or # to comment.
Man I’m as basic as it comes. I have a .txt file that I update with today’s date and write what I’m working on. I try to write as much as needed on what I’m working on. I write commands down and save links to reading material.
It’s not the best but it’s better than nothing.
When I set something up I write all the steps I’m doing in obsidian as I do it. The pages get tagged so they’re searchable in the future.
I use Guix
I’m actually in the middle of rebuilding my entire setup right now and one of my major goals is to actually document my processes this time.
I use Obsidian which is a Markdown editor and I have a couple plugins alongside that for QoL stuff and extra features.
I document processes, problems and fixes I encounter, list of active services alongside where/how to access them, and plans for future additions/changes.
As far as working documentation into your flow, realistically that is just a matter of discipline. It is explicitly up to you to stay on top of documentation.
Hope that helps, and good luck with your endeavor! 😁
draw.io in my nextcloud
And leantime to keep track of what I want to do with notes and such
And a mess of notes in Joplin.
I’m surprised no one else has answered mediawiki. Love my mediawiki instance.
README.mdREADME_I_AAM_VERY_IMPORTANT.md
I run Adguard Home containers (the primary auto-syncs to the secondary) and use redirect filters to assign hostnames to each of my containers. I have a “services” folder of bookmarks for each container host so I don’t have to remember each service’s port number. I use KeePassXC to track all my passwords and certificates so authentication is a breeze (someday I’ll get around to setting up an SSO solution). I also keep a .txt file with my basic network info that doesn’t always translate well to dns hostname redirects in adguard. I occassionally remember to update my hosts listed in the file. My individual config files aren’t backed up beyond my automated container backups, but so far none of my services have been that complicated I couldn’t just rebuild from scratch.
It’s not perfect, but combined with my automated backups I have barely enough to rebuild if/when my hardware fails.
I have a bare minimum of documentation as markdown files which I take care to keep in an accessible lovation, aka not on my server.
If my server does ever go down, I might really want to access the (admittedly limited) documentation for it
I read the title and this was literally the first thing that popped in my head
I just think I do that, but absolutely don’t.
Yeah I also use config-as-code along with wiki but I used to remember things 10 years ago when the setup was simpler and the brain was newer. 😅
I use Obsidian with a folder for hardware and a folder for software, then an entry for each device or service. I’ve been pretty good about maintaining cross-links.
I kind of wish I used Docker Compose more, but I haven’t run into a situation where it’s been a problem yet.It is hard, if even possible, to keep documentation up-to-date. Better use a configuration management system (salt, ansible etc.) for your servers. Yes, you need to learn how to use it. Yes, it will take a longer time to make changes in your configuration. But as a result you’ll have a self-documented configuration-as-a-code that will allow you to scale your setup as you need. Reproducing something won’t require reading your notes, remembering your actions etc.
But as a result you’ll have a self-documented configuration-as-a-code that will allow you to scale your setup as you need. Reproducing something won’t require reading your notes, remembering your actions etc.
Until you realise that
- you don’t really need to scale a homelab that much
- if something breaks, you just want to quickly fix it manually because “doing the Ansible” is more of a pain
- now idempotency and documentation-as-code is out of the window. ;)
(I’m being tongue-in-cheek here. I don’t doubt this may work for you, but it takes much more discipline than I have.)
you don’t really need to scale a homelab that much
Maybe. But you never know this beforehand.
if something breaks, you just want to quickly fix it manually because “doing the Ansible” is more of a pain
In most cases you just need to replay a playbook for quick fix. But I agree that the proper fix will likely take a longer time (while downtime is much shorter).
now idempotency and documentation-as-code is out of the window.
Let @BruisedMoose@piefed.social decide.
P. S. I don’t like Ansible, other tools can be easier to use. But I don’t want to recommend something concrete.
Yeah as someone who does both ansible is for repeatable multi-system commands like telling everything to update or configuring a local agent on every machine at once.
Day job: oneScrote and fucking ansible
Night job: some wiki for the architecture, but just config management for the config detail : we run the docs and it’s done. Thankfully not fucking ansible; because in any environment where there are options, it’s not fucking ansible.
All my computers (including servers) share the same NixOS Flake. So my documentation consists of:
- The Nix code itself
- The commit messages for each change I make
- Inline comments in the Nix code
- A few readme.md files to explain the contents of certain directories
err . i don’t really. well I do a bit. the obvious one is config-as-documentation: docker compose mainly. I’m in the middle from migrating from storing them in portainer’s internal store to using git (and dockhand), which should improve their role as documentation with the addition of vcs.
in addition I have a handful of markdown notes in my obsidian vault to track a few things. there’s some general terminal stuff command references, which aren’t strictly for the server. i have a list off all my hard drives, including their SN,PN,Partition UUID and label (this is their partition/volume label as well an actual physical label on them. It makes moving between operations on my host machine, omv VM and physical drive easy. its a maddening combination of using three or more command ouputs to map a drive between whatever info is available in proxmox, a vm or physically otherwise!
