Revert "cli: fix installation test with latest release of nixos-anywhere"

This reverts commit 46f746d09c.

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## Description of the change
+
+<!-- Brief summary of the change if not already clear from the title -->
+
+## Checklist
+
+- [ ] Updated Documentation
+- [ ] Added tests
+- [ ] Doesn't affect backwards compatibility - or check the next points
+  - [ ] Add the breaking change and migration details to docs/release-notes.md
+  - !!! Review from another person is required *BEFORE* merge !!!
+- [ ] Add introduction of major feature to docs/release-notes.md

CONTRIBUTING.md

@@ -1,4 +0,0 @@
-# Contributing to Clan
-
-<!-- Local file: docs/CONTRIBUTING.md -->
-Go to the Contributing guide at https://docs.clan.lol/guides/contributing/CONTRIBUTING

checks/flake-module.nix

@@ -19,28 +19,19 @@ let
   nixosLib = import (self.inputs.nixpkgs + "/nixos/lib") { };
 in
 {
-  imports =
-    let
-      clanCoreModulesDir = ../nixosModules/clanCore;
-      getClanCoreTestModules =
-        let
-          moduleNames = attrNames (builtins.readDir clanCoreModulesDir);
-          testPaths = map (
-            moduleName: clanCoreModulesDir + "/${moduleName}/tests/flake-module.nix"
-          ) moduleNames;
-        in
-        filter pathExists testPaths;
-    in
-    getClanCoreTestModules
-    ++ filter pathExists [
-      ./devshell/flake-module.nix
-      ./flash/flake-module.nix
-      ./installation/flake-module.nix
-      ./update/flake-module.nix
-      ./morph/flake-module.nix
-      ./nixos-documentation/flake-module.nix
-      ./dont-depend-on-repo-root.nix
-    ];
+  imports = filter pathExists [
+    ./devshell/flake-module.nix
+    ./flash/flake-module.nix
+    ./installation/flake-module.nix
+    ./update/flake-module.nix
+    ./morph/flake-module.nix
+    ./nixos-documentation/flake-module.nix
+    ./dont-depend-on-repo-root.nix
+    # clan core submodule tests
+    ../nixosModules/clanCore/machine-id/tests/flake-module.nix
+    ../nixosModules/clanCore/postgresql/tests/flake-module.nix
+    ../nixosModules/clanCore/state-version/tests/flake-module.nix
+  ];
   flake.check = genAttrs [ "x86_64-linux" "aarch64-darwin" ] (
     system:
     let
@@ -120,7 +111,7 @@ in
             ) (self.darwinConfigurations or { })
             // lib.mapAttrs' (n: lib.nameValuePair "package-${n}") (
               if system == "aarch64-darwin" then
-                lib.filterAttrs (n: _: n != "docs" && n != "deploy-docs" && n != "docs-options") packagesToBuild
+                lib.filterAttrs (n: _: n != "docs" && n != "deploy-docs" && n != "option-search") packagesToBuild
               else
                 packagesToBuild
             )

checks/flash/flake-module.nix

@@ -13,8 +13,6 @@
         fileSystems."/".device = lib.mkDefault "/dev/vda";
         boot.loader.grub.device = lib.mkDefault "/dev/vda";
 
-        # We need to use `mkForce` because we inherit from `test-install-machine`
-        # which currently hardcodes `nixpkgs.hostPlatform`
         nixpkgs.hostPlatform = lib.mkForce system;
 
         imports = [ self.nixosModules.test-flash-machine ];
@@ -28,6 +26,9 @@
       {
         imports = [ self.nixosModules.test-install-machine-without-system ];
 
+        # We don't want our system to define any `vars` generators as these can't
+        # be generated as the flake is inside `/nix/store`.
+        clan.core.settings.state-version.enable = false;
         clan.core.vars.generators.test = lib.mkForce { };
         disko.devices.disk.main.preCreateHook = lib.mkForce "";
 
@@ -59,11 +60,11 @@
         pkgs.kbd.out
         self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".pkgs.perlPackages.ConfigIniFiles
         self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".pkgs.perlPackages.FileSlurp
+        pkgs.bubblewrap
 
         self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".config.system.build.toplevel
         self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".config.system.build.diskoScript
         self.nixosConfigurations."test-flash-machine-${pkgs.hostPlatform.system}".config.system.build.diskoScript.drvPath
-        (import ../installation/facter-report.nix pkgs.hostPlatform.system)
       ]
       ++ builtins.map (i: i.outPath) (builtins.attrValues self.inputs);
       closureInfo = pkgs.closureInfo { rootPaths = dependencies; };
@@ -87,7 +88,7 @@
               substituters = lib.mkForce [ ];
               hashed-mirrors = null;
               connect-timeout = lib.mkForce 3;
-              flake-registry = pkgs.writeText "flake-registry" ''{"flakes":[],"version":2}'';
+              flake-registry = "";
               experimental-features = [
                 "nix-command"
                 "flakes"

checks/installation/facter-report.nix

@@ -1,10 +0,0 @@
-system:
-builtins.fetchurl {
-  url = "https://git.clan.lol/clan/test-fixtures/raw/commit/4a2bc56d886578124b05060d3fb7eddc38c019f8/nixos-vm-facter-json/${system}.json";
-  sha256 =
-    {
-      aarch64-linux = "sha256:1rlfymk03rmfkm2qgrc8l5kj5i20srx79n1y1h4nzlpwaz0j7hh2";
-      x86_64-linux = "sha256:16myh0ll2gdwsiwkjw5ba4dl23ppwbsanxx214863j7nvzx42pws";
-    }
-    .${system};
-}

checks/installation/flake-module.nix

@@ -1,8 +1,8 @@
 {
+  config,
   self,
   lib,
   privateInputs,
-
   ...
 }:
 {
@@ -14,26 +14,37 @@
   # you can get a new one by adding
   # client.fail("cat test-flake/machines/test-install-machine/facter.json >&2")
   # to the installation test.
-  clan.machines.test-install-machine-without-system = {
-    fileSystems."/".device = lib.mkDefault "/dev/vda";
-    boot.loader.grub.device = lib.mkDefault "/dev/vda";
-
-    imports = [
-      self.nixosModules.test-install-machine-without-system
-    ];
-  };
-
-  clan.machines.test-install-machine-with-system =
-    { pkgs, ... }:
-    {
-      # https://git.clan.lol/clan/test-fixtures
-      facter.reportPath = import ./facter-report.nix pkgs.hostPlatform.system;
-
+  clan.machines = {
+    test-install-machine-without-system = {
       fileSystems."/".device = lib.mkDefault "/dev/vda";
       boot.loader.grub.device = lib.mkDefault "/dev/vda";
 
-      imports = [ self.nixosModules.test-install-machine-without-system ];
+      imports = [
+        self.nixosModules.test-install-machine-without-system
+      ];
     };
+  }
+  // (lib.listToAttrs (
+    lib.map (
+      system:
+      lib.nameValuePair "test-install-machine-${system}" {
+        imports = [
+          self.nixosModules.test-install-machine-without-system
+          (
+            if privateInputs ? test-fixtures then
+              {
+                facter.reportPath = privateInputs.test-fixtures + /nixos-vm-facter-json/${system}.json;
+              }
+            else
+              { nixpkgs.hostPlatform = system; }
+          )
+        ];
+
+        fileSystems."/".device = lib.mkDefault "/dev/vda";
+        boot.loader.grub.device = lib.mkDefault "/dev/vda";
+      }
+    ) (lib.filter (lib.hasSuffix "linux") config.systems)
+  ));
 
   flake.nixosModules = {
     test-install-machine-without-system =
@@ -149,13 +160,12 @@
           closureInfo = pkgs.closureInfo {
             rootPaths = [
               privateInputs.clan-core-for-checks
-              self.clanInternals.machines.${pkgs.hostPlatform.system}.test-install-machine-with-system.config.system.build.toplevel
-              self.clanInternals.machines.${pkgs.hostPlatform.system}.test-install-machine-with-system.config.system.build.initialRamdisk
-              self.clanInternals.machines.${pkgs.hostPlatform.system}.test-install-machine-with-system.config.system.build.diskoScript
+              self.nixosConfigurations."test-install-machine-${pkgs.hostPlatform.system}".config.system.build.toplevel
+              self.nixosConfigurations."test-install-machine-${pkgs.hostPlatform.system}".config.system.build.initialRamdisk
+              self.nixosConfigurations."test-install-machine-${pkgs.hostPlatform.system}".config.system.build.diskoScript
               pkgs.stdenv.drvPath
               pkgs.bash.drvPath
               pkgs.buildPackages.xorg.lndir
-              (import ./facter-report.nix pkgs.hostPlatform.system)
             ]
             ++ builtins.map (i: i.outPath) (builtins.attrValues self.inputs);
           };
@@ -205,7 +215,7 @@
                   # Prepare test flake and Nix store
                   flake_dir = prepare_test_flake(
                       temp_dir,
-                      "${self.checks.x86_64-linux.clan-core-for-checks}",
+                      "${self.checks.${pkgs.hostPlatform.system}.clan-core-for-checks}",
                       "${closureInfo}"
                   )
 
@@ -216,6 +226,22 @@
                       "${../assets/ssh/privkey}"
                   )
 
+                  # Run clan install from host using port forwarding
+                  clan_cmd = [
+                      "${self.packages.${pkgs.system}.clan-cli-full}/bin/clan",
+                      "machines",
+                      "init-hardware-config",
+                      "--debug",
+                      "--flake", str(flake_dir),
+                      "--yes", "test-install-machine-without-system",
+                      "--host-key-check", "none",
+                      "--target-host", f"nonrootuser@localhost:{ssh_conn.host_port}",
+                      "-i", ssh_conn.ssh_key,
+                      "--option", "store", os.environ['CLAN_TEST_STORE']
+                  ]
+                  subprocess.run(clan_cmd, check=True)
+
+
                   # Run clan install from host using port forwarding
                   clan_cmd = [
                       "${self.packages.${pkgs.system}.clan-cli-full}/bin/clan",
@@ -270,7 +296,7 @@
                   # Prepare test flake and Nix store
                   flake_dir = prepare_test_flake(
                       temp_dir,
-                      "${self.checks.x86_64-linux.clan-core-for-checks}",
+                      "${self.checks.${pkgs.hostPlatform.system}.clan-core-for-checks}",
                       "${closureInfo}"
                   )
 

checks/installation/test-helpers.nix

@@ -15,7 +15,6 @@ let
       networking.useNetworkd = true;
       services.openssh.enable = true;
       services.openssh.settings.UseDns = false;
-      services.openssh.settings.PasswordAuthentication = false;
       system.nixos.variant_id = "installer";
       environment.systemPackages = [
         pkgs.nixos-facter
@@ -147,28 +146,11 @@ let
     ];
     doCheck = false;
   };
-
-  # Common closure info
-  closureInfo = pkgs.closureInfo {
-    rootPaths = [
-      self.checks.x86_64-linux.clan-core-for-checks
-      self.clanInternals.machines.${pkgs.hostPlatform.system}.test-install-machine-with-system.config.system.build.toplevel
-      self.clanInternals.machines.${pkgs.hostPlatform.system}.test-install-machine-with-system.config.system.build.initialRamdisk
-      self.clanInternals.machines.${pkgs.hostPlatform.system}.test-install-machine-with-system.config.system.build.diskoScript
-      self.clanInternals.machines.${pkgs.hostPlatform.system}.test-install-machine-with-system.config.system.clan.deployment.file
-      pkgs.stdenv.drvPath
-      pkgs.bash.drvPath
-      pkgs.buildPackages.xorg.lndir
-    ]
-    ++ builtins.map (i: i.outPath) (builtins.attrValues self.inputs);
-  };
-
 in
 {
   inherit
     target
     baseTestMachine
     nixosTestLib
-    closureInfo
     ;
 }

checks/morph/flake-module.nix

@@ -35,7 +35,6 @@
                   pkgs.stdenv.drvPath
                   pkgs.stdenvNoCC
                   self.nixosConfigurations.test-morph-machine.config.system.build.toplevel
-                  (import ../installation/facter-report.nix pkgs.hostPlatform.system)
                 ]
                 ++ builtins.map (i: i.outPath) (builtins.attrValues self.inputs);
                 closureInfo = pkgs.closureInfo { rootPaths = dependencies; };

checks/service-dummy-test-from-flake/default.nix

@@ -29,32 +29,34 @@ nixosLib.runTest (
       { nodes, ... }:
       ''
         import subprocess
-        from nixos_test_lib.nix_setup import setup_nix_in_nix # type: ignore[import-untyped]
+        import tempfile
+        from nixos_test_lib.nix_setup import setup_nix_in_nix
 
-        setup_nix_in_nix(None)  # No closure info for this test
+        with tempfile.TemporaryDirectory() as temp_dir:
+          setup_nix_in_nix(temp_dir, None)  # No closure info for this test
 
-        start_all()
-        admin1.wait_for_unit("multi-user.target")
-        peer1.wait_for_unit("multi-user.target")
+          start_all()
+          admin1.wait_for_unit("multi-user.target")
+          peer1.wait_for_unit("multi-user.target")
 
-        # peer1 should have the 'hello' file
-        peer1.succeed("cat ${nodes.peer1.clan.core.vars.generators.new-service.files.not-a-secret.path}")
+          # peer1 should have the 'hello' file
+          peer1.succeed("cat ${nodes.peer1.clan.core.vars.generators.new-service.files.not-a-secret.path}")
 
-        ls_out = peer1.succeed("ls -la ${nodes.peer1.clan.core.vars.generators.new-service.files.a-secret.path}")
-        # Check that the file is owned by 'nobody'
-        assert "nobody" in ls_out, f"File is not owned by 'nobody': {ls_out}"
-        # Check that the file is in the 'users' group
-        assert "users" in ls_out, f"File is not in the 'users' group: {ls_out}"
-        # Check that the file is in the '0644' mode
-        assert "-rw-r--r--" in ls_out, f"File is not in the '0644' mode: {ls_out}"
+          ls_out = peer1.succeed("ls -la ${nodes.peer1.clan.core.vars.generators.new-service.files.a-secret.path}")
+          # Check that the file is owned by 'nobody'
+          assert "nobody" in ls_out, f"File is not owned by 'nobody': {ls_out}"
+          # Check that the file is in the 'users' group
+          assert "users" in ls_out, f"File is not in the 'users' group: {ls_out}"
+          # Check that the file is in the '0644' mode
+          assert "-rw-r--r--" in ls_out, f"File is not in the '0644' mode: {ls_out}"
 
-        # Run clan command
-        result = subprocess.run(
-            ["${
-              clan-core.packages.${hostPkgs.system}.clan-cli
-            }/bin/clan", "machines", "list", "--flake", "${config.clan.test.flakeForSandbox}"],
-            check=True
-        )
+          # Run clan command
+          result = subprocess.run(
+              ["${
+                clan-core.packages.${hostPkgs.system}.clan-cli
+              }/bin/clan", "machines", "list", "--flake", "${config.clan.test.flakeForSandbox}"],
+              check=True
+          )
       '';
   }
 )

checks/service-dummy-test-from-flake/flake.nix

