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.
That’s the neat part, I don’t.
“I don’t need to, I have it stored all in my head.”
Famous last words.
“I can remember that” is my cue to write it down, because I won’t.
It’s not like anyone needs to support it when I’m gone.
Documentation is for onboarding other people. Why on earth would I need to onboard other people to something self-hosted?
Sometimes future me has the memory of a goldfish, and I fear that, for future me, the online sources that guided me before won’t be there for me anymore
The theory is I use Docmost. The reality is I don’t, and I hope my backups are solid.
I just think I do that, but absolutely don’t.
write-only memory.
no read, only write!
The fun thing about infrastructure as code is that the terraform, ansible and k8s manifests are documentation.
I only really need to document some bootstrap things in case of emergency and maybe some “architectural” things. I use joplin for that (and many other things).
I just create a README.md file wherever I setup services with docker compose which keeps top level docs so I know how and why certain things work.
Other than that, if comments are supported inside configuration files, also document stuff in there too.
That’s been good enough for me.
Bookstack in a docker container. You can export pages with revision numbers and dates. I print out the emergency stuff and keep it in a binder. https://www.bookstackapp.com/ I’ve been using it at work for like a decade now. No apps or anything though, just a decent web interface.
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.
Acronyms, initialisms, abbreviations, contractions, and other phrases which expand to something larger, that I’ve seen in this thread:
Fewer Letters More Letters Git Popular version control system, primarily for code IP Internet Protocol SSH Secure Shell for remote terminal access SSO Single Sign-On VPN Virtual Private Network ZFS Solaris/Linux filesystem focusing on data integrity k8s Kubernetes container management package
7 acronyms in this thread; the most compressed thread commented on today has 17 acronyms.
[Thread #207 for this comm, first seen 2nd Apr 2026, 12:40] [FAQ] [Full list] [Contact] [Source code]
Ansible.
Infrastructure as code is the best documentation.
ADHD: functional notes in abbreviated version on fat strips of painter’s tape on server case or shelf. Passwords go on page dedicated to that server or service in a little black notebook, then eventually in a password manager.
Readme file if my brain lets me, usually 3 months later after hyperfocus on troubleshooting.
Honestly, the tape idea is one of the most practical ones in the thread!
Notesnook notebook with whatever info I need to be able to administrate the system. e.g. what different ports are used for and why the firewall policies are what they are, sometimes write-ups after a troubleshooting session, etc.
The Notesnook instance is self-hosted too, but if the server goes down, the notebook will still be available locally.
A great question. First of all, all of my services run with docker compose and use volumes for their config storage which get backed up regularly. Then I just use markdown files organized by having a separate file for each service. Basically anything I would need to reproduce my setup on a new machine is what I try to write down. All the docs and compose yaml files are versioned in git. I usually realize I left out info later on and add it as it occurs to me, typically if I have to set up the services on a new machine. This all applies to any software that needs more than a little config, not just apps hosted for the purpose of other machines using them. It’s a very imperfect process, but it’s a ton better than what I used to do which was think “eh I’ll remember how it’s setup”. I rarely would remember all the key details.
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
In only have one server with NixOS. I don’t use flakes, just plain nix files. It still works great as documentation.
The only thing it is missing is why something is setup in a certain way.
Do you use git? That basically forces you to do some documentation as you go. Multi-line commit messages are often helpful too. (When I first learned git, I only committed using
git commit -mwhich is a bit restrictive in terms of how much you can fit in commit messages)Where do you push to? I have some secrets in my nix files (passwords). While I will get around to move them away from my nix files soonTM, I don’t want to push those to a public repo.
I currently push to a private GitHub repository (planning on moving to a self-hosted Forgejo instance soon).
Although making my nix configuration public would be safe anyway since I use sops-nix which encrypts all my passwords in the repo using a key derived from my SSH key. During nixos-rebuild it decrypts them and puts them each in their own text file at
/run/secrets, with permissions set so you need sudo to view them. (The permissions can be tweaked as needed)It was a pain in the neck to get started with initially (like NixOS itself), but it was very much worth it. (Basically a necessity since putting secrets even in a private repo is considered bad practice)
I was considering putting the secrets somewhere not in /etc/nixos/ and just point to them. Then I could push my nix files without worry. My plan was to use my other server as a remote with just git and ssh, but that server is not responding and is ~6 by car away from me (I don’t own a car). It will be traveling here soon so I can configure it and send it back though.
Thanks for the link to sops-nix, I will check it out. As you said, NixOS is great when you have it running. I can’t see myself going back to debian now.
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.
I don’t like Ansible, other tools can be easier to use. But I don’t want to recommend something concrete.
Which ones do you like to work with? (Even though it’s not a recommendation ;) I’ve only dabbled in Ansible so far and found it overkill for most of the things I do, but maybe one of yours isn’t?
I didn’t try many of them. I use Ansible for my job, but sometimes I hate it. I would try Terraform/OpenTofu or Salt if I were looking for alternative.
