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.
It’s not like anyone needs to support it when I’m gone.
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]
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 @[email protected] 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.
