I started using NixOS as my first actual Linux experience in February. Since then, the project has boomed under my hands. Now it’s my small home infra, just for me and my friends. But because I had to choose something as my high school graduation project, I realised presenting the infra itself would be fun.
I struggled with docs without any way to simply explain how my setup works. So this is why Nixdiag now exists. It’s a small tool, probably in alpha version. It can create flake input visualisations, as well as the topology and closure visualisations.
I would like to get some feedback: what to change and what to add. PRs are welcome.
The biggest downside is that closure visualisations can only be generated by an actual build. This is fine when you use some type of caching like Harmonia, but not good for “I just want a fast sketch”.
(I was informed, I need to disclose LLM usage for projects. I am so sorry I haven’t read the rules mentioning it. The tool’s code is mainly generated by claude, idea is mine. My infra is my own project, where i am using LLMs for debugging at the first place.)
1 Like
Super cool, I’ve been dreaming about building generated diagrams for NixOS deployments for ages.
I wonder, what’s the motivation to not use the module system itself for annotations? This way nixdiag could provide default annotations for well known modules:
# headscale.nix
{config, lib, ... }: let
cfg = config.services.headscale;
in lib.mkIf cfg.enable {
nixdiag.services.headscale = {
role = lib.mkDefault "mesh-control";
expose = {
inherit (cfg) port;
};;
};
}
And the user would only need to supply the information that can’t set by default:
# configuration.nix
{
services.headscale.enable = true;
nixdiag.services.headscale.name = "hs.example.com";
}
Statically generated diagrams could even be a result of the module system like system.build.toplevel, eliminating the need for the user to install a CLI tool.
2 Likes
pretty cool idea to add as a github-pages asset for my nixos configurations tied to a particular commit.
1 Like
Did you try Intro - nix-topology? It seems to have pretty good docs.
2 Likes
I thought simillar way, but since the tool’s main purpose the day i started was only to let me map the topology without need to rebuild d2 schema each time, i decided to use comment styled syntax. It would be pretty cool, to have implemented well known modules this way, but the core would have to be able of adaptation to modules options changes. This is perfect idea for me to implement later, after the current work/school press dissapears.
No i haven’t. I heard about it from my friend. Seems cool, but maps only the topology or not?
Only topology, but it generates very nice diagrams (at least from all the ones I have seen, don’t use it personally because I only run 1 machine off of nix). You could probably hack it to do something similar to your flake input view by making another topology instance with only your flake inputs as additional things, but it would fall a bit short at your other visualizations. You may want to at least point your agent at it to see if you can reuse any code from extractors to make your topology view nicer and have more info about ports etc.
2 Likes
