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 register to comment.
I just think I do that, but absolutely don’t.
write-only memory.
no read, only write!
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 read the title and this was literally the first thing that popped in my head
I’m here to serve.
Ansible.
Infrastructure as code is the best documentation.
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.
README.mdREADME_I_AAM_VERY_IMPORTANT.md
The moment you think you might possibly need documentation is the moment you should seriously consider using Ansible or similar to orchestra things. Sure, it’s annoying for a single server, but it is the best form of documentation there is.
Why do you have to be like that? Drop the innocent questions and just come right out and call me a piece of shit directly.
Trust me, this is all about me being incompetent.
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.
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.
NixOS because it’s declarative kind of does it all for me.
The .nix files serve as their own documentation and if I need to do anything outside them I add a comment to the .nix file.
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!
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.
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 use Guix
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.
