I’d like to start doing a better job of tracking the changes I made to my homelab environment. Hardware, software, network, etc. I’m just not sure what path I want to take and was hoping to get some recommendations. So far the thoughts I have are:
- A change history sub-section of my wiki. (I’m not a fan of this idea.)
- A ticketing system of some sort. (I tried this one and it was too heavy. I’d need to find a simple solution.)
- A nextcloud task list.
- Self-host a gitlab instance, make a project for changes and track with issues. Move what stuff I have in github to this instance and kill my github projects. (It’s all private stuff.)
I know that several of you are going to say “config as code” and I get it. But I’m not there yet and I want to track the changes I’m making today.
Thanks
Just my two cents but if you decide to go for the self hosted GitLab approach I think Forgejo might be a better fit. It’s not as resource intensive as GitLab is but has all of the essential features you’d need from a forge.
My needs are pretty simple. I’ll take a look. Thanks.
Ultimately, do whatever you think you’ll be able to keep up with.
The best documentation system is useless if you keep putting it off because it’s too much work.You are 100% correct. I’m on the quest to find the method that resonates with me that I’ll keep up with.
It can be in git even if you’re not doing ‘config as code’ or ‘infrastructure as code’ yet/ever.
Even just a text file with notes in markdown is better than nothing. Can usually be rendered, tracked, versionned.
You can also add some relevant files as needed too.Like, even if your stuff isn’t fully automated CI/CD magic, a copy of that one important file you just modified can be added as necessary.
It can be in git even if you’re not doing ‘config as code’ or ‘infrastructure as code’ yet/ever.
I have some of this. I have an ansible playbook I use to do initial vm/lxc setup and I’ve built out a number of roles. But none of my systems are to a point were I could just delete the vm, spin a new one up, point ansible at it, and pickup where I left off.
The one thing I have that probably closest to this is my internal BIND zones, which double as my IPAM. I’ve been fairly diligent about committing changes and documenting what the change was.
I try to keep things simple and just use Markdown files for everything. I have a doc for each physical device, and another doc for each service/container running on the LAN.
I generally track hardware specs, upgrade paths, and software changelogs/todos as unsorted lists within these docs. It’s super portable and easily synced across devices via Syncthing.
My recommendation would be to use Logseq.
It’s similar to Obsidian (“Second Brain”/ PKM), but with the journal function as backbone.
It relies heavily on crosslinking, is markdown-based, very efficient and a joy to use once you “got” it, and supports a hell lot of features, including TODO, plugins, a knowledge network (“graph view”) and much more.
I use it for everything (external brain) and pretty much never loved a piece of software this much!
It sounds like it is THE tool you’re searching for!+1 for Logseq
I’ll definitely take a look.
I’ve started using Obsidian with a kanban plugin, though any sufficient kanban style solution would work. I have a to-do column (aka backlog), an in-progress column, and a finished column. I add notes to the cards about what I did and I never delete stuff from the finished column so I can review if I need to re-open or re-do a task in the future.
Best thing i did was creating a git repository just for my local environment and set up.
Granted I did switch over to kubernetes and helm, so that was good. Kick start where everything is laid out and simply YAML files, but even more important than that was setting up readme files for all my major systems.
I want to say it’s now hundreds of times. I’ve gone back and reread those read me files, the random fixes I had to come across, common error codes that I needed to fix, setting up new boxes, the list goes on. On. Having one central place where I can edit and update those readmes has been a godsend. Plus I run gitea so it then formats those in a nice way for me automatically.
Not to mention the dozens of scripts and random snippets of code I’ve needed to save to help me run my local lab.
I do have a couple github repos for various things (ansible, scripts, dns). My plan for general documentation is the wiki. I’ve started the work on that but it’s far from complete (those get saved in markdown and synced to github). Maybe the simplest solution is the one I’m avoiding. Just putting it all in a readme/changelog.
I would encourage you not to split things up too finely. A single repo for your environment would allow you to see all related changes with git. E.g. if you set up a new VM it might need a playbook to set something up, a script to automate a task, and a DNS entry. With a well put together commit message explaining why you’re making those changes there’s not much need for external documentation.
Maybe if you want some more info organised in a wiki, point to the initial commit where you introduced some set up. That way you can see how something was structured. Or if you have a issue tracker you can comment with research on something and then close the issue when you commit a resolution.
Try not to have info spread out too much or maintaining all the pieces will become a chore. Make it simple and easy to keep up.
Try not to have info spread out too much or maintaining all the pieces will become a chore. Make it simple and easy to keep up.
I think you’re right on this point. I have a tendency to over-complicate things and that leads to them getting scrapped or neglected.
I’m in the same boat.
Past: My notes are all over the place. Some are in paper notebooks, on scraps of paper, index cards. Some are plain text files, some are markdown; dumped into random folders (had some in my yyyy/mm/dd folders for my journaling, some in project folders) some are on a wiki, some in redmine, some in openproject. I’ve tried different bug tracking apps, but as mentioned, they (like project management apps) are too burdensome.
Current: For now I am using Joplin for my active notes (and slowly migrating historical notes as I have energy). I have a top level notebook for my homelab, then a subnotebook broken down by subject (infrastructure, app/service, hardware), then individual pages for each specific item (host os setup, vpn, application, etc). On those individual pages, I have it sectioned out; Goal, Research notes, Actions taken, results.
- Personal Notes
- Journal
- Inbox
- Homelab
- Infrastructure
- Host OS
- VPN
- NFS
- Services
- Radicale
- Audiobookshelf
- etc
- Hardware
- node 1
- node 2
- node 3
- router
- Infrastructure
Future step: Once I have something figured out and ready for “prod”, I will be wiping it out and redoing it all through ansible. I’ll take that playbook and a clean markdown doc with the important details and put them in git. That way I can rebuild it later if there is a tragedy.
I have the beginnings of a similar structure in my wiki but I wasn’t happy with the way I was tracking todos, fixes, changes.
Joplin has a plug-in that can grab todos and reveal them all in one spot. You can use tags with it as well. Although I believe it only works on desktop? I haven’t tried on phone/tablet. https://github.com/CalebJohn/joplin-inline-todo#readme
Back in the day when the self-hosted $10 license existed I was using JIRA Service Desk to do this. As far as ticketing systems go it was very easy to work with and didn’t slow me down too much.
I know you don’t want a ticket system but I’m just curious what other people will suggest because I’m in the same boat as you.
Currently I haphazardly use Joplin to take very loose notes and sync them to Nextcloud.
If you want a very simple option with minimal setup and overhead you could use Joplin to create separate notes for each “part” of your lab and just add a new line with a date, time and summary of the change.
I do also use SnipeIT to track all my hardware and parts, which allows you to add notes and service history against the hardware asset.
Other than that, I’m keen to see what everyone else says
I know you don’t want a ticket system but I’m just curious what other people will suggest because I’m in the same boat as you.
I’m not opposed to a ticketing system but I’d want something pretty simple. Last one I tried was GLPI because I thought the inventory mgmt + ticketing would be useful but it was just way too much.
Currently I haphazardly use Joplin to take very loose notes and sync them to Nextcloud.
I’m currently using Wiki.js (synced to GitHub) in an attempt to document things. I’ve played with a changelog section but it’s like a stream of consciousness and I’m not real happy with the layout.
I do also use SnipeIT to track all my hardware and parts, which allows you to add notes and service history against the hardware asset.
That looks cool. I may check that out.
Thanks
Acronyms, initialisms, abbreviations, contractions, and other phrases which expand to something larger, that I’ve seen in this thread:
Fewer Letters More Letters DNS Domain Name Service/System Git Popular version control system, primarily for code VPN Virtual Private Network
3 acronyms in this thread; the most compressed thread commented on today has 6 acronyms.
[Thread #579 for this sub, first seen 6th Mar 2024, 20:55] [FAQ] [Full list] [Contact] [Source code]
A wiki sounds like the right thing since you want to be able to see the current and previous versions of things. It’s a bit easier to edit than straight Markdown in git, which is the other option I’d do. Ticketing systems like OpenProject are more useful for tracking many different pieces of work simultaneously, including future work. The process of changing your current networking setup from A to B would be tracked in OpenProject. New equipment to buy, cabling to do, software to install, descibing it in your wiki, and the progress on each of those. Your wiki would be in state A before you begin this ticket. Once you finish it, your wiki will be in state B. While in progress, the wiki would be somewhere between A and B. You could of course use just the wiki but it’s nice to have a place where you can keep track of all the other things including being able to leave comments that provide context which allows you to resume at a later point in time. At several workplaces the standard setup that always gets entrenched is a ticketing system, a wiki and a version control. Version is only needed for tasks that include code. So the absolute core are the other two. If I had to reduce to a single solution, I’d choose a wiki since I could use separate wiki pages to track my progress as I go from A to B.