@@ -27,7 +27,9 @@
         modules.new-service = {
           _class = "clan.service";
           manifest.name = "new-service";
-          roles.peer = { };
+          roles.peer = {
+            description = "A peer that uses the new-service to generate some files.";
+          };
           perMachine = {
             nixosModule = {
               # This should be generated by:

checks/service-dummy-test/default.nix

@@ -34,7 +34,9 @@ nixosLib.runTest (
       modules.new-service = {
         _class = "clan.service";
         manifest.name = "new-service";
-        roles.peer = { };
+        roles.peer = {
+          description = "A peer that uses the new-service to generate some files.";
+        };
         perMachine = {
           nixosModule = {
             # This should be generated by:

checks/update/flake-module.nix

@@ -67,6 +67,15 @@
         ];
       };
 
+      nix.settings = {
+        flake-registry = "";
+        # required for setting the `flake-registry`
+        experimental-features = [
+          "nix-command"
+          "flakes"
+        ];
+      };
+
       # Define the mounts that exist in the container to prevent them from being stopped
       fileSystems = {
         "/" = {
@@ -106,13 +115,13 @@
               let
                 closureInfo = pkgs.closureInfo {
                   rootPaths = [
-                    self.packages.${pkgs.system}.clan-cli
-                    self.checks.${pkgs.system}.clan-core-for-checks
+                    self.packages.${pkgs.hostPlatform.system}.clan-cli
+                    self.checks.${pkgs.hostPlatform.system}.clan-core-for-checks
                     self.clanInternals.machines.${pkgs.hostPlatform.system}.test-update-machine.config.system.build.toplevel
                     pkgs.stdenv.drvPath
                     pkgs.bash.drvPath
                     pkgs.buildPackages.xorg.lndir
-                    (import ../installation/facter-report.nix pkgs.hostPlatform.system)
+                    pkgs.bubblewrap
                   ]
                   ++ builtins.map (i: i.outPath) (builtins.attrValues self.inputs);
                 };
@@ -123,7 +132,7 @@
                   imports = [ self.nixosModules.test-update-machine ];
                 };
                 extraPythonPackages = _p: [
-                  self.legacyPackages.${pkgs.system}.nixosTestLib
+                  self.legacyPackages.${pkgs.hostPlatform.system}.nixosTestLib
                 ];
 
                 testScript = ''
@@ -145,7 +154,7 @@
                       # Prepare test flake and Nix store
                       flake_dir = prepare_test_flake(
                           temp_dir,
-                          "${self.checks.x86_64-linux.clan-core-for-checks}",
+                          "${self.checks.${pkgs.hostPlatform.system}.clan-core-for-checks}",
                           "${closureInfo}"
                       )
                       (flake_dir / ".clan-flake").write_text("")  # Ensure .clan-flake exists
@@ -212,12 +221,13 @@
                         [
                             "${pkgs.nix}/bin/nix",
                             "copy",
+                            "--from",
+                            f"{temp_dir}/store",
                             "--to",
                             "ssh://root@192.168.1.1",
                             "--no-check-sigs",
-                            f"${self.packages.${pkgs.system}.clan-cli}",
+                            f"${self.packages.${pkgs.hostPlatform.system}.clan-cli}",
                             "--extra-experimental-features", "nix-command flakes",
-                            "--from", f"{os.environ["TMPDIR"]}/store"
                         ],
                         check=True,
                         env={
@@ -232,7 +242,7 @@
                           "-o", "UserKnownHostsFile=/dev/null",
                           "-o", "StrictHostKeyChecking=no",
                           f"root@192.168.1.1",
-                          "${self.packages.${pkgs.system}.clan-cli}/bin/clan",
+                          "${self.packages.${pkgs.hostPlatform.system}.clan-cli}/bin/clan",
                           "machines",
                           "update",
                           "--debug",
@@ -260,7 +270,7 @@
 
                       # Run clan update command
                       subprocess.run([
-                          "${self.packages.${pkgs.system}.clan-cli-full}/bin/clan",
+                          "${self.packages.${pkgs.hostPlatform.system}.clan-cli-full}/bin/clan",
                           "machines",
                           "update",
                           "--debug",
@@ -287,7 +297,7 @@
 
                       # Run clan update command with --build-host
                       subprocess.run([
-                          "${self.packages.${pkgs.system}.clan-cli-full}/bin/clan",
+                          "${self.packages.${pkgs.hostPlatform.system}.clan-cli-full}/bin/clan",
                           "machines",
                           "update",
                           "--debug",

clanServices/admin/default.nix

@@ -1,14 +1,14 @@
 {
   _class = "clan.service";
   manifest.name = "clan-core/admin";
-  manifest.description = "Convenient Administration for the Clan App";
+  manifest.description = "Adds a root user with ssh access";
   manifest.categories = [ "Utility" ];
 
   roles.default = {
+    description = "Placeholder role to apply the admin service";
     interface =
       { lib, ... }:
       {
-
         options = {
           allowedKeys = lib.mkOption {
             default = { };

clanServices/borgbackup/README.md

@@ -9,7 +9,7 @@ inventory.instances = {
     };
     roles.client.machines."jon".settings = {
       destinations."storagebox" = {
-        repo = "username@$hostname:/./borgbackup";
+        repo = "username@hostname:/./borgbackup";
         rsh = ''ssh -oPort=23 -i /run/secrets/vars/borgbackup/borgbackup.ssh'';
       };
     };

clanServices/borgbackup/default.nix

@@ -9,7 +9,7 @@
   # TODO: a client can only be in one instance, add constraint
 
   roles.server = {
-
+    description = "A borgbackup server that stores the backups of clients.";
     interface =
       { lib, ... }:
       {
@@ -54,7 +54,7 @@
                   authorizedKeys = [ (builtins.readFile (borgbackupIpMachinePath machineName)) ];
                   # };
                   # }) machinesWithKey;
-                }) roles.client.machines;
+                }) (roles.client.machines or { });
               in
               hosts;
           };
@@ -62,6 +62,7 @@
   };
 
   roles.client = {
+    description = "A borgbackup client that backs up to all borgbackup server roles.";
     interface =
       {
         lib,
@@ -187,7 +188,7 @@
                           config.clan.core.vars.generators.borgbackup.files."borgbackup.ssh".path
                         } -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o IdentitiesOnly=Yes";
                       };
-                    }) (builtins.attrNames roles.server.machines);
+                    }) (builtins.attrNames (roles.server.machines or { }));
                   in
                   (builtins.listToAttrs destinations);
 

clanServices/certificates/default.nix

@@ -2,12 +2,12 @@
 {
   _class = "clan.service";
   manifest.name = "certificates";
-  manifest.description = "Sets up a certificates internal to your Clan";
+  manifest.description = "Sets up a PKI certificate chain using step-ca";
   manifest.categories = [ "Network" ];
   manifest.readme = builtins.readFile ./README.md;
 
   roles.ca = {
-
+    description = "A certificate authority that issues and signs certificates for other machines.";
     interface =
       { lib, ... }:
       {
@@ -184,6 +184,7 @@
 
   # Empty role, so we can add non-ca machins to the instance to trust the CA
   roles.default = {
+    description = "A machine that trusts the CA and can get certificates issued by it.";
     interface =
       { lib, ... }:
       {

clanServices/coredns/README.md

@@ -45,13 +45,15 @@ inventory = {
       # Add the default role to all machines, including `client`
       roles.default.tags.all = { };
 
-      # DNS server
+      # DNS server queries to http://<name>.foo are resolved here
       roles.server.machines."dnsserver".settings = {
         ip = "192.168.1.2";
         tld = "foo";
       };
 
       # First service
+      # Registers http://one.foo will resolve to 192.168.1.3
+      # underlying service runs on server01
       roles.default.machines."server01".settings = {
         ip = "192.168.1.3";
         services = [ "one" ];

clanServices/coredns/default.nix

@@ -8,7 +8,7 @@
   manifest.readme = builtins.readFile ./README.md;
 
   roles.server = {
-
+    description = "A DNS server that resolves services in the clan network.";
     interface =
       { lib, ... }:
       {
@@ -103,6 +103,7 @@
   };
 
   roles.default = {
+    description = "A machine that registers the 'server' role as resolver and registers services under the configured TLD in the resolver.";
     interface =
       { lib, ... }:
       {

clanServices/coredns/tests/vm/default.nix

@@ -50,13 +50,13 @@
     dns =
       { pkgs, ... }:
       {
-        environment.systemPackages = [ pkgs.net-tools ];
+        environment.systemPackages = [ pkgs.nettools ];
       };
 
     client =
       { pkgs, ... }:
       {
-        environment.systemPackages = [ pkgs.net-tools ];
+        environment.systemPackages = [ pkgs.nettools ];
       };
 
     server01 = {

clanServices/data-mesher/default.nix

@@ -101,6 +101,7 @@ in
   manifest.readme = builtins.readFile ./README.md;
 
   roles.admin = {
+    description = "A data-mesher admin node that bootstraps the network and can sign new nodes into the network.";
     interface =
       { lib, ... }:
       {
@@ -177,6 +178,7 @@ in
   };
 
   roles.signer = {
+    description = "A data-mesher signer node that can sign new nodes into the network.";
     interface = sharedInterface;
     perInstance =
       {
@@ -208,6 +210,7 @@ in
   };
 
   roles.peer = {
+    description = "A data-mesher peer node that connects to the network.";
     interface = sharedInterface;
     perInstance =
       {

clanServices/dyndns/default.nix

@@ -2,11 +2,12 @@
 {
   _class = "clan.service";
   manifest.name = "clan-core/dyndns";
-  manifest.description = "A dynamic DNS service to update domain IPs";
+  manifest.description = "A dynamic DNS service to auto update domain IPs";
   manifest.categories = [ "Network" ];
   manifest.readme = builtins.readFile ./README.md;
 
   roles.default = {
+    description = "Placeholder role to apply the dyndns service";
     interface =
       { lib, ... }:
       {

clanServices/emergency-access/default.nix

@@ -2,31 +2,34 @@
 {
   _class = "clan.service";
   manifest.name = "clan-core/emergency-access";
-  manifest.description = "Set recovery password for emergency access to machine";
+  manifest.description = "Set recovery password for emergency access to machine to debug boot issues";
   manifest.categories = [ "System" ];
   manifest.readme = builtins.readFile ./README.md;
 
-  roles.default.perInstance = {
-    nixosModule =
-      { config, pkgs, ... }:
-      {
-        boot.initrd.systemd.emergencyAccess =
-          config.clan.core.vars.generators.emergency-access.files.password-hash.value;
+  roles.default = {
+    description = "Placeholder role to apply the emergency-access service";
+    perInstance = {
+      nixosModule =
+        { config, pkgs, ... }:
+        {
+          boot.initrd.systemd.emergencyAccess =
+            config.clan.core.vars.generators.emergency-access.files.password-hash.value;
 
-        clan.core.vars.generators.emergency-access = {
-          runtimeInputs = [
-            pkgs.coreutils
-            pkgs.mkpasswd
-            pkgs.xkcdpass
-          ];
-          files.password.deploy = false;
-          files.password-hash.secret = false;
+          clan.core.vars.generators.emergency-access = {
+            runtimeInputs = [
+              pkgs.coreutils
+              pkgs.mkpasswd
+              pkgs.xkcdpass
+            ];
+            files.password.deploy = false;
+            files.password-hash.secret = false;
 
-          script = ''
-            xkcdpass --numwords 4 --delimiter - --count 1 | tr -d "\n" > $out/password
-            mkpasswd -s -m sha-512 < $out/password | tr -d "\n" > $out/password-hash
-          '';
+            script = ''
+              xkcdpass --numwords 4 --delimiter - --count 1 | tr -d "\n" > $out/password
+              mkpasswd -s -m sha-512 < $out/password | tr -d "\n" > $out/password-hash
+            '';
+          };
         };
-      };
+    };
   };
 }

clanServices/garage/default.nix

@@ -6,7 +6,7 @@
   manifest.categories = [ "System" ];
 
   roles.default = {
-
+    description = "Placeholder role to apply the garage service";
     perInstance.nixosModule =
       {
         config,

clanServices/hello-world/default.nix

@@ -14,6 +14,7 @@
   # defined in this file directly (e.g. the "morning" role) or split up into a
   # separate file (e.g. the "evening" role)
   roles.morning = {
+    description = "A morning greeting machine";
     interface =
       { lib, ... }:
       {
@@ -67,6 +68,7 @@
   # the interface here, so we can see all settings of the service in one place,
   # but you can also move it to the respective file
   roles.evening = {
+    description = "An evening greeting machine";
     interface =
       { lib, ... }:
       {

clanServices/importer/default.nix

@@ -6,5 +6,7 @@
   manifest.categories = [ "Utility" ];
   manifest.readme = builtins.readFile ./README.md;
 
-  roles.default = { };
+  roles.default = {
+    description = "Placeholder role to apply the importer service";
+  };
 }

clanServices/internet/default.nix

@@ -2,12 +2,13 @@
 {
   _class = "clan.service";
   manifest.name = "clan-core/internet";
-  manifest.description = "direct access (or via ssh jumphost) to machines";
+  manifest.description = "Part of the clan networking abstraction to define how to reach machines from outside the clan network over the internet, if defined has the highest priority";
   manifest.categories = [
     "System"
     "Network"
   ];
   roles.default = {
+    description = "Placeholder role to apply the internet service";
     interface =
       { lib, ... }:
       {

clanServices/localbackup/default.nix

@@ -2,11 +2,12 @@
 {
   _class = "clan.service";
   manifest.name = "localbackup";
-  manifest.description = "Automatically backups current machine to local directory.";
+  manifest.description = "Automatically backups current machine to local directory or a mounted drive.";
   manifest.categories = [ "System" ];
   manifest.readme = builtins.readFile ./README.md;
 
   roles.default = {
+    description = "Placeholder role to apply the localbackup service";
     interface =
       { lib, ... }:
       {

clanServices/matrix-synapse/default.nix

@@ -6,6 +6,7 @@
   manifest.categories = [ "Social" ];
 
   roles.default = {
+    description = "Placeholder role to apply the matrix-synapse service";
     interface =
       { lib, ... }:
       {

clanServices/monitoring/default.nix

@@ -6,6 +6,7 @@
   manifest.readme = builtins.readFile ./README.md;
 
   roles.telegraf = {
+    description = "Placeholder role to apply the telegraf monitoring agent";
     interface =
       { lib, ... }:
       {

clanServices/mycelium/default.nix

@@ -2,13 +2,14 @@
 {
   _class = "clan.service";
   manifest.name = "clan-core/mycelium";
-  manifest.description = "End-2-end encrypted IPv6 overlay network";
+  manifest.description = "End-2-end encrypted P2P IPv6 overlay network";
   manifest.categories = [
     "System"
     "Network"
   ];
 
   roles.peer = {
+    description = "A peer in the mycelium network";
     interface =
       { lib, ... }:
       {

clanServices/packages/default.nix

@@ -8,6 +8,7 @@
   ];
 
   roles.default = {
+    description = "Placeholder role to apply the packages service";
     interface =
       { lib, ... }:
       {

clanServices/sshd/README.md

@@ -1,11 +1,15 @@
-The `sshd` Clan service manages SSH to make it easy to securely access your machines over the internet. The service uses `vars` to store the SSH host keys for each machine to ensure they remain stable across deployments.
+The `sshd` Clan service manages SSH to make it easy to securely access your
+machines over the internet. The service uses `vars` to store the SSH host keys
+for each machine to ensure they remain stable across deployments.
 
-`sshd` also generates SSH certificates for both servers and clients allowing for certificate-based authentication for SSH.
+`sshd` also generates SSH certificates for both servers and clients allowing for
+certificate-based authentication for SSH.
 
-The service also disables password-based authentication over SSH, to access your machines you'll need to use public key authentication or certificate-based authentication.
+The service also disables password-based authentication over SSH, to access your
+machines you'll need to use public key authentication or certificate-based
+authentication.
 
 ## Usage
-
 ```nix
 {
   inventory.instances = {
@@ -18,7 +22,6 @@ The service also disables password-based authentication over SSH, to access your
       roles.server.tags.all = { };
       roles.client.tags.all = { };
     };
-
     # Also generate RSA host keys for all servers
     sshd-with-rsa = {
       module = {

clanServices/sshd/default.nix

@@ -10,6 +10,7 @@
   manifest.readme = builtins.readFile ./README.md;
 
   roles.client = {
+    description = "Installs the SSH CA public key into known_hosts for the configured domains, so this machine can verify servers’ host certificates without TOFU prompts.";
     interface =
       { lib, ... }:
       {
@@ -38,7 +39,6 @@
             ...
           }:
           {
-
             clan.core.vars.generators.openssh-ca = lib.mkIf (settings.certificate.searchDomains != [ ]) {
               share = true;
               files.id_ed25519.deploy = false;
@@ -64,11 +64,12 @@
   };
 
   roles.server = {
+    description = "Runs sshd with persistent host keys and (if certificate.searchDomains is set) a CA‑signed host certificate for <machine>.<domain>, enabling TOFU‑less verification by clients that trust the CA.";
     interface =
       { lib, ... }:
       {
         options = {
-          hostKeys.rsa.enable = lib.mkEnableOption "Generate RSA host key";
+          hostKeys.rsa.enable = lib.mkEnableOption "generating a RSA host key";
 
           certificate = {
             searchDomains = lib.mkOption {
@@ -96,9 +97,7 @@
             ...
           }:
           {
-
             clan.core.vars.generators = {
-
               openssh-ca = lib.mkIf (settings.certificate.searchDomains != [ ]) {
                 share = true;
                 files.id_ed25519.deploy = false;

clanServices/syncthing/README.md

@@ -13,7 +13,7 @@
 }
 ```
 
-Now the folder `~/syncthing/documents` will be shared with all your machines.
+Now the folder `~/syncthing/documents` will be shared and kept in sync with all your machines.
 
 
 ## Documentation 

clanServices/syncthing/default.nix

@@ -11,6 +11,7 @@
   manifest.readme = builtins.readFile ./README.md;
 
   roles.peer = {
+    description = "A peer in the syncthing cluster that syncs files with other peers.";
     interface =
       { lib, ... }:
       {

clanServices/syncthing/vars.nix

@@ -11,9 +11,7 @@
       pkgs.syncthing
     ];
     script = ''
-      export TMPDIR=/tmp
-      TEMPORARY=$(mktemp -d)
-      syncthing generate --config "$out" --data "$TEMPORARY"
+      syncthing generate --config "$out"
       mv "$out"/key.pem "$out"/key
       mv "$out"/cert.pem "$out"/cert
       cat "$out"/config.xml | grep -oP '(?<=<device id=")[^"]+' | uniq > "$out"/id

clanServices/tor/default.nix

@@ -2,13 +2,17 @@
 {
   _class = "clan.service";
   manifest.name = "clan-core/tor";
-  manifest.description = "Onion routing, use Hidden services to connect your machines";
+  manifest.description = "Part of the clan networking abstraction to define how to reach machines through the Tor network, if used has the lowest priority";
   manifest.categories = [
     "System"
     "Network"
   ];
 
   roles.client = {
+    description = ''
+      Enables a continuosly running Tor proxy on the machine, allowing access to other machines via the Tor network.
+      If not enabled, a Tor proxy will be started automatically when required.
+    '';
     perInstance =
       {
         ...
@@ -31,6 +35,7 @@
   };
 
   roles.server = {
+    description = "Sets up a Tor onion service for the machine, thus making it reachable over Tor.";
     # interface =
     #   { lib, ... }:
     #   {

clanServices/trusted-nix-caches/default.nix

@@ -7,7 +7,7 @@
   manifest.readme = builtins.readFile ./README.md;
 
   roles.default = {
-
+    description = "Placeholder role to apply the trusted-nix-caches service";
     perInstance =
       { ... }:
       {

clanServices/users/default.nix

@@ -10,6 +10,7 @@
   manifest.readme = builtins.readFile ./README.md;
 
   roles.default = {
+    description = "Placeholder role to apply the user service";
     interface =
       { lib, ... }:
       {

clanServices/wifi/README.md

@@ -0,0 +1,21 @@
+This module allows you to pre-configure WiFi networks for automatic connection.  
+Each attribute in `settings.network` serves as an internal identifier, not the actual SSID.  
+After defining your networks, you will be prompted for the SSID and password for each one.
+
+This module leverages NetworkManager for managing connections.
+
+```nix
+instances = {
+    wifi = {
+        module.name = "wifi";
+        module.input = "clan-core";
+
+        roles.default = {
+            machines."jon" = {
+                settings.networks.home = { };
+                settings.networks.work = { keyMgmt = "wpa-eap"; };
+            };
+        };
+    };
+};
+```

clanServices/wifi/default.nix

@@ -9,8 +9,11 @@ in
 {
   _class = "clan.service";
   manifest.name = "wifi";
+  manifest.description = "Pre configure wifi networks to connect to";
+  manifest.readme = builtins.readFile ./README.md;
 
   roles.default = {
+    description = "Placeholder role to apply the wifi service";
     interface = {
       options.networks = lib.mkOption {
         type = lib.types.attrsOf (
@@ -42,7 +45,18 @@ in
           )
         );
         default = { };
-        description = "Wifi networks to predefine";
+        example = {
+          home = { };
+          guest = {
+            autoConnect = false;
+            keyMgmt = "wpa-eap";
+          };
+        };
+        description = ''
+          List of wifi networks to configure for connection.
+          Each attribute name is an internal identifier (not the SSID).
+          For each network, you will be prompted to enter the SSID and password as secrets.
+        '';
       };
     };
 

clanServices/wireguard/default.nix

@@ -146,6 +146,7 @@ in
 
   # Peer options and configuration
   roles.peer = {
+    description = "A peer that connects to one or more controllers.";
     interface =
       { lib, ... }:
       {
@@ -261,6 +262,7 @@ in
 
   # Controller options and configuration
   roles.controller = {
+    description = "A controller that routes peer traffic. Must be publicly reachable.";
     interface =
       { lib, ... }:
       {

clanServices/yggdrasil/default.nix

@@ -5,6 +5,7 @@
   manifest.description = "Yggdrasil encrypted IPv6 routing overlay network";
 
   roles.default = {
+    description = "Placeholder role to apply the yggdrasil service";
     interface =
       { lib, ... }:
       {
@@ -88,7 +89,7 @@
               enable = true;
               openMulticastPort = true;
               # We don't need this option, because we persist our keys with
-              # vars by ourselfs. This option creates an unnessesary additional
+              # vars by ourselves. This option creates an unnecesary additional
               # systemd service to save/load the keys and should be removed
               # from the NixOS module entirely, as it can be replaced by the
               # (at the time of writing undocumented) PrivateKeyPath= setting.

clanServices/zerotier/default.nix

@@ -2,11 +2,12 @@
 {
   _class = "clan.service";
   manifest.name = "clan-core/zerotier";
-  manifest.description = "Configuration of the secure and efficient Zerotier VPN";
+  manifest.description = "Zerotier Mesh VPN Service for secure P2P networking between machines";
   manifest.categories = [ "Utility" ];
   manifest.readme = builtins.readFile ./README.md;
 
   roles.peer = {
+    description = "A peer that connects to your private Zerotier network.";
     perInstance =
       {
         instanceName,
@@ -51,6 +52,7 @@
   };
 
   roles.moon = {
+    description = "A moon acts as a relay node to connect other nodes in the zerotier network that are not publicly reachable. Each moon must be publicly reachable.";
     interface =
       { lib, ... }:
       {
@@ -101,6 +103,7 @@
   };
 
   roles.controller = {
+    description = "Manages network membership and is responsible for admitting new peers to your Zerotier network.";
     interface =
       { lib, ... }:
       {

devFlake/flake.lock

@@ -3,21 +3,42 @@
     "clan-core-for-checks": {
       "flake": false,
       "locked": {
-        "lastModified": 1756166884,
-        "narHash": "sha256-skg4rwpbCjhpLlrv/Pndd43FoEgrJz98WARtGLhCSzo=",
-        "ref": "main",
-        "rev": "f7414d7e6e58709af27b6fe16eb530278e81eaaf",
+        "lastModified": 1760368011,
+        "narHash": "sha256-mLK2nwbfklfOGIVAKVNDwGyYz8mPh4fzsAqSK3BlCiI=",
+        "ref": "clan-25.05",
+        "rev": "1b3c129aa9741d99b27810652ca888b3fbfc3a11",
         "shallow": true,
         "type": "git",
         "url": "https://git.clan.lol/clan/clan-core"
       },
       "original": {
-        "ref": "main",
+        "ref": "clan-25.05",
         "shallow": true,
         "type": "git",
         "url": "https://git.clan.lol/clan/clan-core"
       }
     },
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": [
+          "test-fixtures",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1741352980,
+        "narHash": "sha256-+u2UunDA4Cl5Fci3m7S643HzKmIDAe+fiXrLqYsR2fs=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "f4330d22f1c5d2ba72d3d22df5597d123fdb60a9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
     "flake-utils": {
       "inputs": {
         "systems": [
@@ -84,16 +105,16 @@
     },
     "nixpkgs-dev": {
       "locked": {
-        "lastModified": 1758573205,
-        "narHash": "sha256-0ybDco+HjG5h46wx7ww4JIyg3y/mBDgkMCVX/Ua0e/Q=",
+        "lastModified": 1760309387,
+        "narHash": "sha256-e0lvQ7+B1Y8zjykYHAj9tBv10ggLqK0nmxwvMU3J0Eo=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "803b1683f562edc00665874bf98c1aad0b111482",
+        "rev": "6cd95994a9c8f7c6f8c1f1161be94119afdcb305",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixos-unstable-small",
+        "ref": "nixos-25.05-small",
         "repo": "nixpkgs",
         "type": "github"
       }
@@ -107,11 +128,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1758272005,
-        "narHash": "sha256-1u3xTH+3kaHhztPmWtLAD8LF5pTYLR2CpsPFWTFnVtQ=",
+        "lastModified": 1758662783,
+        "narHash": "sha256-igrxT+/MnmcftPOHEb+XDwAMq3Xg1Xy7kVYQaHhPlAg=",
         "owner": "NuschtOS",
         "repo": "search",
-        "rev": "aa975a3757f28ce862812466c5848787b868e116",
+        "rev": "7d4c0fc4ffe3bd64e5630417162e9e04e64b27a4",
         "type": "github"
       },
       "original": {
@@ -127,6 +148,7 @@
         "nixpkgs-dev": "nixpkgs-dev",
         "nuschtos": "nuschtos",
         "systems": "systems_2",
+        "test-fixtures": "test-fixtures",
         "treefmt-nix": "treefmt-nix"
       }
     },
@@ -160,16 +182,37 @@
         "type": "github"
       }
     },
+    "test-fixtures": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "nixpkgs": [
+          "nixpkgs-dev"
+        ]
+      },
+      "locked": {
+        "lastModified": 1742806412,
+        "narHash": "sha256-ZoAN0/sHEHY+ymJnkdkBAuZ/6sc66RYR4xMHpLf7++E=",
+        "ref": "refs/heads/main",
+        "rev": "4a2bc56d886578124b05060d3fb7eddc38c019f8",
+        "revCount": 2,
+        "type": "git",
+        "url": "https://git.clan.lol/clan/test-fixtures"
+      },
+      "original": {
+        "type": "git",
+        "url": "https://git.clan.lol/clan/test-fixtures"
+      }
+    },
     "treefmt-nix": {
       "inputs": {
         "nixpkgs": []
       },
       "locked": {
-        "lastModified": 1758206697,
-        "narHash": "sha256-/DbPkh6PZOgfueCbs3uzlk4ASU2nPPsiVWhpMCNkAd0=",
+        "lastModified": 1760120816,
+        "narHash": "sha256-gq9rdocpmRZCwLS5vsHozwB6b5nrOBDNc2kkEaTXHfg=",
         "owner": "numtide",
         "repo": "treefmt-nix",
-        "rev": "128222dc911b8e2e18939537bed1762b7f3a04aa",
+        "rev": "761ae7aff00907b607125b2f57338b74177697ed",
         "type": "github"
       },
       "original": {

devFlake/flake.nix

@@ -2,7 +2,7 @@
   description = "private dev inputs";
 
   # Dev dependencies
-  inputs.nixpkgs-dev.url = "github:NixOS/nixpkgs/nixos-unstable-small";
+  inputs.nixpkgs-dev.url = "github:NixOS/nixpkgs/nixos-25.05-small";
 
   inputs.flake-utils.url = "github:numtide/flake-utils";
   inputs.flake-utils.inputs.systems.follows = "systems";
@@ -15,8 +15,11 @@
 
   inputs.systems.url = "github:nix-systems/default";
 
-  inputs.clan-core-for-checks.url = "git+https://git.clan.lol/clan/clan-core?ref=main&shallow=1";
+  inputs.clan-core-for-checks.url = "git+https://git.clan.lol/clan/clan-core?ref=clan-25.05&shallow=1";
   inputs.clan-core-for-checks.flake = false;
 
+  inputs.test-fixtures.url = "git+https://git.clan.lol/clan/test-fixtures";
+  inputs.test-fixtures.inputs.nixpkgs.follows = "nixpkgs-dev";
+
   outputs = inputs: inputs;
 }

docs/.gitignore

@@ -1,5 +1,6 @@
 /site/reference
+/site/services/official
 /site/static
-/site/options
+/site/option-search
 /site/openapi.json
 !/site/static/extra.css

docs/CONTRIBUTING.md

@@ -1,6 +1,5 @@
 # Contributing to Clan
 
-
 **Continuous Integration (CI)**: Each pull request gets automatically tested by gitea. If any errors are detected, it will block pull requests until they're resolved.
 
 **Dependency Management**: We use the [Nix package manager](https://nixos.org/) to manage dependencies and ensure reproducibility, making your development process more robust.
@@ -10,25 +9,27 @@
 - Linux
 - macOS
 
-# Getting Started with the Development Environment
+## Getting Started with the Development Environment
 
 Let's get your development environment up and running:
 
 1. **Install Nix Package Manager**:
 
       - You can install the Nix package manager by either [downloading the Nix installer](https://github.com/DeterminateSystems/nix-installer/releases) or running this command:
-        ```bash
-        curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-        ```
 
-1. **Install direnv**:
+      ```bash
+      curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
+      ```
+
+2. **Install direnv**:
 
       - To automatically setup a devshell on entering the directory
-        ```bash
-        nix profile install nixpkgs#nix-direnv-flakes nixpkgs#direnv
-        ```
 
-1. **Add direnv to your shell**:
+      ```bash
+      nix profile install nixpkgs#nix-direnv-flakes nixpkgs#direnv
+      ```
+
+3. **Add direnv to your shell**:
 
       - Direnv needs to [hook into your shell](https://direnv.net/docs/hook.html) to work.
         You can do this by executing following command. The example below will setup direnv for `zsh` and `bash`
@@ -37,34 +38,43 @@ Let's get your development environment up and running:
       echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && eval "$SHELL"
       ```
 
-1. **Allow the devshell**
+4. **Allow the devshell**
       - Go to `clan-core/pkgs/clan-cli` and do a `direnv allow` to setup the necessary development environment to execute the `clan` command
 
-1. **Create a Gitea Account**:
+5. **Create a Gitea Account**
+
       - Register an account on https://git.clan.lol
       - Fork the [clan-core](https://git.clan.lol/clan/clan-core) repository
       - Clone the repository and navigate to it
-      - Add a new remote called upstream:
-         ```bash
-         git remote add upstream gitea@git.clan.lol:clan/clan-core.git
-         ```
-1. **Allow .envrc**:
+      - Add a new remote called upstream
+
+      ```bash
+      git remote add upstream gitea@git.clan.lol:clan/clan-core.git
+      ```
+
+7. **Allow .envrc**
 
       - When you enter the directory, you'll receive an error message like this:
-        ```bash
-        direnv: error .envrc is blocked. Run `direnv allow` to approve its content
-        ```
+
+      ```bash
+      direnv: error .envrc is blocked. Run `direnv allow` to approve its content
+      ```
+
       - Execute `direnv allow` to automatically execute the shell script `.envrc` when entering the directory.
 
-1. **(Optional) Install Git Hooks**:
+8. **(Optional) Install Git Hooks**
+
       - To syntax check your code you can run:
-         ```bash
-         nix fmt
-         ```
+
+      ```bash
+      nix fmt
+      ```
+
       - To make this automatic install the git hooks
-         ```bash
-         ./scripts/pre-commit
-         ```
+
+      ```bash
+      ./scripts/pre-commit
+      ```
 
 ## Related Projects
 
@@ -73,7 +83,7 @@ Let's get your development environment up and running:
 - **Nixos Anywhere**: [nixos-anywhere](https://github.com/nix-community/nixos-anywhere)
 - **Disko**: [disko](https://github.com/nix-community/disko)
 
-## Fixing Bugs or Adding Features in Clan-CLI
+### Override related projects for local development
 
 If you have a bug fix or feature that involves a related project, clone the relevant repository and replace its invocation in your local setup.
 
@@ -102,10 +112,10 @@ run(
 
 ```
 
-The <path_to_local_src> doesn't need to be a local path, it can be any valid [flakeref](https://nix.dev/manual/nix/2.26/command-ref/new-cli/nix3-flake.html#flake-references).
+The `<path_to_local_src>` doesn't need to be a local path, it can be any valid [flakeref](https://nix.dev/manual/nix/2.26/command-ref/new-cli/nix3-flake.html#flake-references).
 And thus can point to test already opened PRs for example.
 
-# Standards
+## Standards
 
 - Every new module name should be in kebab-case.
 - Every fact definition, where possible should be in kebab-case.

docs/README.md

@@ -1,5 +1,5 @@
 # Serve documentation locally
 
 ```
-$ nix develop .#docs -c mkdocs serve
+nix develop .#docs -c mkdocs serve
 ```

docs/main.py

@@ -1,41 +0,0 @@
-from typing import Any
-
-
-def define_env(env: Any) -> None:
-    static_dir = "/static/"
-    video_dir = "https://clan.lol/" + "videos/"
-    asciinema_dir = static_dir + "asciinema-player/"
-
-    @env.macro
-    def video(name: str) -> str:
-        return f"""<video loop muted autoplay id="{name}">
-                <source src={video_dir + name} type="video/webm">
-                Your browser does not support the video tag.
-            </video>"""
-
-    @env.macro
-    def asciinema(name: str) -> str:
-        return f"""<div id="{name}">
-            <script>
-                // Function to load the script and then create the Asciinema player
-                function loadAsciinemaPlayer() {{
-                    var script = document.createElement('script');
-                    script.src = "{asciinema_dir}/asciinema-player.min.js";
-                    script.onload = function() {{
-                        AsciinemaPlayer.create('{video_dir + name}', document.getElementById("{name}"), {{
-                            loop: true,
-                            autoPlay: true,
-                            controls: false,
-                            speed: 1.5,
-                            theme: "solarized-light"
-                    }});
-                    }};
-                    document.head.appendChild(script);
-                }}
-
-                // Load the Asciinema player script
-                loadAsciinemaPlayer();
-            </script>
-
-            <link rel="stylesheet" type="text/css" href="{asciinema_dir}/asciinema-player.css" />
-        </div>"""

docs/mkdocs.yml

@@ -47,26 +47,26 @@ exclude_docs: |
 nav:
   - Getting Started:
       - Overview: index.md
-      - Creating Your First Clan: guides/getting-started/index.md
-      - Add Machines: guides/getting-started/add-machines.md
-      - Add User: guides/getting-started/add-user.md
-      - Add Services: guides/getting-started/add-services.md
+      - getting-started/creating-your-first-clan.md
+      - getting-started/add-machines.md
+      - getting-started/add-users.md
+      - getting-started/add-services.md
       - Deploy to Physical Machine:
-          - Create USB Installer: guides/getting-started/create-installer.md
-          - Deploy Physical Machine: guides/getting-started/hardware-report-physical.md
-      - Deploy to Virtual Machine: guides/getting-started/hardware-report-virtual.md
-      - Configure Disk Config: guides/getting-started/choose-disk.md
-      - Update Machine: guides/getting-started/update.md
-      - Continuous Integration: guides/getting-started/flake-check.md
-      - Convert Existing NixOS Config: guides/getting-started/convert-flake.md
+          - getting-started/deploy-to-physical-machine/flash-installer.md
+          - getting-started/deploy-to-physical-machine/install-machine.md
+      - getting-started/deploy-to-virtual-machine.md
+      - getting-started/configure-disk.md
+      - getting-started/update-machines.md
+      - getting-started/continuous-integration.md
+      - Convert existing NixOS configurations: getting-started/convert-existing-NixOS-configuration.md
   - Guides:
       - Inventory:
           - Introduction to Inventory: guides/inventory/inventory.md
           - File Autoincludes: guides/inventory/autoincludes.md
-
-      - Clan Services:
-          - Inventory Guide: guides/inventory/clanServices.md
+      - Services:
+          - Introduction to Services: guides/services/introduction-to-services.md
           - Author Your Own Service: guides/services/community.md
+          - Internal Services with SSL: guides/internal-ssl-services.md
       - Vars:
           - Introduction to Vars: guides/vars/vars-overview.md
           - Minimal Example: guides/vars/vars-backend.md
@@ -76,37 +76,40 @@ nav:
           - Sops Backend:
               - Yubikeys & Age Plugins: guides/vars/sops/age-plugins.md
           - Managing Users (OLD): guides/secrets.md
+      - Backups:
+          - Introduction to Backups: guides/backups/backup-intro.md
+          - Minimal Example: guides/backups/minimal-example.md
+          - Digging Deeper: guides/backups/digging-deeper.md
+          - Advanced Example: guides/backups/advanced-example.md
       - Networking:
           - Introduction to Networking: guides/networking/networking.md
           - Zerotier VPN: guides/networking/mesh-vpn.md
-      - Disko Templates:
-          - Community Disko Templates: guides/disko-templates/community.md
-      - Backups:
-          - Introduction to Backups: guides/backups.md
+      - Nixpkgs Flake Input: guides/nixpkgs-flake-input/index.md
       - Flake-parts: guides/flake-parts.md
       - NixOS Rebuild: guides/nixos-rebuild.md
-      - macOS:
-          - Managing macOS Machines: guides/macos.md
+      - macOS: guides/macos.md
       # Should be part of the respective sections above
       # machines, disko, clan
-      - Templates: concepts/templates.md
+      - Templates:
+          - Introduction to Templates: concepts/templates.md
+          - Community Disko Templates: guides/disko-templates/community.md
       - Migrations:
-          - clan modules --> clan services: guides/migrations/migrate-inventory-services.md
-          - Facts --> Vars: guides/migrations/migration-facts-vars.md
+          - clan modules to clan services: guides/migrations/migrate-inventory-services.md
+          - Facts to Vars: guides/migrations/migration-facts-vars.md
           - Disk id: guides/migrations/disk-id.md
       - Disk Encryption: guides/disk-encryption.md
       - Disable Secure Boot: guides/secure-boot.md
       - Contributing:
-          - Hacking: guides/contributing/CONTRIBUTING.md
-          - Advanced Debugging: guides/contributing/debugging.md
-          - Testing: guides/contributing/testing.md
+          - guides/contributing/CONTRIBUTING.md
+          - guides/contributing/debugging.md
+          - guides/contributing/testing.md
 
   - Reference:
       - Overview: reference/index.md
-      - Clan Options: reference/options/clan.md
-      - Clan Inventory Options: reference/options/clan_inventory.md
-
-      - Clan Service API: reference/clanServices/clan-service-author-interface.md
+      - Options:
+          - reference/options/clan.md
+          - reference/options/clan_inventory.md
+          - reference/options/clan_service.md
 
       - clan.core (Machine Options):
           - Overview: reference/clan.core/index.md
@@ -140,43 +143,44 @@ nav:
       - HTTP API: api.md
 
       - Decisions:
-          - Architecture Decisions: decisions/README.md
-          - 01-clanModules: decisions/01-ClanModules.md
-          - 02-clan-api: decisions/02-clan-api.md
-          - 03-adr-numbering-process: decisions/03-adr-numbering-process.md
-          - 04-fetching-nix-from-python: decisions/04-fetching-nix-from-python.md
-          - 05-deployment-parameters: decisions/05-deployment-parameters.md
-          - Template: decisions/_template.md
+          - decisions/Architecture-decisions.md
+          - decisions/01-Clan-Modules.md
+          - decisions/02-clan-as-library.md
+          - decisions/03-adr-numbering-process.md
+          - decisions/04-fetching-nix-from-python.md
+          - decisions/05-deployment-parameters.md
+          - decisions/template.md
       - Glossary: reference/glossary.md
   - Services:
-      - Introduction to ClanServices: reference/clanServices/index.md
+      - services/definition.md
+      # Generated list from the list of official services
       - Official:
-          - reference/clanServices/admin.md
-          - reference/clanServices/borgbackup.md
-          - reference/clanServices/certificates.md
-          - reference/clanServices/coredns.md
-          - reference/clanServices/data-mesher.md
-          - reference/clanServices/dyndns.md
-          - reference/clanServices/emergency-access.md
-          - reference/clanServices/garage.md
-          - reference/clanServices/hello-world.md
-          - reference/clanServices/importer.md
-          - reference/clanServices/localbackup.md
-          - reference/clanServices/matrix-synapse.md
-          - reference/clanServices/mycelium.md
-          - reference/clanServices/monitoring.md
-          - reference/clanServices/packages.md
-          - reference/clanServices/sshd.md
-          - reference/clanServices/syncthing.md
-          - reference/clanServices/trusted-nix-caches.md
-          - reference/clanServices/users.md
-          - reference/clanServices/wifi.md
-          - reference/clanServices/wireguard.md
-          - reference/clanServices/yggdrasil.md
-          - reference/clanServices/zerotier.md
-      - Community: community/services/index.md
+          - services/official/admin.md
+          - services/official/borgbackup.md
+          - services/official/certificates.md
+          - services/official/coredns.md
+          - services/official/data-mesher.md
+          - services/official/dyndns.md
+          - services/official/emergency-access.md
+          - services/official/garage.md
+          - services/official/hello-world.md
+          - services/official/importer.md
+          - services/official/localbackup.md
+          - services/official/matrix-synapse.md
+          - services/official/mycelium.md
+          - services/official/monitoring.md
+          - services/official/packages.md
+          - services/official/sshd.md
+          - services/official/syncthing.md
+          - services/official/trusted-nix-caches.md
+          - services/official/users.md
+          - services/official/wifi.md
+          - services/official/wireguard.md
+          - services/official/yggdrasil.md
+          - services/official/zerotier.md
+      - services/community.md
 
-  - Search Clan Options: "/options"
+  - Search Clan Options: "/option-search"
 
 docs_dir: site
 site_dir: out
@@ -230,7 +234,7 @@ extra:
     - icon: fontawesome/brands/github
       link: https://github.com/clan-lol/clan-core
     - icon: fontawesome/solid/rss
-      link: /feed_rss_created.xml
+      link: https://clan.lol/feed.xml
 
 plugins:
   - search

docs/nix/default.nix

@@ -3,11 +3,9 @@
   module-docs,
   clan-cli-docs,
   clan-lib-openapi,
-  asciinema-player-js,
-  asciinema-player-css,
   roboto,
   fira-code,
-  docs-options,
+  option-search,
   ...
 }:
 let
@@ -44,22 +42,18 @@ pkgs.stdenv.mkDerivation {
     pushd docs
 
     mkdir -p ./site/reference/cli
-    cp -af ${module-docs}/* ./site/reference/
+    cp -af ${module-docs}/services/* ./site/services/
+    cp -af ${module-docs}/reference/* ./site/reference/
     cp -af ${clan-cli-docs}/* ./site/reference/cli/
 
-    mkdir -p ./site/reference/internal
     cp -af ${clan-lib-openapi} ./site/openapi.json
 
-    chmod -R +w ./site/reference
+    chmod -R +w ./site
     echo "Generated API documentation in './site/reference/' "
 
-    rm -rf ./site/options
-    cp -r ${docs-options} ./site/options
-    chmod -R +w ./site/options
-
-    mkdir -p ./site/static/asciinema-player
-    ln -snf ${asciinema-player-js} ./site/static/asciinema-player/asciinema-player.min.js
-    ln -snf ${asciinema-player-css} ./site/static/asciinema-player/asciinema-player.css
+    rm -rf ./site/option-search
+    cp -r ${option-search} ./site/option-search
+    chmod -R +w ./site/option-search
 
     # Link to fonts
     ln -snf ${roboto}/share/fonts/truetype/Roboto-Regular.ttf ./site/static/

docs/nix/flake-module.nix

@@ -1,8 +1,5 @@
-{ inputs, self, ... }:
+{ inputs, ... }:
 {
-  imports = [
-    ./options/flake-module.nix
-  ];
   perSystem =
     {
       config,
@@ -10,86 +7,14 @@
       pkgs,
       ...
     }:
-    let
-      # Simply evaluated options (JSON)
-      # { clanCore = «derivation JSON»; clanModules = { ${name} = «derivation JSON» }; }
-      jsonDocs = pkgs.callPackage ./get-module-docs.nix {
-        inherit (self) clanModules;
-        clan-core = self;
-        inherit pkgs;
-      };
-
-      # clan service options
-      clanModulesViaService = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesViaService);
-
-      # Simply evaluated options (JSON)
-      renderOptions =
-        pkgs.runCommand "render-options"
-          {
-            # TODO: ruff does not splice properly in nativeBuildInputs
-            depsBuildBuild = [ pkgs.ruff ];
-            nativeBuildInputs = [
-              pkgs.python3
-              pkgs.mypy
-              self'.packages.clan-cli
-            ];
-          }
-          ''
-            install -D -m755 ${./render_options}/__init__.py $out/bin/render-options
-            patchShebangs --build $out/bin/render-options
-
-            ruff format --check --diff $out/bin/render-options
-            ruff check --line-length 88 $out/bin/render-options
-            mypy --strict $out/bin/render-options
-          '';
-
-      asciinema-player-js = pkgs.fetchurl {
-        url = "https://github.com/asciinema/asciinema-player/releases/download/v3.7.0/asciinema-player.min.js";
-        sha256 = "sha256-Ymco/+FinDr5YOrV72ehclpp4amrczjo5EU3jfr/zxs=";
-      };
-      asciinema-player-css = pkgs.fetchurl {
-        url = "https://github.com/asciinema/asciinema-player/releases/download/v3.7.0/asciinema-player.css";
-        sha256 = "sha256-GZMeZFFGvP5GMqqh516mjJKfQaiJ6bL38bSYOXkaohc=";
-      };
-
-      module-docs =
-        pkgs.runCommand "rendered"
-          {
-            buildInputs = [
-              pkgs.python3
-              self'.packages.clan-cli
-            ];
-          }
-          ''
-            export CLAN_CORE_PATH=${
-              inputs.nixpkgs.lib.fileset.toSource {
-                root = ../..;
-                fileset = ../../clanModules;
-              }
-            }
-            export CLAN_CORE_DOCS=${jsonDocs.clanCore}/share/doc/nixos/options.json
-
-            # A file that contains the links to all clanModule docs
-            export CLAN_MODULES_VIA_SERVICE=${clanModulesViaService}
-            export CLAN_SERVICE_INTERFACE=${self'.legacyPackages.clan-service-module-interface}/share/doc/nixos/options.json
-            export CLAN_OPTIONS_PATH=${self'.legacyPackages.clan-options}/share/doc/nixos/options.json
-
-            mkdir $out
-
-            # The python script will place mkDocs files in the output directory
-            exec python3 ${renderOptions}/bin/render-options
-          '';
-    in
     {
-      legacyPackages = {
-        inherit
-          jsonDocs
-          clanModulesViaService
-          ;
-      };
       devShells.docs = self'.packages.docs.overrideAttrs (_old: {
-        nativeBuildInputs =
-          self'.devShells.default.nativeBuildInputs ++ self'.packages.docs.nativeBuildInputs;
+        nativeBuildInputs = [
+          # Run: htmlproofer --disable-external
+          pkgs.html-proofer
+        ]
+        ++ self'.devShells.default.nativeBuildInputs
+        ++ self'.packages.docs.nativeBuildInputs;
         shellHook = ''
           ${self'.devShells.default.shellHook}
           git_root=$(git rev-parse --show-toplevel)
@@ -101,17 +26,27 @@
         docs = pkgs.python3.pkgs.callPackage ./default.nix {
           inherit (self'.packages)
             clan-cli-docs
-            docs-options
+            option-search
             inventory-api-docs
             clan-lib-openapi
+            module-docs
             ;
           inherit (inputs) nixpkgs;
-          inherit module-docs;
-          inherit asciinema-player-js;
-          inherit asciinema-player-css;
         };
         deploy-docs = pkgs.callPackage ./deploy-docs.nix { inherit (config.packages) docs; };
-        inherit module-docs;
       };
+      checks.docs-integrity =
+        pkgs.runCommand "docs-integrity"
+          {
+            nativeBuildInputs = [ pkgs.html-proofer ];
+            LANG = "C.UTF-8";
+          }
+          ''
+            # External links should be avoided in the docs, because they often break
+            # and we cannot statically control them. Thus we disable checking them
+            htmlproofer --disable-external ${self'.packages.docs}
+
+            touch $out
+          '';
     };
 }

docs/release-notes.md

@@ -0,0 +1,9 @@
+# clan-core release notes 25.11
+
+<!-- This is not rendered yet -->
+
+## New features
+
+## Breaking Changes
+
+## Misc

docs/site/decisions/01-Clan-Modules.md

@@ -1,5 +1,3 @@
-# Clan service modules
-
 ## Status
 
 Accepted

docs/site/decisions/02-clan-as-library.md

@@ -1,5 +1,3 @@
-# Clan as library
-
 ## Status
 
 Accepted

docs/site/decisions/03-adr-numbering-process.md

@@ -1,5 +1,3 @@
-# ADR Numbering process
-
 ## Status
 
 Proposed after some conversation between @lassulus, @Mic92, & @lopter.

docs/site/decisions/05-deployment-parameters.md

@@ -1,5 +1,3 @@
-# deployment parameters: evalHost, buildHost, targetHost
-
 ## Status
 
 accepted

docs/site/decisions/Architecture-decisions.md

@@ -1,5 +1,3 @@
-# Architecture Decision Records
-
 This section contains the architecture decisions that have been reviewed and generally agreed upon
 
 ## What is an ADR?
@@ -11,6 +9,6 @@ This section contains the architecture decisions that have been reviewed and gen
 
 ## Crafting a new ADR
 
-1. Use the [template](./_template.md)
+1. Use the [template](../decisions/template.md)
 2. Create the Pull request and gather feedback
-3. Retreive your adr-number (see: [numbering](./03-adr-numbering-process.md))
+3. Retreive your adr-number (see: [numbering](../decisions/03-adr-numbering-process.md))

docs/site/decisions/template.md

@@ -1,6 +1,6 @@
-# Decision record template by Michael Nygard
+## Decision record template by Michael Nygard
 
-This is the template in [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+This is the template in [Documenting architecture decisions - Michael Nygard](https://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
 You can use [adr-tools](https://github.com/npryce/adr-tools) for managing the ADR files.
 
 In each ADR file, write these sections:

docs/site/getting-started/add-machines.md

@@ -1,12 +1,10 @@
-# How to add machines
-
 Machines can be added using the following methods
 
-- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../inventory/autoincludes.md))
+- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../guides/inventory/autoincludes.md))
 - Imperative via cli command: `clan machines create`
-- Editing nix expressions in flake.nix See [`clan-core.lib.clan`](/options/?scope=Flake Options (clan.nix file))
+- Editing nix expressions in flake.nix See [`clan-core.lib.clan`](../reference/options/clan.md)
 
-See the complete [list](../inventory/autoincludes.md) of auto-loaded files.
+See the complete [list](../guides/inventory/autoincludes.md) of auto-loaded files.
 
 ## Create a machine
 
@@ -20,8 +18,6 @@ See the complete [list](../inventory/autoincludes.md) of auto-loaded files.
         };
 
         # Additional NixOS configuration can be added here.
-        # machines/jon/configuration.nix will be automatically imported.
-        # See: https://docs.clan.lol/guides/more-machines/#automatic-registration
         machines = {
             # jon = { config, ... }: {
             #   environment.systemPackages = [ pkgs.asciinema ];

docs/site/getting-started/add-services.md

@@ -1,5 +1,3 @@
-# How to add services
-
 A service in clan is a self-contained, reusable unit of system configuration that provides a specific piece of functionality across one or more machines.
 
 Think of it as a recipe for running a tool — like automatic backups, VPN networking, monitoring, etc.
@@ -10,7 +8,7 @@ In Clan Services are multi-Host & role-based:
 
 - You can use tags instead of explicit machine names.
 
-To learn more: [Guide about clanService](../inventory/clanServices.md)
+To learn more: [Guide about clanService](../guides/services/introduction-to-services.md)
 
 !!! Important
     It is recommended to add at least one networking service such as `zerotier` that allows to reach all your clan machines from your setup computer across the globe.
@@ -40,8 +38,8 @@ To learn more: [Guide about clanService](../inventory/clanServices.md)
 }
 ```
 
-1. See [reference/clanServices](../../reference/clanServices/index.md) for all available services and how to configure them.
-   Or read [authoring/clanServices](../services/community.md) if you want to bring your own
+1. See [services/official](../services/definition.md) for all available services and how to configure them.
+   Or read [guides/services](../guides/services/community.md) if you want to bring your own
 
 2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine.
 
@@ -73,5 +71,5 @@ Adding the following services is recommended for most users:
 ```
 
 1. The `admin` service will generate a **root-password** and **add your ssh-key** that allows for convienient administration.
-2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](./add-machines.md#configuring-a-machine)
+2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](../getting-started/add-machines.md#configuring-a-machine)
 3. Adds `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment.

docs/site/getting-started/add-users.md

@@ -1,19 +1,17 @@
-# How to add users
-
 !!! Note "Under construction"
 
 The users concept of clan is not done yet. This guide outlines some solutions from our community.
 Defining users can be done in many different ways. We want to highlight two approaches:
 
-- Using clan's [users](../../reference/clanServices/users.md) service.
+- Using clan's [users](../services/official/users.md) service.
 - Using a custom approach.
 
-## Adding Users using the [users](../../reference/clanServices/users.md) service
+## Adding Users using the [users](../services/official/users.md) service
 
 To add a first *user* this guide will be leveraging two things:
 
-- [clanServices](../../reference/clanServices/index.md): Allows to bind arbitrary logic to something we call an `ìnstance`.
-- [clanServices/users](../../reference/clanServices/users.md): Implements logic for adding a single user perInstance.
+- [services](../services/definition.md): Allows to bind arbitrary logic to something we call an `ìnstance`.
+- [services/users](../services/official/users.md): Implements logic for adding a single user perInstance.
 
 The example shows how to add a user called `jon`:
 
@@ -51,7 +49,7 @@ The example shows how to add a user called `jon`:
 
 The `users` service creates a `/home/jon` directory, allows `jon` to sign in and will take care of the user's password.
 
-For more information see [clanService/users](../../reference/clanServices/users.md)
+For more information see [services/users](../services/official/users.md)
 
 ## Using a custom approach
 

docs/site/getting-started/configure-disk.md

@@ -1,5 +1,3 @@
-# Configure Disk Config
-
 By default clan uses [disko](https://github.com/nix-community/disko) which allows for declarative disk partitioning.
 
 To see what disk templates are available run:
@@ -64,9 +62,9 @@ You can have a look and customize it if needed.
 
 ## Deploy the machine
 
-**Finally deployment time!** 
+**Finally deployment time!**
 
-This command is destructive and will format your disk and install NixOS on it! It is equivalent to appending `--phases kexec,disko,install,reboot`. 
+This command is destructive and will format your disk and install NixOS on it! It is equivalent to appending `--phases kexec,disko,install,reboot`.
 
 
 ```bash

docs/site/getting-started/convert-existing-NixOS-configuration.md

@@ -1,19 +1,17 @@
-# Convert existing NixOS configurations
-
 This guide will help you convert your existing NixOS configurations into a Clan.
 
 !!! Warning
     Migrating instead of starting new can be trickier and might lead to bugs or
-    unexpected issues. We recommend reading the [Getting Started](./index.md) guide first.
+    unexpected issues. We recommend reading the [Getting Started](../getting-started/creating-your-first-clan.md) guide first.
 
-    Once you have a working setup and understand the concepts transfering your NixOS configurations over is easy.
+    Once you have a working setup and understand the concepts transferring your NixOS configurations over is easy.
 
 ## Back up your existing configuration
 
 Before you start, it is strongly recommended to back up your existing
 configuration in any form you see fit. If you use version control to manage
 your configuration changes, it is also a good idea to follow the migration
-guide in a separte branch until everything works as expected.
+guide in a separate branch until everything works as expected.
 
 ## Starting Point
 
@@ -171,7 +169,7 @@ Clan needs to know where it can reach your hosts. For testing purpose set
 }
 ```
 
-See our guide on for properly [configuring machines networking](../networking/networking.md)
+See our guide on for properly [configuring machines networking](../guides/networking/networking.md)
 
 ## Next Steps
 

docs/site/getting-started/creating-your-first-clan.md

@@ -1,6 +1,4 @@
-# :material-clock-fast: Getting Started
-
-Ready to manage your fleet of machines? 
+Ready to manage your fleet of machines?
 
 We will create a declarative infrastructure using **clan**, **git**, and **nix flakes**.
 
@@ -43,7 +41,7 @@ Make sure you have the following:
 ## Create a New Clan
 
 1. Navigate to your desired directory:
-    
+
     ```shellSession
     cd <your-directory>
     ```
@@ -76,7 +74,7 @@ my-clan/
 ```
 
 !!! note "Templates"
-    This is the structure for the `default` template. 
+    This is the structure for the `default` template.
 
     Use `clan templates list` and `clan templates --help` for available templates & more. Keep in mind that the exact files may change as templates evolve.
 
@@ -121,7 +119,7 @@ Name: __CHANGE_ME__
 Description: None
 ```
 
-This confirms your setup is working correctly. 
+This confirms your setup is working correctly.
 
 You can now change the default name by editing the `meta.name` field in your `clan.nix` file.
 

docs/site/getting-started/deploy-to-physical-machine/flash-installer.md

@@ -1,9 +1,7 @@
-# USB Installer Image for Physical Machines
-
 To install Clan on physical machines, you need to use our custom installer image. This is necessary for proper installation and operation.
 
 !!! note "Deploying to a Virtual Machine?"
-    If you're deploying to a virtual machine (VM), you can skip this section and go directly to the [Deploy Virtual Machine](./hardware-report-virtual.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime.
+    If you're deploying to a virtual machine (VM), you can skip this section and go directly to the [Deploy Virtual Machine](../../getting-started/deploy-to-virtual-machine.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime.
 
 ??? info "Why nixos-anywhere Doesn't Work on Physical Hardware?"
     nixos-anywhere relies on [kexec](https://wiki.archlinux.org/title/Kexec) to replace the running kernel with our custom one. This method often has compatibility issues with real hardware, especially systems with dedicated graphics cards like laptops and servers, leading to crashes and black screens.
@@ -152,7 +150,7 @@ sudo umount /dev/sdb1
 
 ## Boot From USB Stick
 
-- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](../secure-boot.md)
+- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](../../guides/secure-boot.md)
 
 ## (Optional) Connect to Wifi Manually
 

docs/site/getting-started/deploy-to-physical-machine/install-machine.md

@@ -1,18 +1,16 @@
-# Installing a Physical Machine
-
 Now that you have created a machine, added some services, and set up secrets, this guide will walk you through how to deploy it.
 
 
 ### Prerequisites
 - [x] RAM > 2GB
 - [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
-- [x] **Machine configuration**: See our basic [adding and configuring machine guide](./add-machines.md)
-- [x] **Initialized secrets**: See [secrets](../secrets.md) for how to initialize your secrets.
-- [x] **USB Flash Drive**: See [Clan Installer](./create-installer.md)
+- [x] **Machine configuration**: See our basic [adding and configuring machine guide](../../getting-started/add-machines.md)
+- [x] **Initialized secrets**: See [secrets](../../guides/secrets.md) for how to initialize your secrets.
+- [x] **USB Flash Drive**: See [Clan Installer](../../getting-started/deploy-to-physical-machine/flash-installer.md)
 
 
 ### Image Installer
-This method makes use of the [image installers](./create-installer.md).
+This method makes use of the [image installers](../../getting-started/deploy-to-physical-machine/flash-installer.md).
 
 The installer will randomly generate a password and local addresses on boot, then run a SSH server with these preconfigured.
 The installer shows its deployment relevant information in two formats, a text form, as well as a QR code.
@@ -68,7 +66,7 @@ This is an example of the booted installer.
     ```
 2.  The root password for the installer medium.
     This password is autogenerated and meant to be easily typeable.
-3.  See how to connect the installer medium to wlan [here](./create-installer.md).
+3.  See how to connect the installer medium to wlan [here](../../getting-started/deploy-to-physical-machine/flash-installer.md).
 
 !!!tip
     For easy sharing of deployment information via QR code, we highly recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/).
@@ -113,4 +111,4 @@ The following command will generate a hardware report with [nixos-facter](https:
 
 If you are using our template `[MACHINE]` would be `jon`
 
-[Next Step (Choose Disk Format)](./choose-disk.md){ .md-button .md-button--primary }
+[Next Step (Choose Disk Format)](../../getting-started/configure-disk.md){ .md-button .md-button--primary }

docs/site/getting-started/deploy-to-virtual-machine.md

@@ -1,12 +1,8 @@
-# Generate a VM Hardware Report
-
-Now that you have created a machine, added some services, and set up secrets, this guide will walk you through how to deploy it.
-
 
 ## Prerequisites
 - [x] RAM > 2GB
 - [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
-- [x] **Machine configuration**: See our basic [adding and configuring machine guide](./add-machines.md)
+- [x] **Machine configuration**: See our basic [adding and configuring machine guide](../getting-started/add-machines.md)
 
 
 Clan supports any cloud machine if it is reachable via SSH and supports `kexec`.

docs/site/getting-started/update-machines.md

@@ -1,4 +1,3 @@
-
 # Update Machines
 
 The Clan command line interface enables you to update machines remotely over SSH.
@@ -32,7 +31,7 @@ Ensure that the root login is secured and only used when necessary.
 
 ## Multiple Target Hosts
 
-You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](../networking/networking.md).
+You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](../guides/networking/networking.md).
 
 ## Updating Machine Configurations
 
@@ -79,7 +78,7 @@ clan {
 
 `buildHost` / `targetHost`, and other network settings can be temporarily overridden for a single command:
 
-For the full list of flags refer to the [Clan CLI](../../reference/cli/index.md)
+For the full list of flags refer to the [Clan CLI](../reference/cli/index.md)
 
 ```bash
 # Build on a remote host

docs/site/guides/backups.md

@@ -1,195 +0,0 @@
-This guide explains how to set up and manage
-[BorgBackup](https://borgbackup.readthedocs.io/) for secure, efficient backups
-in a clan network. BorgBackup provides:
-
-- Space efficient storage of backups with deduplication
-- Secure, authenticated encryption
-- Compression: lz4, zstd, zlib, lzma or none
-- Mountable backups with FUSE
-- Easy installation on multiple platforms: Linux, macOS, BSD, …
-- Free software (BSD license).
-- Backed by a large and active open-source community.
-
-## Borgbackup Example
-
-```nix
-inventory.instances = {
-  borgbackup = {
-    module = {
-      name = "borgbackup";
-      input = "clan-core";
-    };
-    roles.client.machines."jon".settings = {
-      destinations."storagebox" = {
-        repo = "username@$hostname:/./borgbackup";
-        rsh = ''ssh -oPort=23 -i /run/secrets/vars/borgbackup/borgbackup.ssh'';
-      };
-    };
-    roles.server.machines = { };
-  };
-};
-```
-
-The input should be named according to your flake input. Jon is configured as a
-client machine with a destination pointing to a Hetzner Storage Box.
-
-To see a list of all possible options go to [borgbackup clan service](../reference/clanServices/borgbackup.md)
-
-## Roles
-
-A Clan Service can have multiple roles, each role applies different nix config to the machine.
-
-### 1. Client
-
-Clients are machines that create and send backups to various destinations. Each
-client can have multiple backup destinations configured.
-
-### 2. Server
-
-Servers act as backup repositories, receiving and storing backups from client
-machines. They can be dedicated backup servers within your clan network.
-
-## Backup destinations
-
-This service allows you to perform backups to multiple `destinations`.
-Destinations can be:
-
-- **Local**: Local disk storage
-- **Server**: Your own borgbackup server (using the `server` role)
-- **Third-party services**: Such as Hetzner's Storage Box
-
-## State management
-
-Backups are based on [states](../reference/clan.core/state.md). A state
-defines which files should be backed up and how these files are obtained through
-pre/post backup and restore scripts.
-
-Here's an example for a user application `linkding`:
-
-In this example:
-
-- `/data/podman/linkding` is the application's data directory
-- `/var/backup/linkding` is the staging directory where data is copied for
-  backup
-
-```nix
-clan.core.state.linkding = {
-  folders = [ "/var/backup/linkding" ];
-
-  preBackupScript = ''
-    export PATH=${
-      lib.makeBinPath [
-        config.systemd.package
-        pkgs.coreutils
-        pkgs.rsync
-      ]
-    }
-
-    service_status=$(systemctl is-active podman-linkding)
-
-    if [ "$service_status" = "active" ]; then
-      systemctl stop podman-linkding
-      rsync -avH --delete --numeric-ids "/data/podman/linkding/" /var/backup/linkding/
-      systemctl start podman-linkding
-    fi
-  '';
-
-  postRestoreScript = ''
-    export PATH=${
-      lib.makeBinPath [
-        config.systemd.package
-        pkgs.coreutils
-        pkgs.rsync
-      ]
-    }
-
-    service_status="$(systemctl is-active podman-linkding)"
-
-    if [ "$service_status" = "active" ]; then
-      systemctl stop podman-linkding
-
-      # Backup locally current linkding data
-      cp -rp "/data/podman/linkding" "/data/podman/linkding.bak"
-
-      # Restore from borgbackup
-      rsync -avH --delete --numeric-ids /var/backup/linkding/ "/data/podman/linkding/"
-
-      systemctl start podman-linkding
-    fi
-  '';
-};
-```
-
-## Managing backups
-
-In this section we go over how to manage your collection of backups with the clan command.
-
-### Listing states
-
-To see which files (`states`) will be backed up on a specific machine, use:
-
-```bash
-clan state list jon
-```
-
-This will show all configured states for the machine `jon`, for example:
-
-```text
-· service: linkding
-  folders:
-  - /var/backup/linkding
-  preBackupCommand: pre-backup-linkding
-  postRestoreCommand: post-restore-linkding
-
-· service: zerotier
-  folders:
-  - /var/lib/zerotier-one
-```
-
-### Creating backups
-
-To create a backup of a machine (e.g., `jon`), run:
-
-```bash
-clan backups create jon
-```
-
-This will backup all configured states (`zerotier` and `linkding` in this
-example) from the machine `jon`.
-
-### Listing available backups
-
-To see all available backups, use:
-
-```bash
-clan backups list
-```
-
-This will display all backups with their timestamps:
-
-```text
-storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-22T19:40:10
-storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-23T01:00:00
-storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T01:00:00
-storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
-```
-
-### Restoring backups
-
-For restoring a backup you have two options.
-
-#### Full restoration
-
-To restore all services from a backup:
-
-```bash
-clan backups restore jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
-```
-
-#### Partial restoration
-
-To restore only a specific service (e.g., `linkding`):
-
-```bash
-clan backups restore --service linkding jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
-```

docs/site/guides/backups/advanced-example.md

@@ -0,0 +1,71 @@
+This guide explains how to set up a [Hetzner Storage Box](https://docs.hetzner.com/storage/storage-box/general) as a backup destination instead of using an internal Clan backup server. Follow the steps below to configure and verify the setup.
+
+### Step 1: Create a Hetzner Storage Box
+
+Begin by [creating a Hetzner Storage Box account](https://docs.hetzner.com/storage/storage-box/getting-started/creating-a-storage-box).
+
+### Step 2: Create a Sub-Account
+
+Set up a sub-account for your `jon` machine. Save the SSH password for this account in your password manager for future reference.
+
+### Step 3: Configure BorgBackup in `clan.nix`
+
+Add the BorgBackup service to your `clan.nix` configuration. In this example, the `jon` machine will back up to `user-sub1@user-sub1.your-storagebox.de` in the `borgbackup` folder:
+
+```nix hl_lines="9"
+inventory.instances = {
+  borgbackup = {
+    module = {
+      name = "borgbackup";
+      input = "clan-core";
+    };
+    roles.client.machines."jon".settings = {
+      destinations."storagebox" = {
+        repo = "user-sub1@user-sub1.your-storagebox.de:/./borgbackup";
+        rsh = ''ssh -p 23 -oStrictHostKeyChecking=accept-new -i /run/secrets/vars/borgbackup/borgbackup.ssh'';
+      };
+    };
+  };
+};
+```
+
+### Step 4: Generate SSH Keys
+
+Run the following command to generate the SSH private keys:
+
+```bash
+clan vars generate
+```
+
+### Step 5: Add the Public Key to the Sub-Account
+
+Add the generated SSH public key to the `user-sub1` account by running:
+
+```bash
+clan vars get jon borgbackup/borgbackup.ssh.pub | ssh -p23 user-sub1@user-sub1.your-storagebox.de install-ssh-key
+```
+
+### Step 6: Deploy the Configuration
+
+Apply the changes to your Clan setup by executing:
+
+```bash
+clan machines update
+```
+
+### Step 7: Verify the Setup
+
+Check if the configuration works by starting the BorgBackup service on the `jon` machine:
+
+```bash
+systemctl start borgbackup-job-storagebox.service &
+```
+
+Then, inspect the service logs to ensure everything is functioning correctly:
+
+```bash
+journalctl -u borgbackup-job-storagebox.service
+```
+
+
+

docs/site/guides/backups/backup-intro.md

@@ -0,0 +1,89 @@
+# Introduction to Clan Backups
+
+This guide explains how to use the Clan backup and state management interface to configure, manage, and restore backups for your services and machines. By the end of this guide, you will understand how to define backup states, manage backups, and restore data.
+
+## State Management
+
+Clan backups are based on the concept of [states](../../reference/clan.core/state.md). A state is a Nix attribute set, defined as `clan.core.state.<name> = {};`, which specifies the files or directories to back up.
+
+For example, if you have a clan service called `linkding`, you can define the folders to back up as follows:
+
+```nix hl_lines="2"
+clan.core.state.linkding = {
+  folders = [ "/var/backup/linkding" ];
+};
+```
+
+In this example:
+
+- `/var/backup/linkding` is the staging directory where data is prepared for backup.
+
+This simple configuration ensures that all critical data for the `linkding` service is included in the backup process.
+
+
+## Custom Pre and Post Backup Hooks
+
+The state interface allows you to run custom scripts before creating a backup and after restoring one. These scripts are defined using the `preBackupScript` and `postRestoreScript` options. This can be useful for tasks like stopping services, syncing data, or performing cleanup operations.
+
+### Example: Pre and Post Backup Scripts for the `linkding` Service
+
+In the following example, we configure the `linkding` service to:
+
+1. Stop the service before backing up its data.
+2. Sync the data to a staging directory.
+3. Restore the data and restart the service after restoration.
+
+```nix hl_lines="5 26"
+clan.core.state.linkding = {
+  folders = [ "/var/backup/linkding" ];
+
+  # Script to run before creating a backup
+  preBackupScript = ''
+    export PATH=${
+      lib.makeBinPath [
+        config.systemd.package
+        pkgs.coreutils
+        pkgs.rsync
+      ]
+    }
+
+    # Check if the service is running
+    service_status=$(systemctl is-active podman-linkding)
+
+    if [ "$service_status" = "active" ]; then
+      # Stop the service and sync data to the backup directory
+      systemctl stop podman-linkding
+      rsync -avH --delete --numeric-ids "/data/podman/linkding/" /var/backup/linkding/
+      systemctl start podman-linkding
+    fi
+  '';
+
+  # Script to run after restoring a backup
+  postRestoreScript = ''
+    export PATH=${
+      lib.makeBinPath [
+        config.systemd.package
+        pkgs.coreutils
+        pkgs.rsync
+      ]
+    }
+
+    # Check if the service is running
+    service_status="$(systemctl is-active podman-linkding)"
+
+    if [ "$service_status" = "active" ]; then
+      # Stop the service
+      systemctl stop podman-linkding
+
+      # Backup current data locally
+      cp -rp "/data/podman/linkding" "/data/podman/linkding.bak"
+
+      # Restore data from the backup directory
+      rsync -avH --delete --numeric-ids /var/backup/linkding/ "/data/podman/linkding/"
+
+      # Restart the service
+      systemctl start podman-linkding
+    fi
+  '';
+};
+```

docs/site/guides/backups/digging-deeper.md

@@ -0,0 +1,75 @@
+
+
+In this section we go over how to manage your collection of backups with the clan command.
+
+### Listing states
+
+To see which files (`states`) will be backed up on a specific machine, use:
+
+```bash
+clan state list jon
+```
+
+This will show all configured states for the machine `jon`, for example:
+
+```text
+· service: linkding
+  folders:
+  - /var/backup/linkding
+  preBackupCommand: pre-backup-linkding
+  postRestoreCommand: post-restore-linkding
+
+· service: zerotier
+  folders:
+  - /var/lib/zerotier-one
+```
+
+### Creating backups
+
+To create a backup of a machine (e.g., `jon`), run:
+
+```bash
+clan backups create jon
+```
+
+This will backup all configured states (`zerotier` and `linkding` in this
+example) from the machine `jon`.
+
+### Listing available backups
+
+To see all available backups, use:
+
+```bash
+clan backups list
+```
+
+This will display all backups with their timestamps:
+
+```text
+storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-22T19:40:10
+storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-23T01:00:00
+storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T01:00:00
+storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
+```
+
+### Restoring backups
+
+For restoring a backup you have two options.
+
+#### Full restoration
+
+To restore all services from a backup:
+
+```bash
+clan backups restore jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
+```
+
+#### Partial restoration
+
+To restore only a specific service (e.g., `linkding`):
+
+```bash
+clan backups restore --service linkding jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
+```
+
+

docs/site/guides/backups/minimal-example.md

@@ -0,0 +1,63 @@
+In this guide we will explain how to install a simple peer-to-peer backup system through the inventory. Such that machines will backup it's state to other machines in the clan, ensuring redundancy and data safety.
+
+
+### What is BorgBackup?
+
+BorgBackup is a powerful and efficient backup solution designed for secure and space-efficient backups. It offers features such as:
+
+- **Deduplication**: Saves storage space by avoiding duplicate data.
+- **Encryption**: Ensures backups are secure and authenticated.
+- **Compression**: Supports multiple compression algorithms like lz4, zstd, zlib, and more.
+- **FUSE Mounting**: Allows backups to be mounted as a file system.
+- **Cross-Platform**: Works on Linux, macOS, BSD, and more.
+- **Open Source**: Licensed under BSD and supported by an active community.
+
+
+While this guide uses BorgBackup, you can also use other backup services supported by Clan, depending on your requirements.
+
+
+### Example Setup
+
+In this example, we configure a backup system with three machines: `bob`, `jon`, and `alice`. The `bob` and `jon` machines will periodically back up their state folders to `alice`. The backups are encrypted for security.
+
+
+
+```nix
+inventory.instances = {
+  borgbackup = {
+    module = {
+      name = "borgbackup";
+      input = "clan-core";
+    };
+    roles.client.machines = {
+        "bob" = { };
+        "jon" = { };
+    };
+    roles.server.machines = { 
+        "alice" = { };
+    };
+  };
+};
+```
+
+
+## Roles
+
+In a Clan Service, roles define how machines participate in the backup system. Each role applies specific Nix configurations to the machine, enabling flexibility and scalability in your backup setup.
+
+- **Client**: These machines create backups and send them to designated destinations. Clients can be configured to back up to multiple destinations, ensuring redundancy and reliability.
+
+- **Server**: These machines act as repositories, receiving and securely storing backups from client machines. Servers can be dedicated backup nodes within your clan network, providing centralized storage for all backups.
+
+
+## Backup destinations
+
+This service allows you to perform backups to multiple `destinations`.
+Destinations can be:
+
+- **Local**: Local disk storage
+- **Server**: Your own borgbackup server (using the `server` role)
+- **Third-party services**: Such as Hetzner's Storage Box
+
+
+However, if BorgBackup does not meet your needs, you can implement your own backup clan service.

docs/site/guides/contributing/debugging.md

@@ -26,7 +26,7 @@ pkgs.mkShell {
 
 ## Debugging nixos-anywhere
 
-If you encounter a bug in a complex shell script such as `nixos-anywhere`, start by replacing the `nixos-anywhere` command with a local checkout of the project, look in the [contribution](./CONTRIBUTING.md) section for an example. 
+If you encounter a bug in a complex shell script such as `nixos-anywhere`, start by replacing the `nixos-anywhere` command with a local checkout of the project, look in the [contribution](../../guides/contributing/CONTRIBUTING.md) section for an example.
 
 ## The Debug Flag
 

docs/site/guides/contributing/testing.md

@@ -67,6 +67,59 @@ nix build .#checks.x86_64-linux.{test-attr-name}
 ```
 (replace `{test-attr-name}` with the name of the test)
 
+### Testing services with vars
+
+Services that define their own vars (using `clan.core.vars.generators`) require generating test vars before running the tests.
+
+#### Understanding the `clan.directory` setting
+
+The `clan.directory` option is critical for vars generation and loading in tests. This setting determines:
+
+1. **Where vars are generated**: When you run `update-vars`, it creates `vars/` and `sops/` directories inside the path specified by `clan.directory`
+2. **Where vars are loaded from**: During test execution, machines look for their vars and secrets relative to `clan.directory`
+
+#### Generating test vars
+
+For services that define vars, you must first run:
+
+```shellSession
+nix run .#checks.x86_64-linux.{test-attr-name}.update-vars
+```
+
+This generates the necessary var files in the directory specified by `clan.directory`. After running this command, you can run the test normally:
+
+```shellSession
+nix run .#checks.x86_64-linux.{test-attr-name}
+```
+
+#### Example: service-dummy-test
+
+The `service-dummy-test` is a good example of a test that uses vars. To run it:
+
+```shellSession
+# First, generate the test vars
+nix run .#checks.x86_64-linux.service-dummy-test.update-vars
+
+# Then run the test
+nix run .#checks.x86_64-linux.service-dummy-test
+```
+
+#### Common issues
+
+If `update-vars` fails, you may need to ensure that:
+
+- **`clan.directory` is set correctly**: It should point to the directory where you want vars to be generated (typically `clan.directory = ./.;` in your test definition)
+- **Your test defines machines**: Machines must be defined in `clan.inventory.machines` or through the inventory system
+- **Machine definitions are complete**: Each machine should have the necessary service configuration that defines the vars generators
+
+**If vars are not found during test execution:**
+
+- Verify that `clan.directory` points to the same location where you ran `update-vars`
+- Check that the `vars/` and `sops/` directories exist in that location
+- Ensure the generated files match the machines and generators defined in your test
+
+You can reference `/checks/service-dummy-test/` to see a complete working example of a test with vars, including the correct directory structure.
+
 ### Debugging VM tests
 
 The following techniques can be used to debug a VM test:

docs/site/guides/disk-encryption.md

@@ -5,7 +5,7 @@ This guide provides an example setup for a single-disk ZFS system with native en
     This configuration only applies to `systemd-boot` enabled systems and **requires** UEFI booting.
 
 !!! Info "Secure Boot"
-    This guide is compatible with systems that have [secure boot disabled](./secure-boot.md). If you encounter boot issues, check if secure boot needs to be disabled in your UEFI settings.
+    This guide is compatible with systems that have [secure boot disabled](../guides/secure-boot.md). If you encounter boot issues, check if secure boot needs to be disabled in your UEFI settings.
 
 Replace the highlighted lines with your own disk-id.
 You can find our your disk-id by executing:

docs/site/guides/flake-parts.md

@@ -1,33 +1,29 @@
+Clan supports integration with [flake-parts](https://flake.parts/), a framework for constructing your `flake.nix` using modules. Follow these steps to integrate Clan with flake-parts:
 
-Clan supports integration with [flake-parts](https://flake.parts/), a framework for constructing your `flake.nix` using modules.
+## Step 1: Update Your Flake Inputs
 
-To construct your Clan using flake-parts, follow these steps:
-
-## Update Your Flake Inputs
-
-To begin, you'll need to add `flake-parts` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `clan-core` and `nixpkgs`. Here's how you can update your `flake.nix` file:
+Add `flake-parts` as a dependency in your `flake.nix` file alongside existing dependencies like `clan-core` and `nixpkgs`. Here's an example:
 
 ```nix
 # flake.nix
 inputs = {
   nixpkgs.url = "github:NixOS/nixpkgs?ref=nixos-unstable";
 
-  # New flake-parts input
+  # Add flake-parts
   flake-parts.url = "github:hercules-ci/flake-parts";
   flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
 
   clan-core = {
     url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-    inputs.nixpkgs.follows = "nixpkgs"; # Don't do this if your machines are on nixpkgs stable.
-    # New
-    inputs.flake-parts.follows = "flake-parts";
+    inputs.nixpkgs.follows = "nixpkgs"; # Avoid this if using nixpkgs stable.
+    inputs.flake-parts.follows = "flake-parts"; # New
   };
-}
+};
 ```
 
-## Import the Clan flake-parts Module
+## Step 2: Import the Clan flake-parts Module
 
-After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](/options) available within `mkFlake`.
+Next, import the Clan flake-parts module to make the [Clan options](../reference/options/clan.md) available within `mkFlake`:
 
 ```nix
 {
@@ -43,9 +39,9 @@ After updating your flake inputs, the next step is to import the Clan flake-part
 }
 ```
 
-## Configure Clan Settings and Define Machines
+## Step 3: Configure Clan Settings and Define Machines
 
-Next you'll need to configure Clan wide settings and define machines, here's an example of how `flake.nix` should look:
+Configure Clan-wide settings and define machines. Here's an example `flake.nix`:
 
 ```nix
 {
@@ -62,24 +58,22 @@ Next you'll need to configure Clan wide settings and define machines, here's an
       ];
 
       # Define your Clan
-      # See: https://docs.clan.lol/reference/nix-api/clan/
       clan = {
-        # Clan wide settings
-        meta.name = ""; # This is required and must be unique
+        meta.name = ""; # Required and must be unique
 
         machines = {
           jon = {
             imports = [
               ./modules/firefox.nix
-              # ... more modules
+              # Add more modules as needed
             ];
 
             nixpkgs.hostPlatform = "x86_64-linux";
 
-            # Set this for Clan commands to work remotely over SSH like `clan machines update`
+            # Enable remote Clan commands over SSH
             clan.core.networking.targetHost = "root@jon";
 
-            # remote> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
+            # Disk configuration
             disko.devices.disk.main = {
               device = "/dev/disk/by-id/nvme-eui.e8238fa6bf530001001b448b4aec2929";
             };
@@ -90,7 +84,4 @@ Next you'll need to configure Clan wide settings and define machines, here's an
 }
 ```
 
-For detailed information about configuring `flake-parts` and the available options within Clan,
-refer to the [Clan module](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) documentation.
-
----
+For more details on configuring `flake-parts` and available Clan options, refer to the [Clan module documentation](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix).

docs/site/guides/internal-ssl-services.md

@@ -0,0 +1,213 @@
+A common use case you might have is to host services and applications which are
+only reachable within your clan.
+
+This guide explains how to set up such secure, clan-internal web services using
+a custom top-level domain (TLD) with SSL certificates.
+
+Your services will be accessible only within your clan network and secured with
+proper SSL certificates that all clan machines trust.
+
+## Overview
+
+By combining the `coredns` and `certificates` clan services, you can:
+
+- Create a custom TLD for your clan (e.g. `.c`)
+- Host internal web services accessible via HTTPS (e.g. `https://api.c`, `https://dashboard.c`)
+- Automatically provision and trust SSL certificates across all clan machines
+- Keep internal services secure and isolated from the public internet
+
+The setup uses two clan services working together:
+
+- **coredns service**: Provides DNS resolution for your custom TLD within the clan
+- **certificates service**: Creates a certificate authority (CA) and issues SSL certificates for your TLD
+
+### DNS Resolution Flow
+
+1. A clan machine tries to access `https://service.c`
+2. The machine queries its local DNS resolver (unbound)
+3. For `.c` domains, the query is forwarded to your clan's CoreDNS server. All
+   other domains will be resolved as usual.
+4. CoreDNS returns the IP address of the machine hosting the service
+5. The machine connects directly to the service over HTTPS
+6. The SSL certificate is trusted because all machines trust your clan's CA
+
+## Step-by-Step Setup
+
+The following setup assumes you have a VPN (e.g. Zerotier) already running. The
+IPs configured in the options below will probably the Zerotier-IPs of the
+respective machines.
+
+### Configure the CoreDNS Service
+
+The CoreDNS service has two roles:
+- `server`: Runs the DNS server for your custom TLD
+- `default`: Makes machines use the DNS server for TLD resolution and allows exposing services
+
+Add this to your inventory:
+
+```nix
+inventory = {
+  machines = {
+    dns-server = { }; # Machine that will run the DNS server
+    web-server = { }; # Machine that will host web services
+    client = { };     # Any other machines in your clan
+  };
+
+  instances = {
+    coredns = {
+
+      # Add the default role to all machines
+      roles.default.tags = [ "all" ];
+
+      # DNS server for the .c TLD
+      roles.server.machines.dns-server.settings = {
+        ip = "192.168.1.10";  # IP of your DNS server machine
+        tld = "c";
+      };
+
+      # Machine hosting services (example: ca.c and admin.c)
+      roles.default.machines.web-server.settings = {
+        ip = "192.168.1.20";  # IP of your web server
+        services = [ "ca" "admin" ];
+      };
+    };
+  };
+};
+```
+
+### Configure the Certificates Service
+
+The certificates service also has two roles:
+- `ca`: Sets up the certificate authority on a server
+- `default`: Makes machines trust the CA and allows them to request certificates
+
+Add this to your inventory:
+
+```nix
+inventory = {
+  instances = {
+    # ... coredns configuration from above ...
+
+    certificates = {
+
+      # Set up CA for .c domain
+      roles.ca.machines.dns-server.settings = {
+        tlds = [ "c" ];
+        acmeEmail = "admin@example.com";  # Optional: your email
+      };
+
+      # Add default role to all machines to trust the CA
+      roles.default.tags = [ "all" ];
+    };
+  };
+};
+```
+
+### Complete Example Configuration
+
+Here's a complete working example:
+
+```nix
+nventory = {
+  machines = {
+    caserver = { };  # DNS server + CA + web services
+    webserver = { }; # Additional web services
+    client = { };    # Client machine
+  };
+
+  instances = {
+    coredns = {
+
+      # Add the default role to all machines
+      roles.default.tags = [ "all" ];
+
+      # DNS server for the .c TLD
+      roles.server.machines.caserver.settings = {
+        ip = "192.168.8.5";
+        tld = "c";
+      };
+
+      # machine hosting https://ca.c (our CA for SSL)
+      roles.default.machines.caserver.settings = {
+        ip = "192.168.8.5";
+        services = [ "ca" ];
+      };
+
+      # machine hosting https://blub.c (some internal web-service)
+      roles.default.machines.webserver.settings = {
+        ip = "192.168.8.6";
+        services = [ "blub" ];
+      };
+    };
+
+    # Provide https for the .c top-level domain
+    certificates = {
+
+      roles.ca.machines.caserver.settings = {
+        tlds = [ "c" ];
+        acmeEmail = "admin@example.com";
+      };
+
+      roles.default.tags = [ "all" ];
+    };
+  };
+};
+```
+
+## Testing Your Configuration
+
+DNS resolution can be tested with:
+
+```bash
+# On any clan machine, test DNS resolution
+nslookup ca.c
+nslookup blub.c
+```
+
+You should also now be able to visit `https://ca.c` to access the certificate authority or visit `https://blub.c` to access your web service.
+
+## Troubleshooting
+
+### DNS Resolution Issues
+
+1. **Check if DNS server is running**:
+```bash
+# On the DNS server machine
+systemctl status coredns
+```
+
+2. **Verify DNS configuration**:
+```bash
+# Check if the right nameservers are configured
+cat /etc/resolv.conf
+systemctl status systemd-resolved
+```
+
+3. **Test DNS directly**:
+```bash
+# Query the DNS server directly
+dig @192.168.8.5 ca.c
+```
+
+### Certificate Issues
+
+1. **Check CA status**:
+```bash
+# On the CA machine
+systemctl status step-ca
+systemctl status nginx
+```
+
+2. **Verify certificate trust**:
+```bash
+# Test certificate trust
+curl -v https://ca.c
+openssl s_client -connect ca.c:443 -verify_return_error
+```
+
+3. **Check ACME configuration**:
+```bash
+# View ACME certificates
+ls /var/lib/acme/
+journalctl -u acme-ca.c.service
+```

docs/site/guides/inventory/inventory.md

@@ -17,13 +17,13 @@ The following tutorial will walk through setting up a Backup service where the t
 
 ## Prerequisites
 
-- [x] [Add some machines](../getting-started/add-machines.md) to your Clan.
+- [x] [Add some machines](../../getting-started/add-machines.md) to your Clan.
 
 ## Services
 
 The inventory defines `instances` of clan services. Membership of `machines` is defined via `roles` exclusively.
 
-See each [modules documentation](../../reference/clanServices/index.md) for its available roles.
+See each [modules documentation](../../services/definition.md) for its available roles.
 
 ### Adding services to machines
 

docs/site/guides/macos.md

@@ -7,7 +7,7 @@ This guide explains how to manage macOS machines using Clan.
 Currently, Clan supports the following features for macOS:
 
 - `clan machines update` for existing [nix-darwin](https://github.com/nix-darwin/nix-darwin) installations
-- Support for [vars](./vars/vars-overview.md)
+- Support for [vars](../guides/vars/vars-overview.md)
 
 ## Add Your Machine to Your Clan Flake
 

docs/site/guides/migrations/migrate-inventory-services.md

@@ -1,7 +1,7 @@
 # Migrating from using `clanModules` to `clanServices`
 
 **Audience**: This is a guide for **people using `clanModules`**.
-If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../services/community.md)
+If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../../guides/services/community.md)
 
 ## What's Changing?
 
@@ -157,7 +157,7 @@ instances = {
 
 ### Move `services` entries to `instances`
 
-Check if a service that you use has been migrated [In our reference](../../reference/clanServices/index.md)
+Check if a service that you use has been migrated [In our reference](../../services/definition.md)
 
 In your inventory, move it from:
 
@@ -247,45 +247,45 @@ The following table shows the migration status of each deprecated clanModule:
 
 | clanModule               | Migration Status                                                  | Notes                                                            |
 |--------------------------|-------------------------------------------------------------------|------------------------------------------------------------------|
-| `admin`                  | ✅ [Migrated](../../reference/clanServices/admin.md)              |                                                                  |
+| `admin`                  | ✅ [Migrated](../../services/official/admin.md)              |                                                                  |
 | `auto-upgrade`           | ❌ Removed                                                        |                                                                  |
 | `borgbackup-static`      | ❌ Removed                                                        |                                                                  |
-| `borgbackup`             | ✅ [Migrated](../../reference/clanServices/borgbackup.md)         |                                                                  |
-| `data-mesher`            | ✅ [Migrated](../../reference/clanServices/data-mesher.md)        |                                                                  |
+| `borgbackup`             | ✅ [Migrated](../../services/official/borgbackup.md)         |                                                                  |
+| `data-mesher`            | ✅ [Migrated](../../services/official/data-mesher.md)        |                                                                  |
 | `deltachat`              | ❌ Removed                                                        |                                                                  |
 | `disk-id`                | ❌ Removed                                                        |                                                                  |
-| `dyndns`                 | ✅ [Migrated](../../reference/clanServices/dyndns.md)             |                                                                  |
+| `dyndns`                 | ✅ [Migrated](../../services/official/dyndns.md)             |                                                                  |
 | `ergochat`               | ❌ Removed                                                        |                                                                  |
-| `garage`                 | ✅ [Migrated](../../reference/clanServices/garage.md)             |                                                                  |
+| `garage`                 | ✅ [Migrated](../../services/official/garage.md)             |                                                                  |
 | `golem-provider`         | ❌ Removed                                                        |                                                                  |
 | `heisenbridge`           | ❌ Removed                                                        |                                                                  |
-| `importer`               | ✅ [Migrated](../../reference/clanServices/importer.md)           |                                                                  |
-| `iwd`                    | ❌ Removed                                                        | Use [wifi service](../../reference/clanServices/wifi.md) instead |
-| `localbackup`            | ✅ [Migrated](../../reference/clanServices/localbackup.md)        |                                                                  |
+| `importer`               | ✅ [Migrated](../../services/official/importer.md)           |                                                                  |
+| `iwd`                    | ❌ Removed                                                        | Use [wifi service](../../services/official/wifi.md) instead |
+| `localbackup`            | ✅ [Migrated](../../services/official/localbackup.md)        |                                                                  |
 | `localsend`              | ❌ Removed                                                        |                                                                  |
 | `machine-id`             | ✅ [Migrated](../../reference/clan.core/settings.md)              | Now an [option](../../reference/clan.core/settings.md)           |
-| `matrix-synapse`         | ✅ [Migrated](../../reference/clanServices/matrix-synapse.md)     |                                                                  |
+| `matrix-synapse`         | ✅ [Migrated](../../services/official/matrix-synapse.md)     |                                                                  |
 | `moonlight`              | ❌ Removed                                                        |                                                                  |
 | `mumble`                 | ❌ Removed                                                        |                                                                  |
-| `mycelium`               | ✅ [Migrated](../../reference/clanServices/mycelium.md)           |                                                                  |
+| `mycelium`               | ✅ [Migrated](../../services/official/mycelium.md)           |                                                                  |
 | `nginx`                  | ❌ Removed                                                        |                                                                  |
-| `packages`               | ✅ [Migrated](../../reference/clanServices/packages.md)           |                                                                  |
+| `packages`               | ✅ [Migrated](../../services/official/packages.md)           |                                                                  |
 | `postgresql`             | ✅ [Migrated](../../reference/clan.core/settings.md)              | Now an [option](../../reference/clan.core/settings.md)           |
-| `root-password`          | ✅ [Migrated](../../reference/clanServices/users.md)              | See [migration guide](../../reference/clanServices/users.md#migration-from-root-password-module) |
+| `root-password`          | ✅ [Migrated](../../services/official/users.md)              | See [migration guide](../../services/official/users.md#migration-from-root-password-module) |
 | `single-disk`            | ❌ Removed                                                        |                                                                  |
-| `sshd`                   | ✅ [Migrated](../../reference/clanServices/sshd.md)               |                                                                  |
+| `sshd`                   | ✅ [Migrated](../../services/official/sshd.md)               |                                                                  |
 | `state-version`          | ✅ [Migrated](../../reference/clan.core/settings.md)              | Now an [option](../../reference/clan.core/settings.md)           |
 | `static-hosts`           | ❌ Removed                                                        |                                                                  |
 | `sunshine`               | ❌ Removed                                                        |                                                                  |
 | `syncthing-static-peers` | ❌ Removed                                                        |                                                                  |
-| `syncthing`              | ✅ [Migrated](../../reference/clanServices/syncthing.md)          |                                                                  |
+| `syncthing`              | ✅ [Migrated](../../services/official/syncthing.md)          |                                                                  |
 | `thelounge`              | ❌ Removed                                                        |                                                                  |
-| `trusted-nix-caches`     | ✅ [Migrated](../../reference/clanServices/trusted-nix-caches.md) |                                                                  |
-| `user-password`          | ✅ [Migrated](../../reference/clanServices/users.md)              |                                                                  |
+| `trusted-nix-caches`     | ✅ [Migrated](../../services/official/trusted-nix-caches.md) |                                                                  |
+| `user-password`          | ✅ [Migrated](../../services/official/users.md)              |                                                                  |
 | `vaultwarden`            | ❌ Removed                                                        |                                                                  |
 | `xfce`                   | ❌ Removed                                                        |                                                                  |
 | `zerotier-static-peers`  | ❌ Removed                                                        |                                                                  |
-| `zerotier`               | ✅ [Migrated](../../reference/clanServices/zerotier.md)           |                                                                  |
+| `zerotier`               | ✅ [Migrated](../../services/official/zerotier.md)           |                                                                  |
 | `zt-tcp-relay`           | ❌ Removed                                                        |                                                                  |
 
 ---
@@ -378,6 +378,6 @@ instances = {
 
 ## Further reference
 
-* [Inventory Concept](../inventory/inventory.md)
-* [Authoring a 'clan.service' module](../services/community.md)
-* [ClanServices](../inventory/clanServices.md)
+* [Inventory Concept](../../guides/inventory/inventory.md)
+* [Authoring a 'clan.service' module](../../guides/services/community.md)
+* [ClanServices](../../guides/services/introduction-to-services.md)

docs/site/guides/migrations/migration-facts-vars.md

@@ -1,9 +1,9 @@
-# Migrate modules from `facts` to `vars`.
+# Migrate modules from `facts` to `vars`
 
 For a high level overview about `vars` see our [blog post](https://clan.lol/blog/vars/).
 
-This guide will help you migrate your modules that still use our [`facts`](../secrets.md) backend
-to the [`vars`](../vars/vars-overview.md) backend.
+This guide will help you migrate your modules that still use our [`facts`](../../guides/migrations/migration-facts-vars.md) backend
+to the [`vars`](../../guides/vars/vars-overview.md) backend.
 
 The `vars` [module](../../reference/clan.core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
 
@@ -33,7 +33,6 @@ vars.generators.vaultwarden = {
 
 And this would read as follows: The vaultwarden `vars` module generates the admin file.
 
-
 ## Prompts
 
 Because prompts can be a necessity for certain systems `vars` have a shorthand for defining them.
@@ -46,7 +45,9 @@ facts.services.forgejo-api = {
     generator.script = "cp $prompt_value > $secret/token";
 };
 ```
+
 To have analogous functionality in `vars`:
+
 ```nix
 vars.generators.forgejo-api = {
     prompts.token = {
@@ -55,6 +56,7 @@ vars.generators.forgejo-api = {
     };
 };
 ```
+
 This does not only simplify prompting, it also now allows us to define multiple prompts in one generator.
 A more analogous way to the `fact` method is available, in case the module author needs more flexibility with the prompt input:
 
@@ -92,8 +94,8 @@ facts.services.syncthing = {
 };
 ```
 
-
 This would be the corresponding `vars` module, which also will migrate existing facts.
+
 ```nix
 vars.generators.syncthing = {
   migrateFact = "syncthing";
@@ -116,11 +118,11 @@ vars.generators.syncthing = {
   '';
 };
 ```
+
 Most of the usage patterns stay the same, but `vars` have a more ergonomic interface.
 There are not two different ways to define files anymore (public/secret).
 Now files are defined under the `files` attribute and are secret by default.
 
-
 ## Happy Migration
 
 We hope this gives you a clear path to start and finish your migration from `facts` to `vars`.

docs/site/guides/networking/mesh-vpn.md

@@ -1,4 +1,3 @@
-
 This guide provides detailed instructions for configuring
 [ZeroTier VPN](https://zerotier.com) within Clan. Follow the
 outlined steps to set up a machine as a VPN controller (`<CONTROLLER>`) and to
@@ -98,11 +97,12 @@ The status should be "ONLINE":
 ```
 
 ## Further
+Currently **Zerotier** is the only mesh-vpn that is fully integrated into clan.
+In the future we plan to add additional network technologies like tinc, head/tailscale
+Currently we support yggdrassil and mycelium through usage of the inventory, 
+though it is not yet integrated into the networking module.
 
-Currently you can only use **Zerotier** as networking technology because this is the first network stack we aim to support.
-In the future we plan to add additional network technologies like tinc, head/tailscale, yggdrassil and mycelium.
-
-We chose zerotier because in our tests it was a straight forwards solution to bootstrap.
+We chose ZeroTier because in our tests it was a straight forward solution to bootstrap.
 It allows you to selfhost a controller and the controller doesn't need to be globally reachable.
 Which made it a good fit for starting the project.
 
@@ -132,7 +132,7 @@ $ sudo zerotier-cli info
 
 #### Manually Authorize a Machine on the Controller
 
-=== "with ZerotierIP"
+=== "with ZeroTierIP"
 
       ```bash
       $ sudo zerotier-members allow --member-ip <IP>
@@ -140,10 +140,10 @@ $ sudo zerotier-cli info
 
       Substitute `<IP>` with the ZeroTier IP obtained previously.
 
-=== "with ZerotierID"
+=== "with ZeroTierID"
 
       ```bash
       $ sudo zerotier-members allow <ID>
       ```
 
-      Substitute `<ID>` with the ZeroTier ID obtained previously.
+      Substitute `<ID>` with the ZeroTier ID obtained previously.

docs/site/guides/nixos-rebuild.md

@@ -64,5 +64,5 @@ nixos-rebuild switch --flake .#my-machine --target-host root@target-ip --build-h
 
 ## Related Documentation
 
-- [Update Your Machines](getting-started/update.md) - Using clan's update command
-- [Variables (Vars)](vars/vars-overview.md) - Understanding the vars system
+- [Update Your Machines](../getting-started/update-machines.md) - Using clan's update command
+- [Variables (Vars)](../guides/vars/vars-overview.md) - Understanding the vars system

docs/site/guides/nixpkgs-flake-input/index.md

@@ -0,0 +1,99 @@
+**Q**: How should I choose the `nixpkgs` input for my flake when using `clan-core`?
+
+**A**: Pin your flake to a recent `nixpkgs` version. Here are two common approaches, each with its trade-offs:
+
+## Option 1: Follow `clan-core`
+
+- **Pros**:
+    - Recommended for most users.
+    - Verified by our CI and widely used by others.
+- **Cons**:
+    - Coupled to version bumps in `clan-core`.
+    - Upstream features and packages may take longer to land.
+
+Example:
+
+```nix
+inputs = {
+  clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
+  # Use the `nixpkgs` version locked in `clan-core`
+  nixpkgs.follows = "clan-core/nixpkgs";
+};
+```
+
+## Option 2: Use Your Own `nixpkgs` Version
+
+- **Pros**:
+    - Faster access to new upstream features and packages.
+- **Cons**:
+    - Recommended for advanced users.
+    - Not covered by our CI — you’re on the frontier.
+
+Example:
+
+```nix
+inputs = {
+  # Specify your own `nixpkgs` version
+  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+
+  clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
+  # Ensure `clan-core` uses your `nixpkgs` version
+  clan-core.inputs.nixpkgs.follows = "nixpkgs";
+};
+```
+
+## Recommended: Avoid Duplicate `nixpkgs` Entries
+
+To prevent ambiguity or compatibility issues, check your `flake.lock` for duplicate `nixpkgs` entries. Duplicate entries indicate a missing `follows` directive in one of your flake inputs.
+
+Example of duplicate entries in `flake.lock`:
+
+```json
+"nixpkgs": {
+  "locked": {
+    "lastModified": 315532800,
+    "narHash": "sha256-1tUpklZsKzMGI3gjo/dWD+hS8cf+5Jji8TF5Cfz7i3I=",
+    "rev": "08b8f92ac6354983f5382124fef6006cade4a1c1",
+    "type": "tarball",
+    "url": "https://releases.nixos.org/nixpkgs/nixpkgs-25.11pre862603.08b8f92ac635/nixexprs.tar.xz"
+  },
+  "original": {
+    "type": "tarball",
+    "url": "https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz"
+  }
+},
+"nixpkgs_2": {
+  "locked": {
+    "lastModified": 1758346548,
+    "narHash": "sha256-afXE7AJ7MY6wY1pg/Y6UPHNYPy5GtUKeBkrZZ/gC71E=",
+    "owner": "nixos",
+    "repo": "nixpkgs",
+    "rev": "b2a3852bd078e68dd2b3dfa8c00c67af1f0a7d20",
+    "type": "github"
+  },
+  "original": {
+    "owner": "nixos",
+    "ref": "nixos-25.05",
+    "repo": "nixpkgs",
+    "type": "github"
+  }
+}
+```
+
+To locate the source of duplicate entries, grep your `flake.lock` file. For example, if `home-manager` is referencing `nixpkgs_2` instead of the main `nixpkgs`:
+
+```json
+"home-manager": {
+  "inputs": {
+    "nixpkgs": "nixpkgs_2"
+  }
+}
+```
+
+Fix this by adding the following line to your `flake.nix` inputs:
+
+```nix
+home-manager.inputs.nixpkgs.follows = "nixpkgs";
+```
+
+Repeat this process until all duplicate `nixpkgs` entries are resolved. This ensures all inputs use the same `nixpkgs` source, preventing cross-version conflicts.

docs/site/guides/secrets.md

@@ -1,5 +1,5 @@
-This article provides an overview over the underlying secrets system which is used by [Vars](./vars/vars-overview.md).
-Under most circumstances you should use [Vars](./vars/vars-overview.md) directly instead.
+This article provides an overview over the underlying secrets system which is used by [Vars](../guides/vars/vars-overview.md).
+Under most circumstances you should use [Vars](../guides/vars/vars-overview.md) directly instead.
 
 Consider using `clan secrets` only for managing admin users and groups, as well as a debugging tool.
 

docs/site/guides/services/community.md

@@ -3,9 +3,9 @@
 ## Service Module Specification
 
 This section explains how to author a clan service module.
-We discussed the initial architecture in [01-clan-service-modules](../../decisions/01-ClanModules.md) and decided to rework the format.
+We discussed the initial architecture in [01-clan-service-modules](../../decisions/01-Clan-Modules.md) and decided to rework the format.
 
-For the full specification and current state see: **[Service Author Reference](../../reference/clanServices/clan-service-author-interface.md)**
+For the full specification and current state see: **[Service Author Reference](../../reference/options/clan_service.md)**
 
 ### A Minimal module
 
@@ -47,7 +47,7 @@ The imported module file must fulfill at least the following requirements:
 }
 ```
 
-For more attributes see: **[Service Author Reference](../../reference/clanServices/clan-service-author-interface.md)**
+For more attributes see: **[Service Author Reference](../../reference/options/clan_service.md)**
 
 ### Adding functionality to the module
 
@@ -288,7 +288,7 @@ of their type.
 In the inventory we the assign machines to a type, e.g. by using tags
 
 ```nix title="flake.nix"
-instnaces.machine-type = {
+instances.machine-type = {
   module.input = "self";
   module.name = "@pinpox/machine-type";
   roles.desktop.tags.desktop = { };
@@ -300,6 +300,7 @@ instnaces.machine-type = {
 
 ## Further Reading
 
-- [Reference Documentation for Service Authors](../../reference/clanServices/clan-service-author-interface.md)
-- [Migration Guide from ClanModules to ClanServices](../migrations/migrate-inventory-services.md)
-- [Decision that lead to ClanServices](../../decisions/01-ClanModules.md)
+- [Reference Documentation for Service Authors](../../reference/options/clan_service.md)
+- [Migration Guide from ClanModules to ClanServices](../../guides/migrations/migrate-inventory-services.md)
+- [Decision that lead to ClanServices](../../decisions/01-Clan-Modules.md)
+- [Testing Guide for Services with Vars](../contributing/testing.md#testing-services-with-vars)

docs/site/guides/services/introduction-to-services.md

@@ -1,11 +1,11 @@
-Clan's inventory system is a composable way to define and deploy services across
+Clan's services are a modular way to define and deploy services across
 machines.
 
-This guide shows how to **instantiate** a `clanService`, explains how service
-definitions are structured in your inventory, and how to pick or create services
+This guide shows how to **instantiate** a **service**, explains how service
+definitions are structured and how to pick or create services
 from modules exposed by flakes.
 
-The term **Multi-host-modules** was introduced previously in the [nixus
+A similar term: **Multi-host-modules** was introduced previously in the [nixus
 repository](https://github.com/infinisil/nixus) and represents a similar
 concept.
 
@@ -68,7 +68,7 @@ inventory.instances = {
 ## Module Settings
 
 Each role might expose configurable options. See clan's [clanServices
-reference](../../reference/clanServices/index.md) for all available options.
+reference](../../services/definition.md) for all available options.
 
 Settings can be set in per-machine or per-role. The latter is applied to all
 machines that are assigned to that role.
@@ -155,13 +155,13 @@ inventory.instances = {
 
 You can use services exposed by Clan's core module library, `clan-core`.
 
-🔗 See: [List of Available Services in clan-core](../../reference/clanServices/index.md)
+🔗 See: [List of Available Services in clan-core](../../services/definition.md)
 
 ## Defining Your Own Service
 
 You can also author your own `clanService` modules.
 
-🔗 Learn how to write your own service: [Authoring a service](../services/community.md)
+🔗 Learn how to write your own service: [Authoring a service](../../guides/services/community.md)
 
 You might expose your service module from your flake — this makes it easy for other people to also use your module in their clan.
 
@@ -177,7 +177,5 @@ ______________________________________________________________________
 
 ## What's Next?
 
-- [Author your own clanService →](../services/community.md)
-- [Migrate from clanModules →](../migrations/migrate-inventory-services.md)
-
-<!-- TODO: * [Understand the architecture →](../explanation/clan-architecture.md) -->
+- [Author your own clanService →](../../guides/services/community.md)
+- [Migrate from clanModules →](../../guides/migrations/migrate-inventory-services.md)

docs/site/guides/vars/vars-overview.md

@@ -140,5 +140,5 @@ clan machines update my-machine
 
 ## Migration from Facts
 
-If you're currently using the legacy facts system, see our [Migration Guide](../migrations/migration-facts-vars.md) for step-by-step instructions on upgrading to vars.
+If you're currently using the legacy facts system, see our [Migration Guide](../../guides/migrations/migration-facts-vars.md) for step-by-step instructions on upgrading to vars.
 

docs/site/index.md

@@ -74,17 +74,18 @@ hide:
   <input type="checkbox" id="clan-readmore" class="clamp-toggle" />
   <div class="clamp-content">
     <p><a href="https://clan.lol/">Clan</a> is a peer-to-peer computer management framework that empowers you to selfhost in a reliable and scalable way</strong>.</p>
-    <p>Built on NixOS, Clan provides a declarative interface for managing machines</strong> with automated <a href="./guides/secrets.md">secret management</a>, easy <a href="./guides/mesh-vpn.md">mesh VPN connectivity</a>, and <a href="./guides/backups.md">automated backups</a>.</p>
+    <p>Built on NixOS, Clan provides a declarative interface for managing machines</strong> with <a href="/guides/vars/vars-overview/">Resource management</a>, <a href="/guides/networking/networking/">Networking</a>, and <a href="
+    /guides/backups/backup-intro/">Backups</a>.</p>
     <p>Whether you're running a homelab or maintaining critical computing infrastructure, Clan will help reduce maintenance burden</strong> by allowing a git repository to define your whole network</strong> of computers.</p>
     <p>In combination with <a href="https://github.com/Mic92/sops-nix">sops-nix</a>, <a href="https://github.com/nix-community/nixos-anywhere">nixos-anywhere</a> and <a href="https://github.com/nix-community/disko">disko</a>, Clan makes it possible to have collaborative infrastructure</strong>.</p>
-    <p>At the heart of Clan are <a href="./reference/clanServices/index.md">Clan Services</a> - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, you can <a href="./guides/inventory/clanServices.md">create custom services</a> tailored to your specific needs.</p>
+    <p>At the heart of Clan are <a href="/services/definition">Clan Services</a> - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, everyone can <a href="/guides/services/community/">create custom services</a> tailored to your specific needs.</p>
   </div>
   <label class="clamp-more" for="clan-readmore"></label>
 </div>
 
 ---
 
-[Get started](./guides/getting-started/index.md){ .md-button .md-button--primary }
+[Get started](./getting-started/creating-your-first-clan.md){ .md-button .md-button--primary }
 [View on Gitea](https://git.clan.lol/clan/clan-core){ .md-button }
 
 ## Guides
@@ -121,13 +122,13 @@ hide:
 
     command line interface
 
--   [Clan Options](/options)
+-   [Clan Options](./reference/options/clan.md)
 
     ---
 
     Search all options
 
--   [Services](./reference/clanServices/index.md)
+-   [Services](./services/definition.md)
 
     ---
 

docs/site/reference/index.md

@@ -4,10 +4,10 @@ This section of the site provides an overview of available options and commands
 
 ---
 
-- [Clan Configuration Option](/options) - for defining a Clan
-- Learn how to use the [Clan CLI](./cli/index.md)
-- Explore available [services](./clanServices/index.md)
-- [NixOS Configuration Options](./clan.core/index.md) - Additional options avilable on a NixOS machine.
+- Learn how to use the [Clan CLI](../reference/cli/index.md)
+- Explore available [services](../services/definition.md)
+- [NixOS Configuration Options](../reference/clan.core/index.md) - Additional options avilable on a NixOS machine.
+- [Search Clan Option](/option-search) - for defining a Clan
 
 ---
 

docs/site/services/definition.md

@@ -0,0 +1,14 @@
+**`clanServices`** are modular building blocks that simplify the configuration and orchestration of multi-host services.
+
+Each `clanService`:
+
+* Is a module of class **`clan.service`**
+* Can define **roles** (e.g., `client`, `server`)
+* Uses **`inventory.instances`** to configure where and how it is deployed
+
+!!! Note
+    `clanServices` are part of Clan's next-generation service model and are intended to replace `clanModules`.
+
+    See [Migration Guide](../guides/migrations/migrate-inventory-services.md) for help on migrating.
+
+Learn how to use `clanServices` in practice in the [Using clanServices guide](../guides/services/introduction-to-services.md).

flake.lock

@@ -13,11 +13,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1758510393,
-        "narHash": "sha256-Bd7gr2RBaDJn1Zppus1WpW6CCdtJFn9Ccv4x0/HqCjo=",
-        "rev": "e8418ce6a514d3561ea7dd2242d4bb9b36bc003b",
+        "lastModified": 1759140052,
+        "narHash": "sha256-CpGdQRvgmBhEAlXNyrSfrDWcKoYYSGd+5Lw7mvlbt/A=",
+        "rev": "8332273e734aa906e7a1b2fda80e631f2dc9d4c9",
         "type": "tarball",
-        "url": "https://git.clan.lol/api/v1/repos/clan/data-mesher/archive/e8418ce6a514d3561ea7dd2242d4bb9b36bc003b.tar.gz"
+        "url": "https://git.clan.lol/api/v1/repos/clan/data-mesher/archive/8332273e734aa906e7a1b2fda80e631f2dc9d4c9.tar.gz"
       },
       "original": {
         "type": "tarball",
@@ -51,11 +51,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1756770412,
-        "narHash": "sha256-+uWLQZccFHwqpGqr2Yt5VsW/PbeJVTn9Dk6SHWhNRPw=",
+        "lastModified": 1759362264,
+        "narHash": "sha256-wfG0S7pltlYyZTM+qqlhJ7GMw2fTF4mLKCIVhLii/4M=",
         "owner": "hercules-ci",
         "repo": "flake-parts",
-        "rev": "4524271976b625a4a605beefd893f270620fd751",
+        "rev": "758cf7296bee11f1706a574c77d072b8a7baa881",
         "type": "github"
       },
       "original": {
@@ -71,15 +71,16 @@
         ]
       },
       "locked": {
-        "lastModified": 1758447883,
-        "narHash": "sha256-yGA6MV0E4JSEXqLTb4ZZkmdJZcoQ8HUzihRRX12Bvpg=",
+        "lastModified": 1759509947,
+        "narHash": "sha256-4XifSIHfpJKcCf5bZZRhj8C4aCpjNBaE3kXr02s4rHU=",
         "owner": "nix-darwin",
         "repo": "nix-darwin",
-        "rev": "25381509d5c91bbf3c30e23abc6d8476d2143cd1",
+        "rev": "000eadb231812ad6ea6aebd7526974aaf4e79355",
         "type": "github"
       },
       "original": {
         "owner": "nix-darwin",
+        "ref": "nix-darwin-25.05",
         "repo": "nix-darwin",
         "type": "github"
       }
@@ -114,15 +115,15 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 315532800,
-        "narHash": "sha256-1tUpklZsKzMGI3gjo/dWD+hS8cf+5Jji8TF5Cfz7i3I=",
-        "rev": "08b8f92ac6354983f5382124fef6006cade4a1c1",
+        "lastModified": 1760324802,
+        "narHash": "sha256-VWlJtLQ5EQQj45Wj0yTExtSjwRyZ59/qMqEwus/Exlg=",
+        "rev": "7e297ddff44a3cc93673bb38d0374df8d0ad73e4",
         "type": "tarball",
-        "url": "https://releases.nixos.org/nixpkgs/nixpkgs-25.11pre862603.08b8f92ac635/nixexprs.tar.xz"
+        "url": "https://releases.nixos.org/nixos/25.05/nixos-25.05.811135.7e297ddff44a/nixexprs.tar.xz"
       },
       "original": {
         "type": "tarball",
-        "url": "https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz"
+        "url": "https://nixos.org/channels/nixos-25.05/nixexprs.tar.xz"
       }
     },
     "root": {
@@ -146,11 +147,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1758425756,
-        "narHash": "sha256-L3N8zV6wsViXiD8i3WFyrvjDdz76g3tXKEdZ4FkgQ+Y=",
+        "lastModified": 1759635238,
+        "narHash": "sha256-UvzKi02LMFP74csFfwLPAZ0mrE7k6EiYaKecplyX9Qk=",
         "owner": "Mic92",
         "repo": "sops-nix",
-        "rev": "e0fdaea3c31646e252a60b42d0ed8eafdb289762",
+        "rev": "6e5a38e08a2c31ae687504196a230ae00ea95133",
         "type": "github"
       },
       "original": {
@@ -181,11 +182,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1758206697,
-        "narHash": "sha256-/DbPkh6PZOgfueCbs3uzlk4ASU2nPPsiVWhpMCNkAd0=",
+        "lastModified": 1760120816,
+        "narHash": "sha256-gq9rdocpmRZCwLS5vsHozwB6b5nrOBDNc2kkEaTXHfg=",
         "owner": "numtide",
         "repo": "treefmt-nix",
-        "rev": "128222dc911b8e2e18939537bed1762b7f3a04aa",
+        "rev": "761ae7aff00907b607125b2f57338b74177697ed",
         "type": "github"
       },
       "original": {

flake.nix

@@ -2,9 +2,9 @@
   description = "clan.lol base operating system";
 
   inputs = {
-    nixpkgs.url = "https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz";
+    nixpkgs.url = "https://nixos.org/channels/nixos-25.05/nixexprs.tar.xz";
 
-    nix-darwin.url = "github:nix-darwin/nix-darwin";
+    nix-darwin.url = "github:nix-darwin/nix-darwin/nix-darwin-25.05";
     nix-darwin.inputs.nixpkgs.follows = "nixpkgs";
 
     flake-parts.url = "github:hercules-ci/flake-parts";
@@ -56,55 +56,61 @@
         else
           (import ./devFlake/flake-compat.nix {
             src = ./devFlake;
-          }).outputs;
+          }).outputs.inputs;
     in
-    flake-parts.lib.mkFlake { inherit inputs; } (
-      { ... }:
+    flake-parts.lib.mkFlake
       {
-        _module.args = {
+        inherit inputs;
+        specialArgs = {
           inherit privateInputs;
         };
-        clan = {
-          meta.name = "clan-core";
-          inventory = {
-            machines = {
-              "test-darwin-machine" = {
-                machineClass = "darwin";
+      }
+      (
+        { ... }:
+        {
+          clan = {
+            meta.name = "clan-core";
+            inventory = {
+              machines = {
+                "test-darwin-machine" = {
+                  machineClass = "darwin";
+                };
               };
             };
+            # Allows downstream users to inject "unsupported" nixpkgs versions
+            checks.minNixpkgsVersion.ignore = true;
           };
-        };
-        systems = import systems;
-        imports = [
-          flake-parts.flakeModules.modules
-        ]
-        ++
-          # only importing existing paths allows to minimize the flake for test
-          # by removing files
-          filter pathExists [
-            ./checks/flake-module.nix
-            ./clanModules/flake-module.nix
-            ./clanServices/flake-module.nix
-            ./devShell.nix
-            ./docs/nix/flake-module.nix
-            ./flakeModules/demo_iso.nix
-            ./flakeModules/flake-module.nix
-            ./lib/filter-clan-core/flake-module.nix
-            ./lib/flake-module.nix
-            ./lib/flake-parts/clan-nixos-test.nix
-            ./nixosModules/clanCore/vars/flake-module.nix
-            ./nixosModules/flake-module.nix
-            ./pkgs/clan-cli/clan_cli/tests/flake-module.nix
-            ./pkgs/flake-module.nix
-            ./templates/flake-module.nix
+          systems = import systems;
+          imports = [
+            flake-parts.flakeModules.modules
           ]
-        ++ [
-          (if pathExists ./flakeModules/clan.nix then import ./flakeModules/clan.nix inputs.self else { })
-        ]
-        # Make treefmt-nix optional
-        # This only works if you set inputs.clan-core.inputs.treefmt-nix.follows
-        # to a non-empty input that doesn't export a flakeModule
-        ++ optional (pathExists ./formatter.nix && inputs.treefmt-nix ? flakeModule) ./formatter.nix;
-      }
-    );
+          ++
+            # only importing existing paths allows to minimize the flake for test
+            # by removing files
+            filter pathExists [
+              ./checks/flake-module.nix
+              ./clanModules/flake-module.nix
+              ./clanServices/flake-module.nix
+              ./devShell.nix
+              ./docs/nix/flake-module.nix
+              ./flakeModules/demo_iso.nix
+              ./flakeModules/flake-module.nix
+              ./lib/filter-clan-core/flake-module.nix
+              ./lib/flake-module.nix
+              ./lib/flake-parts/clan-nixos-test.nix
+              ./nixosModules/clanCore/vars/flake-module.nix
+              ./nixosModules/flake-module.nix
+              ./pkgs/clan-cli/clan_cli/tests/flake-module.nix
+              ./pkgs/flake-module.nix
+              ./templates/flake-module.nix
+            ]
+          ++ [
+            (if pathExists ./flakeModules/clan.nix then import ./flakeModules/clan.nix inputs.self else { })
+          ]
+          # Make treefmt-nix optional
+          # This only works if you set inputs.clan-core.inputs.treefmt-nix.follows
+          # to a non-empty input that doesn't export a flakeModule
+          ++ optional (pathExists ./formatter.nix && inputs.treefmt-nix ? flakeModule) ./formatter.nix;
+        }
+      );
 }

flakeModules/clan.nix

@@ -22,26 +22,50 @@ in
       default = config.flake.clan.clanInternals;
     };
     # The clan module
-    clan = lib.mkOption {
-      description = "Clan module. Define your clan inside here";
-      default = { };
-      type = types.submoduleWith {
-        class = "clan";
-        specialArgs =
-          # TODO: make these explizit options and deduplicate with lib.clan function
-          let
-            nixpkgs = inputs.nixpkgs or clan-core.inputs.nixpkgs;
-            nix-darwin = inputs.nix-darwin or clan-core.inputs.nix-darwin;
-          in
-          {
+    clan =
+      # TODO: make these explizit options and deduplicate with lib.clan function
+      let
+        nixpkgs = inputs.nixpkgs or clan-core.inputs.nixpkgs;
+        nix-darwin = inputs.nix-darwin or clan-core.inputs.nix-darwin;
+      in
+      lib.mkOption {
+        description = "Clan module. Define your clan inside here";
+        default = { };
+        type = types.submoduleWith {
+          class = "clan";
+          specialArgs = {
             inherit self;
             inherit nixpkgs nix-darwin;
           };
-        modules = [
-          clan-core.modules.clan.default
-        ];
+          modules = [
+            clan-core.modules.clan.default
+            {
+              checks.minNixpkgsVersion = {
+                assertion = lib.versionAtLeast nixpkgs.lib.version "25.11";
+                message = ''
+                  Nixpkgs version: ${nixpkgs.lib.version} is incompatible with clan-core. (>= 25.11 is recommended)
+                  ---
+                  Your version of 'nixpkgs' seems too old for clan-core.
+                  Please read: https://docs.clan.lol/guides/nixpkgs-flake-input
+
+                  You can ignore this check by setting:
+                  clan.checks.minNixpkgsVersion.ignore = true;
+                  ---
+                '';
+              };
+            }
+          ];
+        };
+        apply =
+          config:
+          lib.deepSeq (lib.mapAttrs (
+            id: check:
+            if check.ignore || check.assertion then
+              null
+            else
+              throw "clan.checks.${id} failed with message\n${check.message}"
+          ) config.checks) config;
       };
-    };
 
     # Mapped flake toplevel outputs
     darwinConfigurations = lib.mkOption {

formatter.nix

@@ -11,8 +11,6 @@
       treefmt.programs.nixfmt.enable = true;
       treefmt.programs.nixfmt.package = pkgs.nixfmt-rfc-style;
       treefmt.programs.deadnix.enable = true;
-      treefmt.programs.sizelint.enable = true;
-      treefmt.programs.sizelint.failOnWarn = true;
       treefmt.programs.clang-format.enable = true;
       treefmt.settings.global.excludes = [
         "*.png"
@@ -52,8 +50,6 @@
         "checks/secrets/sops/groups/group/machines/machine"
         "checks/syncthing/introducer/introducer_device_id"
         "checks/syncthing/introducer/introducer_test_api"
-        "docs/site/static/asciinema-player/asciinema-player.css"
-        "docs/site/static/asciinema-player/asciinema-player.min.js"
         "nixosModules/clanCore/vars/secret/sops/eval-tests/populated/vars/my_machine/my_generator/my_secret"
         "pkgs/clan-cli/clan_cli/tests/data/gnupg.conf"
         "pkgs/clan-cli/clan_cli/tests/data/password-store/.gpg-id"
@@ -94,9 +90,6 @@
           "*.yaml"
           "*.yml"
         ];
-        excludes = [
-          "*/asciinema-player/*"
-        ];
       };
       treefmt.programs.mypy.directories = {
         "clan-cli" = {