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.
- 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 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.
- what you use for your documentation
Markdown files
- how you organize it
What ?
- what information you include
The commands that worked and the stuff that didn’t work and the links to the source of information
- how you work documentation into your changes
I write as I go. I keep it as part of a git repository when relevant
Had to scroll down this far just to get to markdown files. Although I write with a bit of a delay. Once I get something working. Then I document what worked and what didn’t. Alternative methods and issues I had with the alternatives.
That’s the neat part, I don’t.
The theory is I use Docmost. The reality is I don’t, and I hope my backups are solid.
I have an obsidian document where I write changes I want to do in the future that I never look at; does that count?
I just found my todo list and half of it is irrelevant and half of it is done.
I even had a work todo list for my old job lol.
Ouh! I have a checklist of things I need to add/update too, that I never check. Maybe we could mutualize! ;)
“I don’t need to, I have it stored all in my head.”
Famous last words.
That’s the devil talking Bobby Boucher.
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
“I can remember that” is my cue to write it down, because I won’t.
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).
Yep. It feels good knowing I can take a few hundred KB of text files and rebuild my whole system.
That’s the direction I’m moving my lab in. Plus a bit of supplemental markdown to keep track of which guides I’m referencing (and which parts can be ignored because I baked it into the terrafom). It’s really nice to know that as long as I tweak the terraform for changes, I don’t have to worry about forgetting what I changed.
This is the way
Without really knowing much about it, I just always figured it was overkill for me. Plus I don’t know that I’d even consider myself much more of a beginner with Docker. But you all are making me consider looking into it.
I get that - it’s difficult to see the point in it until you’ve gone along without it. Especially as a beginner since you don’t have a strong sense of what problems you will encounter and how these tools solve those problems.
At some point the learning curve for IaaC becomes worth the investment. I actually pushed off learning k8s myself for some time because it was “too complicated” and docker-compose worked just fine for me. And now that I’ve spent time learning it I converted over very quickly and wouldn’t go back… It’s much easier to maintain, monitor and setup new services now.
Depending on your environment something like Ansible might be a good place to start. You can begin even with just a simple playbook that does an “apt update && apt upgrade” on all your systems. And then start using it to push out standard configurations, install software, create users, etc. The benefit pays off in time. For example - recently (yesterday) I was able to install Apache Alloy on a half-dozen systems trivially because I have a set of Ansible scripts that manage my systems. Literally took 10 mins. All servers have the app installed, running, and using the same configuration. And I can modify that configuration across all those systems just as easily. It’s very powerful and reduces “drift” where some systems are configured incorrectly and over time you forget “which one the correct one?” For me the “correct one” is the one in source control.
I used to try and do it all in obsidian but I’d forget a lot. Now I use nix and it’s all done for me basically
Yeah, I’m currently using Wiki.js. I will definitely check out how you’ve got things organized. It looks really good!
BTW, this gent’s wiki is worth a bookmark. Stumbled on it before I knew the originator.
Thanks you, it means a lot. Just to be clear for whomever didn’t go there: there is zero monetization, no ads, no profiling.
At work, since I’m the sole IT, I’ve been putting everything into MkDocs and it’s been working out great for the team. Only complaint is that I can’t seem to figure out how to update anything without just relaunching the Docker container every time. They mention that you can live reload, but not how.
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.
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.
It depends on what it is. I do not have a singular documentation-platform or wiki for those things. I’m more of the keep the docs where the code is guy. I also try to keep complexity to a minimum.
All my linux server setups are done with
ansible.ansibleitself is pretty self-documenting, as you more or less declare the desired outcome in YAML form andansibledoes the rest. This way, I do not need to remember it, but it’s easier to understand when looking it up again.Most of my projects have a
gitrepository, so most of what I need to know or do is documented- in a
README.md - as pipeline-instructions inside
.gitlab-ci.yml
This way, I was able to reduce complexity and unify my homelab projects.
My current homelab-state is:
- most projects are now
docker-based - most projects have a GitLab CI for automated updating to newer versions
- the CI itself is a project and all my CI-docker-based deploys use this unified pipeline-project
- most projects can be tested locally before rolling out new versions to my VMs
- some projects have a
productionand astagingserver to test - those which cannot be dockerized or turned into a CI are tools and don’t need that (e.g.
ansibleplaybooks or my GitLab CI)
On what to include, I always try to think: Will I still be able to understand this without documentation if I forget about the project for 6 months and need to make a change then? If you can’t be sure, put it in writing.
If it’s just a small thing regarding not the project itself or the functionality or setup itself but rather something like I had to use this strange code-block here because of XXX, I’ll just put a comment next to the code-line or code-block in question. These comments mostly also include a link to a bug-report if I found one, so i can later check and see if it’s been fixed already.
- in a
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.
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.
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.
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!
