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.
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 just rewriting everything in Ansible and I think is worth the effort, it’s self-documented and as an added bonus I won’t have to keep backups of the whole VMs, just the ZFS pool with the data/databases.
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
Use declarative systems and software, where the configurations files themselves are the documentation. For example, I use Guix and Podman. The entire OS is described in a Scheme file and all the services are described in a YAML file. I just need those two files to get an overview of the entire setup.
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.
README.mdREADME_I_AAM_VERY_IMPORTANT.md
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!
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?
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.
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 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.
what you use for your documentation
Hugo (markdown) files that i host on my internal server.
how you organize it
I use basic directory structure. Top level directories are like “dev”, “home”, “general”. Self hosting is a dev/ subdir.
what information you include
Depends on how familiar i am with it and how often I’ll be referencing it. Something i know well or access often will be more high level. Things like an annual process i have documented in more detail
how you work documentation into your changes/tinkering flow
My site has an “edit this page” feature which i use to open my IDE and make the change as I’m doing things. Sometimes I’ll be lazy and just add in what i did this time and then let future me reconcile the differences 🙃
- I use Obsidian
- Usually, what I do is write the documentation as I am engaged with the project at hand. Then clean everything up, and transfer to Obsidian.
- I include everything. I don’t leave anything for my mind to wonder about. If I didn’t write it down, it didn’t happen.
- Date any addenda or changes (4-2-26: Firewall rules review)
I’m surprised no one else has answered mediawiki. Love my mediawiki instance.
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.
