{"id":13799570,"url":"https://github.com/oddlama/nix-topology","last_synced_at":"2025-05-15T14:07:38.283Z","repository":{"id":231392929,"uuid":"781663273","full_name":"oddlama/nix-topology","owner":"oddlama","description":"🍁 Generate infrastructure and network diagrams directly from your NixOS configurations","archived":false,"fork":false,"pushed_at":"2024-10-28T17:32:51.000Z","size":1732,"stargazers_count":528,"open_issues_count":9,"forks_count":22,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-10-29T17:12:50.797Z","etag":null,"topics":["architecture","diagram","diagram-generator","flake","nix","nix-flake","nixos","topology"],"latest_commit_sha":null,"homepage":"https://oddlama.github.io/nix-topology","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oddlama.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["oddlama"]}},"created_at":"2024-04-03T20:05:49.000Z","updated_at":"2024-10-29T14:30:25.000Z","dependencies_parsed_at":"2024-05-11T11:42:05.830Z","dependency_job_id":"8ccde417-8afa-42a7-8202-70e354350527","html_url":"https://github.com/oddlama/nix-topology","commit_stats":{"total_commits":109,"total_committers":13,"mean_commits":8.384615384615385,"dds":0.2844036697247706,"last_synced_commit":"8738d94670265beb166954c4e3a26e432f79f68c"},"previous_names":["oddlama/nix-topology"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fnix-topology","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fnix-topology/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fnix-topology/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fnix-topology/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oddlama","download_url":"https://codeload.github.com/oddlama/nix-topology/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355335,"owners_count":22057354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","diagram","diagram-generator","flake","nix","nix-flake","nixos","topology"],"created_at":"2024-08-04T00:01:04.084Z","updated_at":"2025-05-15T14:07:33.268Z","avatar_url":"https://github.com/oddlama.png","language":"Nix","funding_links":["https://github.com/sponsors/oddlama"],"categories":["nix","NixOS Modules","Nix"],"sub_categories":["Zig"],"readme":"\u003cp float=\"left\"\u003e\n  \u003ca href=\"https://oddlama.github.io/nix-topology/examples/complex/main.svg\"\u003e\u003cimg src=\"https://oddlama.github.io/nix-topology/examples/complex/main.svg\" alt=\"Main view. Click to enlarge.\" width=\"45%\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://oddlama.github.io/nix-topology/examples/complex/network.svg\"\u003e\u003cimg src=\"https://oddlama.github.io/nix-topology/examples/complex/network.svg\" alt=\"Network view. Click to enlarge.\" width=\"51%\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n[Documentation](https://oddlama.github.io/nix-topology) \\| [Installation and Usage](#-installation-and-usage)\n\n## 🍁 nix-topology\n\nWith nix-topology you can automatically generate infrastructure and network\ndiagrams as SVGs directly from your NixOS configurations, and get something similar to the diagram above.\nIt defines a new global module system where you can specify what nodes and networks you have.\nMost of the work is done by the included NixOS module which automatically collects all the information from your hosts.\n\n- 🌱 Extracts a lot of information automatically from your NixOS configuration:\n  - 🔗 Interfaces from systemd-networkd\n  - 🍵 Known configured services\n  - 🖥️ Guests from [microvm.nix](https://github.com/astro/microvm.nix)\n  - 🖥️ Guests from nixos containers\n  - 🌐 Network information from kea\n- 🗺️ Renders both a main diagram (physical connections) and a network-centric diagram\n- ➡️  Automatically propagates assigned networks through your connections\n- 🖨️ Allows you to add external devices like switches, routers, printers ...\n\nHave a look at the [examples](./examples) directory for some self-contained examples\nor view the rendered results in the [documentation](https://oddlama.github.io/nix-topology).\n\n#### Why?\n\nI became a little envious of all the manually crafted infrastructure diagrams on [r/homelab](https://www.reddit.com/r/homelab/).\nBut who's got time for that?! I'd rather spend a whole lot more time\nto create a generator that I will use once or twice in my life 🤡👍.\nMaybe it will be useful for somebody else, too.\n\n## 📦 Installation and Usage\n\nInstallation should be as simple as adding nix-topology to your flake.nix,\ndefining the global module and adding the NixOS module to your systems.\nA [flake-parts](https://flake.parts) module is also available (see end of this section for an example).\n\n1. Add nix-topology as an input to your flake\n   ```nix\n   inputs.nix-topology.url = \"github:oddlama/nix-topology\";\n   ```\n2. Add the exposed overlay to your global pkgs definition, so the necessary tools are available for rendering\n   ```nix\n   pkgs = import nixpkgs {\n     inherit system;\n     overlays = [nix-topology.overlays.default];\n   };\n   ```\n3. Import the exposed NixOS module `nix-topology.nixosModules.default` in your host configs\n   ```nix\n   nixosConfigurations.host1 = lib.nixosSystem {\n      system = \"x86_64-linux\";\n      modules = [\n        ./host1/configuration.nix\n        nix-topology.nixosModules.default\n      ];\n   };\n   ```\n4. Create the global topology by using `topology = import nix-topology { pkgs = /*...*/; };`.\n   Expose this as an output in your flake so you can access it.\n   ```nix\n   # Repeat this for each system where you want to build your topology.\n   # You can do this manually or use flake-utils.\n   topology.x86_64-linux = import nix-topology {\n     inherit pkgs; # Only this package set must include nix-topology.overlays.default\n     modules = [\n       # Your own file to define global topology. Works in principle like a nixos module but uses different options.\n       ./topology.nix\n       # Inline module to inform topology of your existing NixOS hosts.\n       { nixosConfigurations = self.nixosConfigurations; }\n     ];\n   };\n   ```\n5. Render your topology via `nix build .#topology.x86_64-linux.config.output`, the resulting directory will contain your finished svgs.\n   Note that this can take a minute, depending on how many hosts you have defined. Evaluating many nixos configurations just takes some time,\n   and the renderer sometimes struggles with handling bigger PNGs in a timely fashion.\n\n\u003cdetails\u003e\n\u003csummary\u003eExample flake.nix\u003c/summary\u003e\n\n```nix\n{\n  inputs = {\n    flake-utils.url = \"github:numtide/flake-utils\";\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    nix-topology.url = \"github:oddlama/nix-topology\";\n    nix-topology.inputs.nixpkgs.follows = \"nixpkgs\";\n  };\n\n  outputs = { self, flake-utils, nixpkgs, nix-topology, ... }: {\n    # Example. Use your own hosts and add the module to them\n    nixosConfigurations.host1 = nixpkgs.lib.nixosSystem {\n      system = \"x86_64-linux\";\n      modules = [\n        ./host1/configuration.nix\n        nix-topology.nixosModules.default\n      ];\n    };\n  }\n  // flake-utils.lib.eachDefaultSystem (system: rec {\n    pkgs = import nixpkgs {\n      inherit system;\n      overlays = [ nix-topology.overlays.default ];\n    };\n\n    topology = import nix-topology {\n      inherit pkgs;\n      modules = [\n        # Your own file to define global topology. Works in principle like a nixos module but uses different options.\n        ./topology.nix\n        # Inline module to inform topology of your existing NixOS hosts.\n        { nixosConfigurations = self.nixosConfigurations; }\n      ];\n    };\n  });\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eExample flake.nix with flake-parts\u003c/summary\u003e\n\n\n```nix\n{\n  inputs.flake-parts.url = \"github:hercules-ci/flake-parts\";\n  inputs.nix-topology.url = \"github:oddlama/nix-topology\";\n  # ...\n  outputs = inputs:\n    inputs.flake-parts.lib.mkFlake {inherit inputs;} {\n      imports = [\n        inputs.nix-topology.flakeModule\n      ];\n      perSystem = {...}: {\n        topology.modules = [\n          {\n            # Your global topology definitions\n          }\n        ];\n      };\n    };\n}\n```\n\u003c/details\u003e\n\n## 🌱 Adding connections, networks and other devices\n\nAfter rendering for the first time, the initial diagram might look a little unstructured.\nThat's simply because nix-topology will be missing some important connections that can't\nbe derived from a bunch of NixOS configurations, like physical connections.\nYou'll probably also want to add some common devices like an image for the internet,\nswitches, routers and stuff like that. But don't worry, all of this is quite simple.\nThere's a whole [chapter in the documentation](https://oddlama.github.io/nix-topology/defining-additional-things.html) that will guide you through it.\n\nTL;DR: You can add connections and networks by specifying this information\nin the global topology module, or locally in one of your NixOS configs:\n\n```nix\n# This is a topology module, so use it in your global topology, or under `topology = {};` in any participating NixOS node\n{\n  # Connect node1.lan -\u003e node2.wan\n  nodes.node1.interfaces.lan.physicalConnections = [{ node = \"node2\"; interface = \"wan\"; }];\n  # Add home network\n  networks.home = {\n    name = \"Home Network\";\n    cidrv4 = \"192.168.1.1/24\";\n  };\n  # Tell nix-topology that myhost.lan1 is part of this network.\n  # The network will automatically propagate via the interface's connections.\n  nodes.myhost.interfaces.lan1.network = \"home\";\n}\n```\n\nOr locally (e.g. `host1/configuration.nix`):\n\n```nix\n{\n  topology.networks.home = {\n    name = \"Network Made by Host1\";\n    cidrv4 = \"192.168.178.1/24\";\n  };\n  topology.self.interfaces.lan1.network = \"home\";\n}\n```\n\n## 🔨 TODO\n\nYep, there's still a lot that could be added or improved.\n\n#### Information Gathering (Extractors)\n\n- Podman / docker harvesting\n- networking.interfaces extractor\n- Disks (from disko) + render\n- Impermanence render?\n- Nixos nftables firewall render?\n\n#### General\n\n- NAT indication\n- Macvtap/vlan/bridge interface type svg with small link\n- configurable font\n- Make colors configurable\n\n## ❤️ Contributing\n\nContributions are whole-heartedly welcome! Please feel free to suggest new features,\nimplement extractors, other stuff, or generally help out if you'd like. We'd be happy to have you.\nThere's more information in [CONTRIBUTING.md](CONTRIBUTING.md) and the [Development Chapter](./development.html) in the docs.\n\n## 📜 License\n\nLicensed under the MIT license ([LICENSE](LICENSE) or \u003chttps://opensource.org/licenses/MIT\u003e).\nUnless you explicitly state otherwise, any contribution intentionally\nsubmitted for inclusion in this project by you, shall be licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddlama%2Fnix-topology","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foddlama%2Fnix-topology","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddlama%2Fnix-topology/lists"}