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
You must log in or register to comment.
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.
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.
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.
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
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.
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.
