Merge pull request 'Reapply "clan.core: rename clan.{deployment,networking} -> clan.core.{deployment,networking}"' (#1787) from Qubasa/clan-core:Qubasa-main into main

This reverts commit 9778444706.

workaround upstream bug: https://github.com/NixOS/nixpkgs/issues/324802

.envrc

@@ -1,3 +1,4 @@
+# shellcheck shell=bash
 if ! has nix_direnv_version || ! nix_direnv_version 3.0.4; then
   source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.4/direnvrc" "sha256-DzlYZ33mWF/Gs8DDeyjr8mnVmQGx7ASYqA5WlxwvBG4="
 fi
@@ -5,7 +6,7 @@ fi
 watch_file .direnv/selected-shell 
 
 if [ -e .direnv/selected-shell ]; then
-  use flake .#$(cat .direnv/selected-shell)
+  use flake ".#$(cat .direnv/selected-shell)"
 else
   use flake
 fi

.gitignore

@@ -3,6 +3,7 @@
 out.log
 .coverage.*
 **/qubeclan
+pkgs/repro-hook
 **/testdir
 democlan
 example_clan
@@ -13,6 +14,7 @@ nixos.qcow2
 **/*.glade~
 /docs/out
 
+
 # dream2nix
 .dream2nix
 

README.md

@@ -1,6 +1,6 @@
-# Clan Core Repository
+# Clan core repository
 
-Welcome to the Clan Core Repository, the heart of the [clan.lol](https://clan.lol/) project! This monorepo is the foundation of Clan, a revolutionary open-source project aimed at restoring fun, freedom, and functionality to computing. Here, you'll find all the essential packages, NixOS modules, CLI tools, and tests needed to contribute to and work with the Clan project. Clan leverages the Nix system to ensure reliability, security, and seamless management of digital environments, putting the power back into the hands of users.
+Welcome to the Clan core repository, the heart of the [clan.lol](https://clan.lol/) project! This monorepo is the foundation of Clan, a revolutionary open-source project aimed at restoring fun, freedom, and functionality to computing. Here, you'll find all the essential packages, NixOS modules, CLI tools, and tests needed to contribute to and work with the Clan project. Clan leverages the Nix system to ensure reliability, security, and seamless management of digital environments, putting the power back into the hands of users.
 
 ## Why Clan?
 
@@ -14,13 +14,13 @@ Our mission is simple: to democratize computing by providing tools that empower
 - **Robust Backup Management:** Long-term, self-hosted data preservation.
 - **Intuitive Secret Management:** Simplified encryption and password management processes.
 
-## Getting Started with Clan
+## Getting started with Clan
 
 If you're new to Clan and eager to dive in, start with our quickstart guide and explore the core functionalities that Clan offers:
 
 - **Quickstart Guide**: Check out [getting started](https://docs.clan.lol/#starting-with-a-new-clan-project)<!-- [docs/site/index.md](docs/site/index.md) --> to get up and running with Clan in no time.
 
-### Managing Secrets
+### Managing secrets
 
 In the Clan ecosystem, security is paramount. Learn how to handle secrets effectively:
 
@@ -32,11 +32,11 @@ The Clan project thrives on community contributions. We welcome everyone to cont
 
 - **Contribution Guidelines**: Make a meaningful impact by following the steps in [contributing](https://docs.clan.lol/contributing/contributing/)<!-- [contributing.md](docs/CONTRIBUTING.md) -->.
 
-## Join the Revolution
+## Join the revolution
 
 Clan is more than a tool; it's a movement towards a better digital future. By contributing to the Clan project, you're part of changing technology for the better, together.
 
-### Community and Support
+### Community and support
 
 Connect with us and the Clan community for support and discussion:
 

checks/backups/flake-module.nix

@@ -27,7 +27,7 @@
           self.clanModules.localbackup
           self.clanModules.sshd
         ];
-        clan.networking.targetHost = "machine";
+        clan.core.networking.targetHost = "machine";
         networking.hostName = "machine";
         services.openssh.settings.UseDns = false;
 

checks/impure/flake-module.nix

@@ -1,6 +1,11 @@
 {
   perSystem =
-    { pkgs, lib, ... }:
+    {
+      pkgs,
+      lib,
+      self',
+      ...
+    }:
     {
       # a script that executes all other checks
       packages.impure-checks = pkgs.writeShellScriptBin "impure-checks" ''
@@ -10,14 +15,21 @@
         unset CLAN_DIR
 
         export PATH="${
-          lib.makeBinPath [
+          lib.makeBinPath (
-            pkgs.gitMinimal
+            [
-            pkgs.nix
+              pkgs.gitMinimal
-            pkgs.rsync # needed to have rsync installed on the dummy ssh server
+              pkgs.nix
-          ]
+              pkgs.rsync # needed to have rsync installed on the dummy ssh server
+            ]
+            ++ self'.packages.clan-cli-full.runtimeDependencies
+          )
         }"
         ROOT=$(git rev-parse --show-toplevel)
         cd "$ROOT/pkgs/clan-cli"
+
+        # this disables dynamic dependency loading in clan-cli
+        export CLAN_NO_DYNAMIC_DEPS=1
+
         nix develop "$ROOT#clan-cli" -c bash -c "TMPDIR=/tmp python -m pytest -s -m impure ./tests $@"
       '';
     };

checks/installation/flake-module.nix

@@ -1,7 +1,7 @@
 { self, lib, ... }:
 {
   clan.machines.test_install_machine = {
-    clan.networking.targetHost = "test_install_machine";
+    clan.core.networking.targetHost = "test_install_machine";
     fileSystems."/".device = lib.mkDefault "/dev/vdb";
     boot.loader.grub.device = lib.mkDefault "/dev/vdb";
 
@@ -12,7 +12,7 @@
       { lib, modulesPath, ... }:
       {
         imports = [
-          self.clanModules.disk-layouts
+          "${self}/nixosModules/disk-layouts"
           (modulesPath + "/testing/test-instrumentation.nix") # we need these 2 modules always to be able to run the tests
           (modulesPath + "/profiles/qemu-guest.nix")
         ];

clanModules/borgbackup-static/README.md

@@ -1,4 +1,5 @@
-Statically configure borgbackup with sane defaults.
+---
+description = "Statically configure borgbackup with sane defaults."
 ---
 This module implements the `borgbackup` backend and implements sane defaults
 for backup management through `borgbackup` for members of the clan.

clanModules/borgbackup-static/default.nix

@@ -3,7 +3,7 @@ let
   clanDir = config.clan.core.clanDir;
   machineDir = clanDir + "/machines/";
 in
-{
+lib.warn "This module is deprecated use the service via the inventory interface instead." {
   imports = [ ../borgbackup ];
 
   options.clan.borgbackup-static = {

clanModules/borgbackup/README.md

@@ -1,2 +1,13 @@
-Efficient, deduplicating backup program with optional compression and secure encryption.
 ---
+description = "Efficient, deduplicating backup program with optional compression and secure encryption."
+categories = ["backup"]
+---
+BorgBackup (short: Borg) gives you:
+
+- Space efficient storage of backups.
+- 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.

clanModules/borgbackup/default.nix

@@ -28,7 +28,51 @@ let
     fi
   '';
 in
+# Each .nix file in the roles directory is a role
+# TODO: Helper function to set available roles within module meta.
+# roles =
+#   if builtins.pathExists ./roles then
+#     lib.pipe ./roles [
+#       builtins.readDir
+#       (lib.filterAttrs (_n: v: v == "regular"))
+#       lib.attrNames
+#       (map (fileName: lib.removeSuffix ".nix" fileName))
+#     ]
+#   else
+#     null;
+# TODO: make this an interface of every module
+# Maybe load from readme.md
+# metaInfoOption = lib.mkOption {
+#   readOnly = true;
+#   description = ''
+#     Meta is used to retrieve information about this module.
+#     - `availableRoles` is a list of roles that can be assigned via the inventory.
+#     - `category` is used to group services in the clan marketplace.
+#     - `description` is a short description of the service for the clan marketplace.
+#   '';
+#   default = {
+#     description = "Borgbackup is a backup program. Optionally, it supports compression and authenticated encryption.";
+#     availableRoles = roles;
+#     category = "backup";
+#   };
+#   type = lib.types.submodule {
+#     options = {
+#       description = lib.mkOption { type = lib.types.str; };
+#       availableRoles = lib.mkOption { type = lib.types.nullOr (lib.types.listOf lib.types.str); };
+#       category = lib.mkOption {
+#         description = "A category for the service. This is used to group services in the clan ui";
+#         type = lib.types.enum [
+#           "backup"
+#           "network"
+#         ];
+#       };
+#     };
+#   };
+# };
 {
+
+  # options.clan.borgbackup.meta = metaInfoOption;
+
   options.clan.borgbackup.destinations = lib.mkOption {
     type = lib.types.attrsOf (
       lib.types.submodule (
@@ -76,7 +120,7 @@ in
       lib.nameValuePair "borgbackup-job-${dest.name}" {
         # since borgbackup mounts the system read-only, we need to run in a ExecStartPre script, so we can generate additional files.
         serviceConfig.ExecStartPre = [
-          (''+${pkgs.writeShellScript "borgbackup-job-${dest.name}-pre-backup-commands" preBackupScript}'')
+          ''+${pkgs.writeShellScript "borgbackup-job-${dest.name}-pre-backup-commands" preBackupScript}''
         ];
       }
     ) cfg.destinations;

clanModules/borgbackup/roles/client.nix

@@ -0,0 +1,30 @@
+{ config, lib, ... }:
+let
+  instances = config.clan.inventory.services.borgbackup;
+  # roles = { ${role_name} :: { machines :: [string] } }
+  allServers = lib.foldlAttrs (
+    acc: _instanceName: instanceConfig:
+    acc
+    ++ (
+      if builtins.elem machineName instanceConfig.roles.client.machines then
+        instanceConfig.roles.server.machines
+      else
+        [ ]
+    )
+  ) [ ] instances;
+
+  inherit (config.clan.core) machineName;
+in
+{
+  config.clan.borgbackup.destinations =
+    let
+
+      destinations = builtins.map (serverName: {
+        name = serverName;
+        value = {
+          repo = "borg@${serverName}:/var/lib/borgbackup/${machineName}";
+        };
+      }) allServers;
+    in
+    (builtins.listToAttrs destinations);
+}

clanModules/borgbackup/roles/server.nix

@@ -0,0 +1,51 @@
+{ config, lib, ... }:
+let
+  clanDir = config.clan.core.clanDir;
+  machineDir = clanDir + "/machines/";
+  inherit (config.clan.core) machineName;
+
+  instances = config.clan.inventory.services.borgbackup;
+
+  # roles = { ${role_name} :: { machines :: [string] } }
+
+  allClients = lib.foldlAttrs (
+    acc: _instanceName: instanceConfig:
+    acc
+    ++ (
+      if (builtins.elem machineName instanceConfig.roles.server.machines) then
+        instanceConfig.roles.client.machines
+      else
+        [ ]
+    )
+  ) [ ] instances;
+in
+{
+  config.services.borgbackup.repos =
+    let
+      borgbackupIpMachinePath = machines: machineDir + machines + "/facts/borgbackup.ssh.pub";
+      machinesMaybeKey = builtins.map (
+        machine:
+        let
+          fullPath = borgbackupIpMachinePath machine;
+        in
+        if builtins.pathExists fullPath then
+          machine
+        else
+          lib.warn ''
+            Machine ${machine} does not have a borgbackup key at ${fullPath},
+            run `clan facts generate ${machine}` to generate it.
+          '' null
+      ) allClients;
+
+      machinesWithKey = lib.filter (x: x != null) machinesMaybeKey;
+
+      hosts = builtins.map (machine: {
+        name = machine;
+        value = {
+          path = "/var/lib/borgbackup/${machine}";
+          authorizedKeys = [ (builtins.readFile (borgbackupIpMachinePath machine)) ];
+        };
+      }) machinesWithKey;
+    in
+    if (builtins.listToAttrs hosts) != [ ] then builtins.listToAttrs hosts else { };
+}

clanModules/deltachat/README.md

@@ -1,4 +1,5 @@
-Email-based instant messaging for Desktop.
+---
+description = "Email-based instant messaging for Desktop."
 ---
 
 !!! warning "Under construction"

clanModules/disk-layouts/README.md

@@ -1,2 +0,0 @@
-Automatically format a disk drive on clan installation
----

clanModules/ergochat/README.md

@@ -1,2 +1,3 @@
-A modern IRC server
+---
+description = "A modern IRC server"
 ---

clanModules/flake-module.nix

@@ -1,17 +1,16 @@
 { ... }:
 {
   flake.clanModules = {
-    disk-layouts = {
-      imports = [ ./disk-layouts ];
-    };
     borgbackup = ./borgbackup;
     borgbackup-static = ./borgbackup-static;
     deltachat = ./deltachat;
     ergochat = ./ergochat;
     localbackup = ./localbackup;
     localsend = ./localsend;
+    single-disk = ./single-disk;
     matrix-synapse = ./matrix-synapse;
     moonlight = ./moonlight;
+    packages = ./packages;
     postgresql = ./postgresql;
     root-password = ./root-password;
     sshd = ./sshd;

clanModules/localbackup/README.md

@@ -1,2 +1,3 @@
-Automatically backups current machine to local directory.
+---
+description = "Automatically backups current machine to local directory."
 ---

clanModules/localsend/README.md

@@ -1,2 +1,3 @@
-Securely sharing files and messages over a local network without internet connectivity.
+---
+description = "Securely sharing files and messages over a local network without internet connectivity."
 ---

clanModules/matrix-synapse/0001-register_new_matrix_user-add-password-file-flag.patch

@@ -1,100 +0,0 @@
-From bc199a27f23b0fcf175b116f7cf606c0d22b422a Mon Sep 17 00:00:00 2001
-From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
-Date: Tue, 11 Jun 2024 11:40:47 +0200
-Subject: [PATCH 1/2] register_new_matrix_user: add password-file flag
-MIME-Version: 1.0
-Content-Type: text/plain; charset=UTF-8
-Content-Transfer-Encoding: 8bit
-
-getpass in python expects stdin to be a tty, hence we cannot just pipe
-into register_new_matrix_user. --password-file instead works better and
-it would also allow the use of stdin if /dev/stdin is passed.
-
-Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
-Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
----
- changelog.d/17294.feature                    |  2 ++
- debian/register_new_matrix_user.ronn         |  9 +++++++--
- synapse/_scripts/register_new_matrix_user.py | 20 +++++++++++++++-----
- 3 files changed, 24 insertions(+), 7 deletions(-)
- create mode 100644 changelog.d/17294.feature
-
-diff --git a/changelog.d/17294.feature b/changelog.d/17294.feature
-new file mode 100644
-index 000000000..33aac7b0b
---- /dev/null
-+++ b/changelog.d/17294.feature
-@@ -0,0 +1,2 @@
-+`register_new_matrix_user` now supports a --password-file flag, which
-+is useful for scripting.
-diff --git a/debian/register_new_matrix_user.ronn b/debian/register_new_matrix_user.ronn
-index 0410b1f4c..d99e9215a 100644
---- a/debian/register_new_matrix_user.ronn
-+++ b/debian/register_new_matrix_user.ronn
-@@ -31,8 +31,13 @@ A sample YAML file accepted by `register_new_matrix_user` is described below:
-     Local part of the new user. Will prompt if omitted.
- 
-   * `-p`, `--password`:
--    New password for user. Will prompt if omitted. Supplying the password
--    on the command line is not recommended. Use the STDIN instead.
-+    New password for user. Will prompt if this option and `--password-file` are omitted.
-+    Supplying the password on the command line is not recommended.
-+    Use `--password-file` if possible.
-+
-+  * `--password-file`:
-+    File containing the new password for user. If set, overrides `--password`.
-+    This is a more secure alternative to specifying the password on the command line.
- 
-   * `-a`, `--admin`:
-     Register new user as an admin. Will prompt if omitted.
-diff --git a/synapse/_scripts/register_new_matrix_user.py b/synapse/_scripts/register_new_matrix_user.py
-index 77a7129ee..972b35e2d 100644
---- a/synapse/_scripts/register_new_matrix_user.py
-+++ b/synapse/_scripts/register_new_matrix_user.py
-@@ -173,11 +173,18 @@ def main() -> None:
-         default=None,
-         help="Local part of the new user. Will prompt if omitted.",
-     )
--    parser.add_argument(
-+    password_group = parser.add_mutually_exclusive_group()
-+    password_group.add_argument(
-         "-p",
-         "--password",
-         default=None,
--        help="New password for user. Will prompt if omitted.",
-+        help="New password for user. Will prompt for a password if "
-+        "this flag and `--password-file` are both omitted.",
-+    )
-+    password_group.add_argument(
-+        "--password-file",
-+        default=None,
-+        help="File containing the new password for user. If set, will override `--password`.",
-     )
-     parser.add_argument(
-         "-t",
-@@ -247,6 +254,11 @@ def main() -> None:
-             print(_NO_SHARED_SECRET_OPTS_ERROR, file=sys.stderr)
-             sys.exit(1)
- 
-+    if args.password_file:
-+        password = _read_file(args.password_file, "password-file").strip()
-+    else:
-+        password = args.password
-+
-     if args.server_url:
-         server_url = args.server_url
-     elif config is not None:
-@@ -269,9 +281,7 @@ def main() -> None:
-     if args.admin or args.no_admin:
-         admin = args.admin
- 
--    register_new_user(
--        args.user, args.password, server_url, secret, admin, args.user_type
--    )
-+    register_new_user(args.user, password, server_url, secret, admin, args.user_type)
- 
- 
- def _read_file(file_path: Any, config_path: str) -> str:
--- 
-2.44.1
-

clanModules/matrix-synapse/0002-register-new-matrix-user-add-a-flag-to-ignore-alread.patch

@@ -1,94 +0,0 @@
-From 1789416df425d22693b0055a6688d8686e0ee4a1 Mon Sep 17 00:00:00 2001
-From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
-Date: Thu, 13 Jun 2024 14:38:19 +0200
-Subject: [PATCH 2/2] register-new-matrix-user: add a flag to ignore already
- existing users
-MIME-Version: 1.0
-Content-Type: text/plain; charset=UTF-8
-Content-Transfer-Encoding: 8bit
-
-This allows to register users in a more declarative and stateless way.
-
-Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
----
- synapse/_scripts/register_new_matrix_user.py | 22 ++++++++++++++++++--
- 1 file changed, 20 insertions(+), 2 deletions(-)
-
-diff --git a/synapse/_scripts/register_new_matrix_user.py b/synapse/_scripts/register_new_matrix_user.py
-index 972b35e2d..233e7267d 100644
---- a/synapse/_scripts/register_new_matrix_user.py
-+++ b/synapse/_scripts/register_new_matrix_user.py
-@@ -52,6 +52,7 @@ def request_registration(
-     user_type: Optional[str] = None,
-     _print: Callable[[str], None] = print,
-     exit: Callable[[int], None] = sys.exit,
-+    exists_ok: bool = False,
- ) -> None:
-     url = "%s/_synapse/admin/v1/register" % (server_location.rstrip("/"),)
- 
-@@ -97,6 +98,10 @@ def request_registration(
-     r = requests.post(url, json=data)
- 
-     if r.status_code != 200:
-+        response = r.json()
-+        if exists_ok and response["errcode"] == "M_USER_IN_USE":
-+            _print("User already exists. Skipping.")
-+            return
-         _print("ERROR! Received %d %s" % (r.status_code, r.reason))
-         if 400 <= r.status_code < 500:
-             try:
-@@ -115,6 +120,7 @@ def register_new_user(
-     shared_secret: str,
-     admin: Optional[bool],
-     user_type: Optional[str],
-+    exists_ok: bool = False,
- ) -> None:
-     if not user:
-         try:
-@@ -154,7 +160,13 @@ def register_new_user(
-             admin = False
- 
-     request_registration(
--        user, password, server_location, shared_secret, bool(admin), user_type
-+        user,
-+        password,
-+        server_location,
-+        shared_secret,
-+        bool(admin),
-+        user_type,
-+        exists_ok=exists_ok,
-     )
- 
- 
-@@ -173,6 +185,11 @@ def main() -> None:
-         default=None,
-         help="Local part of the new user. Will prompt if omitted.",
-     )
-+    parser.add_argument(
-+        "--exists-ok",
-+        action="store_true",
-+        help="Do not fail if user already exists.",
-+    )
-     password_group = parser.add_mutually_exclusive_group()
-     password_group.add_argument(
-         "-p",
-@@ -192,6 +209,7 @@ def main() -> None:
-         default=None,
-         help="User type as specified in synapse.api.constants.UserTypes",
-     )
-+
-     admin_group = parser.add_mutually_exclusive_group()
-     admin_group.add_argument(
-         "-a",
-@@ -281,7 +299,7 @@ def main() -> None:
-     if args.admin or args.no_admin:
-         admin = args.admin
- 
--    register_new_user(args.user, password, server_url, secret, admin, args.user_type)
-+    register_new_user(args.user, password, server_url, secret, admin, args.user_type, exists_ok=args.exists_ok)
- 
- 
- def _read_file(file_path: Any, config_path: str) -> str:
--- 
-2.44.1
-

clanModules/matrix-synapse/README.md

@@ -1,2 +1,3 @@
-A federated messaging server with end-to-end encryption.
+---
+description = "A federated messaging server with end-to-end encryption."
 ---

clanModules/matrix-synapse/default.nix

@@ -16,20 +16,8 @@ let
           > $out/config.json < ${pkgs.element-web}/config.json
         ln -s $out/config.json $out/config.${nginx-vhost}.json
       '';
-
-  # FIXME: This was taken from upstream. Drop this when our patch is upstream
-  synapseCfg = config.services.matrix-synapse;
-  wantedExtras =
-    synapseCfg.extras
-    ++ lib.optional (synapseCfg.settings ? oidc_providers) "oidc"
-    ++ lib.optional (synapseCfg.settings ? jwt_config) "jwt"
-    ++ lib.optional (synapseCfg.settings ? saml2_config) "saml2"
-    ++ lib.optional (synapseCfg.settings ? redis) "redis"
-    ++ lib.optional (synapseCfg.settings ? sentry) "sentry"
-    ++ lib.optional (synapseCfg.settings ? user_directory) "user-search"
-    ++ lib.optional (synapseCfg.settings.url_preview_enabled) "url-preview"
-    ++ lib.optional (synapseCfg.settings.database.name == "psycopg2") "postgres";
 in
+# FIXME: This was taken from upstream. Drop this when our patch is upstream
 {
   options.services.matrix-synapse.package = lib.mkOption { readOnly = false; };
   options.clan.matrix-synapse = {
@@ -78,21 +66,6 @@ in
   ];
   config = {
     services.matrix-synapse = {
-      package = lib.mkForce (
-        pkgs.matrix-synapse.override {
-          matrix-synapse-unwrapped = pkgs.matrix-synapse.unwrapped.overrideAttrs (_old: {
-            doInstallCheck = false; # too slow, nixpkgs maintainer already run this.
-            patches = [
-              # see: https://github.com/element-hq/synapse/pull/17304
-              ./0001-register_new_matrix_user-add-password-file-flag.patch
-              ./0002-register-new-matrix-user-add-a-flag-to-ignore-alread.patch
-            ];
-          });
-          extras = wantedExtras;
-          plugins = synapseCfg.plugins;
-        }
-      );
-
       enable = true;
       settings = {
         server_name = cfg.domain;

clanModules/moonlight/README.md

@@ -1,2 +1,3 @@
-A desktop streaming client optimized for remote gaming and synchronized movie viewing.
+---
+description = "A desktop streaming client optimized for remote gaming and synchronized movie viewing."
 ---

clanModules/packages/README.md

@@ -0,0 +1,4 @@
+---
+description = "Define package sets from nixpkgs and install them on one or more machines"
+categories = ["packages"]
+---

clanModules/packages/default.nix

@@ -0,0 +1,19 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+{
+  options.clan.packages = {
+    packages = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      description = "The packages to install on the machine";
+    };
+  };
+  config = {
+    environment.systemPackages = map (
+      pName: lib.getAttrFromPath (lib.splitString "." pName) pkgs
+    ) config.clan.packages.packages;
+  };
+}

clanModules/packages/roles/default.nix

@@ -0,0 +1 @@
+{ }

clanModules/postgresql/README.md

@@ -1,2 +1,3 @@
-A free and open-source relational database management system (RDBMS) emphasizing extensibility and SQL compliance.
+---
+description = "A free and open-source relational database management system (RDBMS) emphasizing extensibility and SQL compliance."
 ---

clanModules/postgresql/default.nix

@@ -91,6 +91,7 @@ in
   options.clan.postgresql = {
     # we are reimplemeting ensureDatabase and ensureUser options here to allow to create databases with options
     databases = lib.mkOption {
+      description = "Databases to create";
       default = { };
       type = lib.types.attrsOf (
         lib.types.submodule (
@@ -114,6 +115,7 @@ in
                 description = "Create the database if it does not exist.";
               };
               create.options = lib.mkOption {
+                description = "Options to pass to the CREATE DATABASE command.";
                 type = lib.types.lazyAttrsOf lib.types.str;
                 default = { };
                 example = {
@@ -135,12 +137,14 @@ in
       );
     };
     users = lib.mkOption {
+      description = "Users to create";
       default = { };
       type = lib.types.attrsOf (
         lib.types.submodule (
           { name, ... }:
           {
             options.name = lib.mkOption {
+              description = "User name";
               type = lib.types.str;
               default = name;
             };

clanModules/root-password/README.md

@@ -1,4 +1,5 @@
-Automatically generates and configures a password for the root user.
+---
+description = "Automatically generates and configures a password for the root user."
 ---
 
 After the system was installed/deployed the following command can be used to display the root-password:

clanModules/root-password/default.nix

@@ -13,8 +13,8 @@
       mkpasswd
     ];
     generator.script = ''
-      xkcdpass --numwords 3 --delimiter - --count 1 > $secrets/password
+      xkcdpass --numwords 3 --delimiter - --count 1 | tr -d "\n" > $secrets/password
-      cat $secrets/password | mkpasswd -s -m sha-512 > $secrets/password-hash
+      cat $secrets/password | mkpasswd -s -m sha-512 | tr -d "\n" > $secrets/password-hash
     '';
   };
 }

clanModules/single-disk/README.md

@@ -0,0 +1,42 @@
+---
+description = "Configures partitioning of the main disk"
+categories = ["disk-layout"]
+---
+# Primary Disk Layout
+
+A module for the "disk-layout" category MUST be choosen.
+
+There is exactly one slot for this type of module in the UI, if you don't fill the slot, your machine cannot boot
+
+This module is a good choice for most machines. In the future clan will offer a broader choice of disk-layouts
+
+The UI will ask for the options of this module:
+
+`device: "/dev/null"`
+
+# Usage example
+
+`inventory.json`
+```json
+"services": {
+    "single-disk": {
+        "default": {
+            "meta": {
+                "name": "single-disk"
+            },
+            "roles": {
+                "default": {
+                    "machines": ["jon"]
+                }
+            },
+            "machines": {
+                "jon": {
+                    "config": {
+                        "device": "/dev/null"
+                    }
+                }
+            }
+        }
+    }
+}
+```

clanModules/single-disk/default.nix

@@ -0,0 +1,53 @@
+{ lib, config, ... }:
+{
+  options.clan.single-disk = {
+    device = lib.mkOption {
+      default = null;
+      type = lib.types.nullOr lib.types.str;
+      description = "The primary disk device to install the system on";
+      # Question: should we set a default here?
+      # default = "/dev/null";
+    };
+  };
+  config = {
+    boot.loader.grub.efiSupport = lib.mkDefault true;
+    boot.loader.grub.efiInstallAsRemovable = lib.mkDefault true;
+    disko.devices = {
+      disk = {
+        main = {
+          type = "disk";
+          # This is set through the UI
+          device = config.clan.single-disk.device;
+
+          content = {
+            type = "gpt";
+            partitions = {
+              boot = {
+                size = "1M";
+                type = "EF02"; # for grub MBR
+                priority = 1;
+              };
+              ESP = {
+                size = "512M";
+                type = "EF00";
+                content = {
+                  type = "filesystem";
+                  format = "vfat";
+                  mountpoint = "/boot";
+                };
+              };
+              root = {
+                size = "100%";
+                content = {
+                  type = "filesystem";
+                  format = "ext4";
+                  mountpoint = "/";
+                };
+              };
+            };
+          };
+        };
+      };
+    };
+  };
+}

clanModules/single-disk/roles/default.nix

@@ -0,0 +1 @@
+{ }

clanModules/sshd/README.md

@@ -1,2 +1,3 @@
-Enables secure remote access to the machine over ssh
+---
+description = "Enables secure remote access to the machine over ssh"
 ---

clanModules/static-hosts/README.md

@@ -1,2 +1,3 @@
-Statically configure the host names of machines based on their respective zerotier-ip.
+---
+description = "Statically configure the host names of machines based on their respective zerotier-ip."
 ---

clanModules/sunshine/README.md

@@ -1,2 +1,3 @@
-A desktop streaming server optimized for remote gaming and synchronized movie viewing.
+---
+description = "A desktop streaming server optimized for remote gaming and synchronized movie viewing."
 ---

clanModules/syncthing-static-peers/README.md

@@ -1,2 +1,3 @@
-Statically configure syncthing peers through clan
+---
+description = "Statically configure syncthing peers through clan"
 ---

clanModules/syncthing/README.md

@@ -1,4 +1,5 @@
-A secure, file synchronization app for devices over networks, offering a private alternative to cloud services.
+---
+description = "A secure, file synchronization app for devices over networks, offering a private alternative to cloud services."
 ---
 ## Usage
 

clanModules/syncthing/default.nix

@@ -7,6 +7,10 @@
 {
   options.clan.syncthing = {
     id = lib.mkOption {
+      description = ''
+        The ID of the machine.
+        It is generated automatically by default.
+      '';
       type = lib.types.nullOr lib.types.str;
       example = "BABNJY4-G2ICDLF-QQEG7DD-N3OBNGF-BCCOFK6-MV3K7QJ-2WUZHXS-7DTW4AS";
       default = config.clan.core.facts.services.syncthing.public."syncthing.pub".value or null;
@@ -94,7 +98,7 @@
         settings = {
           options = {
             urAccepted = -1;
-            allowedNetworks = [ config.clan.networking.zerotier.subnet ];
+            allowedNetworks = [ config.clan.core.networking.zerotier.subnet ];
           };
           devices =
             { }

clanModules/thelounge/README.md

@@ -1,2 +1,3 @@
-Modern web IRC client
+---
+description = "Modern web IRC client"
 ---

clanModules/trusted-nix-caches/README.md

@@ -1,2 +1,3 @@
-This module sets the `clan.lol` and `nix-community` cache up as a trusted cache.
+---
+description = "This module sets the `clan.lol` and `nix-community` cache up as a trusted cache."
 ----

clanModules/user-password/README.md

@@ -1,4 +1,5 @@
-Automatically generates and configures a password for the specified user account.
+---
+description = "Automatically generates and configures a password for the specified user account."
 ---
 
 If setting the option prompt to true, the user will be prompted to type in their desired password.

clanModules/user-password/default.nix

@@ -37,12 +37,12 @@
         mkpasswd
       ];
       generator.script = ''
-        if [[ -n $prompt_value ]]; then
+        if [[ -n ''${prompt_value-} ]]; then
-          echo $prompt_value > $secrets/user-password
+          echo $prompt_value | tr -d "\n" > $secrets/user-password
         else
-          xkcdpass --numwords 3 --delimiter - --count 1 > $secrets/user-password
+          xkcdpass --numwords 3 --delimiter - --count 1 | tr -d "\n" > $secrets/user-password
         fi
-        cat $secrets/user-password | mkpasswd -s -m sha-512 > $secrets/user-password-hash
+        cat $secrets/user-password | mkpasswd -s -m sha-512 | tr -d "\n" > $secrets/user-password-hash
       '';
     };
   };

clanModules/xfce/README.md

@@ -1,2 +1,3 @@
-A lightweight desktop manager
+---
+description = "A lightweight desktop manager"
 ---

clanModules/zerotier-static-peers/README.md

@@ -1,4 +1,5 @@
-Statically configure the `zerotier` peers of a clan network.
+---
+description = "Statically configure the `zerotier` peers of a clan network."
 ---
 Statically configure the `zerotier` peers of a clan network.
 

clanModules/zerotier-static-peers/default.nix

@@ -2,7 +2,6 @@
   lib,
   config,
   pkgs,
-  inputs,
   ...
 }:
 let
@@ -31,6 +30,16 @@ in
       default = [ config.clan.core.machineName ];
       description = "Hosts that should be excluded";
     };
+    networkIps = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      default = [ ];
+      description = "Extra zerotier network Ips that should be accepted";
+    };
+    networkIds = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      default = [ ];
+      description = "Extra zerotier network Ids that should be accepted";
+    };
   };
 
   config.systemd.services.zerotier-static-peers-autoaccept =
@@ -57,20 +66,22 @@ in
           lib.nameValuePair (builtins.readFile fullPath) [ machine ]
         ) filteredMachines
       );
+      allHostIPs = config.clan.zerotier-static-peers.networkIps ++ hosts;
     in
-    lib.mkIf (config.clan.networking.zerotier.controller.enable) {
+    lib.mkIf (config.clan.core.networking.zerotier.controller.enable) {
       wantedBy = [ "multi-user.target" ];
       after = [ "zerotierone.service" ];
-      path = [ pkgs.zerotierone ];
+      path = [ config.clan.core.clanPkgs.zerotierone ];
       serviceConfig.ExecStart = pkgs.writeScript "static-zerotier-peers-autoaccept" ''
         #!/bin/sh
         ${lib.concatMapStringsSep "\n" (host: ''
-          ${
+          ${config.clan.core.clanPkgs.zerotier-members}/bin/zerotier-members allow --member-ip ${host}
-            inputs.clan-core.packages.${pkgs.system}.zerotier-members
+        '') allHostIPs}
-          }/bin/zerotier-members allow --member-ip ${host}
+        ${lib.concatMapStringsSep "\n" (host: ''
-        '') hosts}
+          ${config.clan.core.clanPkgs.zerotier-members}/bin/zerotier-members allow ${host}
+        '') config.clan.zerotier-static-peers.networkIds}
       '';
     };
 
-  config.clan.networking.zerotier.networkId = lib.mkDefault networkId;
+  config.clan.core.networking.zerotier.networkId = lib.mkDefault networkId;
 }

clanModules/zt-tcp-relay/README.md

@@ -1,2 +1,3 @@
-Enable ZeroTier VPN over TCP for networks where UDP is blocked.
+---
+description = "Enable ZeroTier VPN over TCP for networks where UDP is blocked."
 ---

devShell.nix

@@ -26,6 +26,7 @@
       devShells.default = pkgs.mkShell {
         packages = [
           select-shell
+          pkgs.nix-unit
           pkgs.tea
           # Better error messages than nix 2.18
           pkgs.nixVersions.latest

docs/.envrc

@@ -1,6 +1,8 @@
+# shellcheck shell=bash
 source_up
 
-watch_file $(find ./nix -name "*.nix" -printf '%p ')
+mapfile -d '' -t nix_files < <(find ./nix -name "*.nix" -print0)
+watch_file "${nix_files[@]}"
 
 # Because we depend on nixpkgs sources, uploading to builders takes a long time
 use flake .#docs --builders ''

docs/.gitignore

@@ -1,3 +1,6 @@
-/site/reference
+/site/reference/clan-core
+/site/reference/clanModules
+/site/reference/nix-api/inventory.md
+/site/reference/cli
 /site/static/Roboto-Regular.ttf
 /site/static/FiraCode-VF.ttf

docs/CONTRIBUTING.md

@@ -44,6 +44,14 @@ Let's get your development environment up and running:
          ```bash
          git remote add upstream gitea@git.clan.lol:clan/clan-core.git
          ```
+5. **Create an access token**:
+      - Log in to Gitea.
+      - Go to your account settings.
+      - Navigate to the Applications section.
+      - Click Generate New Token.
+      - Name your token and select all available scopes.
+      - Generate the token and copy it for later use.
+      - Your access token is now ready to use with all permissions.
 
 5. **Register Your Gitea Account Locally**:
 
@@ -54,9 +62,8 @@ Let's get your development environment up and running:
       - Fill out the prompt as follows:
         - URL of Gitea instance: `https://git.clan.lol`
         - Name of new Login [git.clan.lol]:
-        - Do you have an access token? No
+        - Do you have an access token? Yes
-        - Username: YourUsername
+        - Token: <yourtoken>
-        - Password: YourPassword
         - Set Optional settings: No
 
 

docs/mkdocs.yml

@@ -14,6 +14,7 @@ markdown_extensions:
   - attr_list
   - footnotes
   - md_in_html
+  - def_list
   - meta
   - plantuml_markdown
   - pymdownx.emoji:
@@ -38,8 +39,6 @@ exclude_docs: |
   /drafts/
 
 nav:
-  - Blog:
-      - blog/index.md
   - Getting started:
       - index.md
       - Installer: getting-started/installer.md
@@ -49,19 +48,25 @@ nav:
       - Mesh VPN: getting-started/mesh-vpn.md
       - Backup & Restore: getting-started/backups.md
       - Flake-parts: getting-started/flake-parts.md
-  - Modules:
+  - Guides:
+      - guides/index.md
+      - Inventory: guides/inventory.md
+  - Reference:
+      - reference/index.md
       - Clan Modules:
+          - reference/clanModules/index.md
           - reference/clanModules/borgbackup-static.md
           - reference/clanModules/borgbackup.md
           - reference/clanModules/deltachat.md
-          - reference/clanModules/disk-layouts.md
           - reference/clanModules/ergochat.md
           - reference/clanModules/localbackup.md
           - reference/clanModules/localsend.md
           - reference/clanModules/matrix-synapse.md
           - reference/clanModules/moonlight.md
+          - reference/clanModules/packages.md
           - reference/clanModules/postgresql.md
           - reference/clanModules/root-password.md
+          - reference/clanModules/single-disk.md
           - reference/clanModules/sshd.md
           - reference/clanModules/static-hosts.md
           - reference/clanModules/sunshine.md
@@ -85,6 +90,7 @@ nav:
           - reference/cli/secrets.md
           - reference/cli/show.md
           - reference/cli/ssh.md
+          - reference/cli/state.md
           - reference/cli/vms.md
       - Clan Core:
           - reference/clan-core/index.md
@@ -92,7 +98,15 @@ nav:
           - reference/clan-core/facts.md
           - reference/clan-core/sops.md
           - reference/clan-core/state.md
+          - reference/clan-core/deployment.md
+          - reference/clan-core/networking.md
+      - Nix API:
+          - reference/nix-api/index.md
+          - buildClan: reference/nix-api/buildclan.md
+          - Inventory: reference/nix-api/inventory.md
   - Contributing: contributing/contributing.md
+  - Blog:
+      - blog/index.md
 
 docs_dir: site
 site_dir: out

docs/nix/default.nix

@@ -2,6 +2,7 @@
   pkgs,
   module-docs,
   clan-cli-docs,
+  inventory-api-docs,
   asciinema-player-js,
   asciinema-player-css,
   roboto,
@@ -26,11 +27,13 @@ pkgs.stdenv.mkDerivation {
       mkdocs-material
       mkdocs-rss-plugin
       mkdocs-macros
+      filelock # FIXME: this should be already provided by mkdocs-rss-plugin
     ]);
   configurePhase = ''
     mkdir -p ./site/reference/cli
     cp -af ${module-docs}/* ./site/reference/
     cp -af ${clan-cli-docs}/* ./site/reference/cli/
+    cp -af ${inventory-api-docs} ./site/reference/nix-api/inventory.md
 
     mkdir -p ./site/static/asciinema-player
     ln -snf ${asciinema-player-js} ./site/static/asciinema-player/asciinema-player.min.js

docs/nix/flake-module.nix

@@ -12,13 +12,14 @@
       # { clanCore = «derivation JSON»; clanModules = { ${name} = «derivation JSON» }; }
       jsonDocs = import ./get-module-docs.nix {
         inherit (inputs) nixpkgs;
-        inherit pkgs self;
+        inherit pkgs;
         inherit (self.nixosModules) clanCore;
         inherit (self) clanModules;
       };
 
       clanModulesFileInfo = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModules);
-      clanModulesReadmes = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesReadmes);
+      # clanModulesReadmes = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesReadmes);
+      # clanModulesMeta = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesMeta);
 
       # Simply evaluated options (JSON)
       renderOptions =
@@ -29,6 +30,7 @@
             nativeBuildInputs = [
               pkgs.python3
               pkgs.mypy
+              self'.packages.clan-cli
             ];
           }
           ''
@@ -36,7 +38,7 @@
             patchShebangs --build $out
 
             ruff format --check --diff $out
-            ruff --line-length 88 $out
+            ruff check --line-length 88 $out
             mypy --strict $out
           '';
 
@@ -49,28 +51,39 @@
         sha256 = "sha256-GZMeZFFGvP5GMqqh516mjJKfQaiJ6bL38bSYOXkaohc=";
       };
 
-      module-docs = pkgs.runCommand "rendered" { nativeBuildInputs = [ pkgs.python3 ]; } ''
+      module-docs =
-        export CLAN_CORE=${jsonDocs.clanCore}/share/doc/nixos/options.json
+        pkgs.runCommand "rendered"
-        # A file that contains the links to all clanModule docs
+          {
-        export CLAN_MODULES=${clanModulesFileInfo}
+            nativeBuildInputs = [
-        export CLAN_MODULES_READMES=${clanModulesReadmes}
+              pkgs.python3
+              self'.packages.clan-cli
+            ];
+          }
+          ''
+            export CLAN_CORE_PATH=${self}
+            export CLAN_CORE_DOCS=${jsonDocs.clanCore}/share/doc/nixos/options.json
+            # A file that contains the links to all clanModule docs
+            export CLAN_MODULES=${clanModulesFileInfo}
 
-        mkdir $out
+            mkdir $out
 
-        # The python script will place mkDocs files in the output directory
+            # The python script will place mkDocs files in the output directory
-        python3 ${renderOptions}
+            python3 ${renderOptions}
-      '';
+          '';
     in
     {
       devShells.docs = pkgs.callPackage ./shell.nix {
-        inherit (self'.packages) docs clan-cli-docs;
+        inherit (self'.packages) docs clan-cli-docs inventory-api-docs;
-        inherit module-docs;
+        inherit
-        inherit asciinema-player-js;
+          asciinema-player-js
-        inherit asciinema-player-css;
+          asciinema-player-css
+          module-docs
+          self'
+          ;
       };
       packages = {
         docs = pkgs.python3.pkgs.callPackage ./default.nix {
-          inherit (self'.packages) clan-cli-docs;
+          inherit (self'.packages) clan-cli-docs inventory-api-docs;
           inherit (inputs) nixpkgs;
           inherit module-docs;
           inherit asciinema-player-js;

docs/nix/get-module-docs.nix

@@ -3,7 +3,6 @@
   pkgs,
   clanCore,
   clanModules,
-  self,
 }:
 let
   allNixosModules = (import "${nixpkgs}/nixos/modules/module-list.nix") ++ [
@@ -31,7 +30,7 @@ let
     options:
     pkgs.nixosOptionsDoc {
       options = options;
-      warningsAreErrors = false;
+      warningsAreErrors = true;
     };
 
   # clanModules docs
@@ -39,15 +38,10 @@ let
     name: module: (evalDocs ((getOptionsWithoutCore [ module ]).clan.${name} or { })).optionsJSON
   ) clanModules;
 
-  clanModulesReadmes = builtins.mapAttrs (
-    module_name: _module: self.lib.modules.getReadme module_name
-  ) clanModules;
-
   # clanCore docs
   clanCoreDocs = (evalDocs (getOptions [ ]).clan.core).optionsJSON;
 in
 {
-  inherit clanModulesReadmes;
   clanCore = clanCoreDocs;
   clanModules = clanModulesDocs;
 }

docs/nix/scripts/renderOptions.py

@@ -28,10 +28,12 @@ import os
 from pathlib import Path
 from typing import Any
 
+from clan_cli.api.modules import Frontmatter, extract_frontmatter, get_roles
+
 # Get environment variables
-CLAN_CORE = os.getenv("CLAN_CORE")
+CLAN_CORE_PATH = os.getenv("CLAN_CORE_PATH")
+CLAN_CORE_DOCS = os.getenv("CLAN_CORE_DOCS")
 CLAN_MODULES = os.environ.get("CLAN_MODULES")
-CLAN_MODULES_READMES = os.environ.get("CLAN_MODULES_READMES")
 
 OUT = os.environ.get("out")
 
@@ -76,7 +78,9 @@ def render_option(name: str, option: dict[str, Any], level: int = 3) -> str:
 
     res = f"""
 {"#" * level} {sanitize(name)}
-{"Readonly" if read_only else ""}
+
+{"**Readonly**" if read_only else ""}
+
 {option.get("description", "No description available.")}
 
 **Type**: `{option["type"]}`
@@ -109,18 +113,19 @@ def render_option(name: str, option: dict[str, Any], level: int = 3) -> str:
 """
 
     decls = option.get("declarations", [])
-    source_path, name = replace_store_path(decls[0])
+    if decls:
-    print(source_path, name)
+        source_path, name = replace_store_path(decls[0])
-    res += f"""
+        print(source_path, name)
+        res += f"""
 :simple-git: [{name}]({source_path})
 """
-    res += "\n"
+        res += "\n"
 
     return res
 
 
 def module_header(module_name: str) -> str:
-    return f"# {module_name}\n"
+    return f"# {module_name}\n\n"
 
 
 def module_usage(module_name: str) -> str:
@@ -146,9 +151,9 @@ options_head = "\n## Module Options\n"
 
 
 def produce_clan_core_docs() -> None:
-    if not CLAN_CORE:
+    if not CLAN_CORE_DOCS:
         raise ValueError(
-            f"Environment variables are not set correctly: $CLAN_CORE={CLAN_CORE}"
+            f"Environment variables are not set correctly: $CLAN_CORE_DOCS={CLAN_CORE_DOCS}"
         )
 
     if not OUT:
@@ -156,7 +161,7 @@ def produce_clan_core_docs() -> None:
 
     # A mapping of output file to content
     core_outputs: dict[str, str] = {}
-    with open(CLAN_CORE) as f:
+    with open(CLAN_CORE_DOCS) as f:
         options: dict[str, dict[str, Any]] = json.load(f)
         module_name = "clan-core"
         for option_name, info in options.items():
@@ -188,14 +193,47 @@ def produce_clan_core_docs() -> None:
                 of.write(output)
 
 
+def render_roles(roles: list[str] | None, module_name: str) -> str:
+    if roles:
+        roles_list = "\n".join([f"    - `{r}`" for r in roles])
+        return f"""
+???+ tip "Inventory usage"
+
+    Predefined roles:
+
+{roles_list}
+
+    Usage:
+
+    ```{{.nix hl_lines="4"}}
+    buildClan {{
+      inventory.services = {{
+        {module_name}.instance_1 = {{
+            roles.{roles[0]}.machines = [ "sara_machine" ];
+            # ...
+        }};
+      }};
+    }}
+    ```
+
+"""
+    return ""
+
+
+clan_modules_descr = """Clan modules are [NixOS modules](https://wiki.nixos.org/wiki/NixOS_modules) which have been enhanced with additional features provided by Clan, with certain option types restricted to enable configuration through a graphical interface.
+
+"""
+
+
 def produce_clan_modules_docs() -> None:
     if not CLAN_MODULES:
         raise ValueError(
             f"Environment variables are not set correctly: $CLAN_MODULES={CLAN_MODULES}"
         )
-    if not CLAN_MODULES_READMES:
+
+    if not CLAN_CORE_PATH:
         raise ValueError(
-            f"Environment variables are not set correctly: $CLAN_MODULES_READMES={CLAN_MODULES_READMES}"
+            f"Environment variables are not set correctly: $CLAN_CORE_PATH={CLAN_CORE_PATH}"
         )
 
     if not OUT:
@@ -204,18 +242,44 @@ def produce_clan_modules_docs() -> None:
     with open(CLAN_MODULES) as f:
         links: dict[str, str] = json.load(f)
 
-    with open(CLAN_MODULES_READMES) as readme:
+    # with open(CLAN_MODULES_READMES) as readme:
-        readme_map: dict[str, str] = json.load(readme)
+    #     readme_map: dict[str, str] = json.load(readme)
+
+    # with open(CLAN_MODULES_META) as f:
+    #     meta_map: dict[str, Any] = json.load(f)
+    #     print(meta_map)
 
     # {'borgbackup': '/nix/store/hi17dwgy7963ddd4ijh81fv0c9sbh8sw-options.json', ... }
+
+    modules_index = "# Modules Overview\n\n"
+    modules_index += clan_modules_descr
+    modules_index += "## Overview\n\n"
+    modules_index += '<div class="grid cards" markdown>\n\n'
+
     for module_name, options_file in links.items():
+        readme_file = Path(CLAN_CORE_PATH) / "clanModules" / module_name / "README.md"
+        print(module_name, readme_file)
+        with open(readme_file) as f:
+            readme = f.read()
+            frontmatter: Frontmatter
+            frontmatter, readme_content = extract_frontmatter(readme, str(readme_file))
+            print(frontmatter, readme_content)
+
+        modules_index += build_option_card(module_name, frontmatter)
+
         with open(Path(options_file) / "share/doc/nixos/options.json") as f:
             options: dict[str, dict[str, Any]] = json.load(f)
             print(f"Rendering options for {module_name}...")
             output = module_header(module_name)
 
-            if readme_map.get(module_name, None):
+            if frontmatter.description:
-                output += f"{readme_map[module_name]}\n"
+                output += f"**{frontmatter.description}**\n\n"
+            output += f"{readme_content}\n"
+
+            # get_roles(str) -> list[str] | None
+            roles = get_roles(str(Path(CLAN_CORE_PATH) / "clanModules" / module_name))
+            if roles:
+                output += render_roles(roles, module_name)
 
             output += module_usage(module_name)
 
@@ -231,6 +295,39 @@ def produce_clan_modules_docs() -> None:
             with open(outfile, "w") as of:
                 of.write(output)
 
+    modules_index += "</div>"
+    modules_index += "\n"
+    modules_outfile = Path(OUT) / "clanModules/index.md"
+
+    with open(modules_outfile, "w") as of:
+        of.write(modules_index)
+
+
+def build_option_card(module_name: str, frontmatter: Frontmatter) -> str:
+    """
+    Build the overview index card for each reference target option.
+    """
+
+    def indent_all(text: str, indent_size: int = 4) -> str:
+        """
+        Indent all lines in a string.
+        """
+        indent = " " * indent_size
+        lines = text.split("\n")
+        indented_text = indent + ("\n" + indent).join(lines)
+        return indented_text
+
+    def to_md_li(module_name: str, frontmatter: Frontmatter) -> str:
+        md_li = (
+            f"""-   **[{module_name}](./{"-".join(module_name.split(" "))}.md)**\n\n"""
+        )
+        md_li += f"""{indent_all("---", 4)}\n\n"""
+        fmd = f"\n{frontmatter.description.strip()}" if frontmatter.description else ""
+        md_li += f"""{indent_all(fmd, 4)}"""
+        return md_li
+
+    return f"{to_md_li(module_name, frontmatter)}\n\n"
+
 
 if __name__ == "__main__":
     produce_clan_core_docs()

docs/nix/shell.nix

@@ -3,18 +3,25 @@
   pkgs,
   module-docs,
   clan-cli-docs,
+  inventory-api-docs,
   asciinema-player-js,
   asciinema-player-css,
   roboto,
   fira-code,
+  self',
   ...
 }:
 pkgs.mkShell {
-  inputsFrom = [ docs ];
+  inputsFrom = [
+    docs
+    self'.devShells.default
+  ];
   shellHook = ''
     mkdir -p ./site/reference/cli
     cp -af ${module-docs}/* ./site/reference/
     cp -af ${clan-cli-docs}/* ./site/reference/cli/
+    cp -af ${inventory-api-docs} ./site/reference/nix-api/inventory.md
+
     chmod +w ./site/reference/*
 
     echo "Generated API documentation in './site/reference/' "

docs/site/blog/posts/backups.md

@@ -0,0 +1,132 @@
+---
+title: "Dev Report: Declarative Backups and Restore"
+description: "An extension to the NixOS module system to declaratively describe how application state is backed up and restored."
+authors:
+  - Mic92
+date: 2024-06-24
+slug: backups
+---
+
+Our goal with [Clan](https://clan.lol/) is to give users control over their data.
+However, with great power comes great responsibility, and owning your data means you also need to take care of backups yourself.
+
+In our experience, setting up automatic backups is often a tedious process as it requires custom integration of the backup software and
+the services that produce the state. More important than the backup is the restore.
+Restores are often not well tested or documented, and if not working correctly, they can render the backup useless.
+
+In Clan, we want to make backup and restore a first-class citizen.
+Every service should describe what state it produces and how it can be backed up and restored.
+
+In this article, we will discuss how our backup interface in Clan works.
+The interface allows different backup software to be used interchangeably and
+allows module authors to define custom backup and restore logic for their services.
+
+
+## First Comes the State
+
+Our services are built from Clan modules. Clan modules are essentially [NixOS modules](https://wiki.nixos.org/wiki/NixOS_modules), the basic configuration components of NixOS.
+However, we have enhanced them with additional features provided by Clan and restricted certain option types to enable configuration through a [graphical interface](https://docs.clan.lol/blog/2024/05/25/jsonschema-converter/).
+
+In a simple case, this can be just a bunch of directories, such as what we define for our [ZeroTier](https://www.zerotier.com/) VPN service.
+
+```nix
+{
+  clan.core.state.zerotier.folders =  [ "/var/lib/zerotier-one" ];
+}
+```
+
+For other systems, we need more complex backup and restore logic.
+For each state, we can provide custom command hooks for backing up and restoring.
+
+In our PostgreSQL module, for example, we define `preBackupCommand` and `postRestoreCommand` to use `pg_dump` and `pg_restore` to backup and restore individual databases:
+
+```nix
+preBackupCommand = ''
+  # ...
+  runuser -u postgres -- pg_dump ${compression} --dbname=${db.name} -Fc -c > "${current}.tmp"
+  # ...
+'';
+postRestoreCommand = ''
+  # ...
+  runuser -u postgres -- dropdb "${db.name}"
+  runuser -u postgres -- pg_restore -C -d postgres "${current}"
+  # ...
+'';
+```
+
+## Then the Backup
+
+Our CLI unifies the different backup providers in one [interface](https://docs.clan.lol/reference/cli/backups/).
+
+As of now, we support backups using [BorgBackup](https://www.borgbackup.org/) and
+a backup module called "localbackup" based on [rsnapshot](https://rsnapshot.org/), optimized for backup on locally attached storage media.
+
+To use different backup software, a module needs to set the options provided by our backup interface.
+The following Nix code is a toy example that uses the `tar` program to perform backup and restore to illustrate how the backup interface works:
+
+```nix
+  clan.core.backups.providers.tar = {
+    list = ''
+      echo /var/lib/system-back.tar
+    '';
+    create = let
+      uniqueFolders = lib.unique (
+        lib.flatten (lib.mapAttrsToList (_name: state: state.folders) config.clan.core.state)
+      );
+    in ''
+      # FIXME: a proper implementation should also run `state.preBackupCommand` of each state
+      if [ -f /var/lib/system-back.tar ]; then
+        tar -uvpf /var/lib/system-back.tar ${builtins.toString uniqueFolders}
+      else
+        tar -cvpf /var/lib/system-back.tar ${builtins.toString uniqueFolders}
+      fi
+    '';
+    restore = ''
+      IFS=':' read -ra FOLDER <<< "''$FOLDERS"
+      echo "${FOLDER[@]}" > /run/folders-to-restore.txt
+      tar -xvpf /var/lib/system-back.tar -C / -T /run/folders-to-restore.txt
+    '';
+  };
+```
+
+For better real-world implementations, check out the implementations for [BorgBackup](https://git.clan.lol/clan/clan-core/src/branch/main/clanModules/borgbackup/default.nix)
+and [localbackup](https://git.clan.lol/clan/clan-core/src/branch/main/clanModules/localbackup/default.nix).
+
+## What It Looks Like to the End User
+
+After following the guide for configuring a [backup](https://docs.clan.lol/getting-started/backups/),
+users can use the CLI to create backups, list them, and restore them.
+
+Backups can be created through the CLI like this:
+
+```
+clan backups create web01
+```
+
+BorgBackup will also create backups itself every day by default.
+
+Completed backups can be listed like this:
+
+```
+clan backups list web01
+...
+web01::u366395@u366395.your-storagebox.de:/./borgbackup::web01-web01-2024-06-18T01:00:00
+web03::u366395@u366395.your-storagebox.de:/./borgbackup::web01-web01-2024-06-19T01:00:00
+```
+One cool feature of our backup system is that it is aware of individual services/applications.
+Let's say we want to restore the state of our [Matrix](https://matrix.org/) chat server; we can just specify it like this:
+
+```
+clan backups restore --service matrix-synapse web01 borgbackup web03::u366395@u366395.your-storagebox.de:/./borgbackup::web01-web01-2024-06-19T01:00:00
+```
+
+In this case, it will first stop the matrix-synapse systemd service, then delete the [PostgreSQL](https://www.postgresql.org/) database, restore the database from the backup, and then start the matrix-synapse service again.
+
+## Future work
+
+As of now we implemented our backup and restore for a handful of services and we expect to refine the interface as we test the interface for more applications.
+
+Currently, our backup implementation backs up filesystem state from running services.
+This can lead to inconsistencies if applications change the state while the backup is running.
+In the future, we hope to make backups more atomic by backing up a filesystem snapshot instead of normal directories.
+This, however, requires the use of modern filesystems that support these features.

docs/site/getting-started/configure.md

@@ -1,17 +1,43 @@
 # Configuration - How to configure clan with your own machines
 
+Managing machine configurations can be done in the following ways:
+
+- writing `nix` expressions in a `flake.nix` file,
+- placing `autoincluded` files into your machine directory,
+- configuring everything in a simple UI (upcoming).
+
+Clan currently offers the following methods to configure machines:
+
+!!! Success "Recommended for nix people"
+
+    - flake.nix (i.e. via `buildClan`)
+        - `machine` argument
+        - `inventory` argument
+
+    - machines/`machine_name`/configuration.nix (`autoincluded` if it exists)
+
+???+ Note "Used by CLI & UI"
+
+    - inventory.json
+    - machines/`machine_name`/hardware-configuration.nix (`autoincluded` if it exists)
+
+
+!!! Warning "Deprecated"
+
+    machines/`machine_name`/settings.json
+
 ## Global configuration
 
 In the `flake.nix` file:
 
-- [x] set a unique `clanName`.
+- [x] set a unique `name`.
 
 === "**buildClan**"
 
     ```nix title="clan-core.lib.buildClan"
     buildClan {
         # Set a unique name
-        clanName = "Lobsters";
+        meta.name = "Lobsters";
         # Should usually point to the directory of flake.nix
         directory = ./.;
 
@@ -31,7 +57,7 @@ In the `flake.nix` file:
     ```nix title="clan-core.flakeModules.default"
     clan = {
         # Set a unique name
-        clanName = "Lobsters";
+        meta.name = "Lobsters";
 
         machines = {
             jon = {
@@ -89,7 +115,7 @@ Adding or configuring a new machine requires two simple steps:
 
               # Change this to the correct ip-address or hostname
               # The hostname is the machine name by default
-              clan.networking.targetHost = pkgs.lib.mkDefault "root@jon"
+              clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon"
 
               # Change this to the ID-LINK of the desired disk shown by 'lsblk'
               disko.devices.disk.main = {
@@ -122,7 +148,7 @@ Adding or configuring a new machine requires two simple steps:
 
               # Change this to the correct ip-address or hostname
               # The hostname is the machine name by default
-              clan.networking.targetHost = pkgs.lib.mkDefault "root@jon"
+              clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon"
 
               # Change this to the ID-LINK of the desired disk shown by 'lsblk'
               disko.devices.disk.main = {

docs/site/getting-started/deploy.md

@@ -160,7 +160,7 @@ buildClan {
             # Set this for clan commands use ssh i.e. `clan machines update`
             # If you change the hostname, you need to update this line to root@<new-hostname>
             # This only works however if you have avahi running on your admin machine else use IP
-            clan.networking.targetHost = pkgs.lib.mkDefault "root@jon";
+            clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon";
         };
     };
 };
@@ -197,7 +197,7 @@ buildClan {
     # ...
     machines = {
         "jon" = {
-            clan.networking.buildHost = "root@<host_or_ip>";
+            clan.core.networking.buildHost = "root@<host_or_ip>";
         };
     };
 };

docs/site/getting-started/flake-parts.md

@@ -63,7 +63,7 @@ Below is a guide on how to structure this in your flake.nix:
       # Define your clan
       clan = {
         # Clan wide settings. (Required)
-        clanName = ""; # Ensure to choose a unique name.
+        meta.name = ""; # Ensure to choose a unique name.
 
         machines = {
           jon = {
@@ -75,7 +75,7 @@ Below is a guide on how to structure this in your flake.nix:
             nixpkgs.hostPlatform = "x86_64-linux";
 
             # Set this for clan commands use ssh i.e. `clan machines update`
-            clan.networking.targetHost = pkgs.lib.mkDefault "root@jon";
+            clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon";
 
             # remote> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
             disko.devices.disk.main = {
@@ -83,7 +83,7 @@ Below is a guide on how to structure this in your flake.nix:
             };
 
             # There needs to be exactly one controller per clan
-            clan.networking.zerotier.controller.enable = true;
+            clan.core.networking.zerotier.controller.enable = true;
 
           };
         };

docs/site/getting-started/installer.md

@@ -48,13 +48,18 @@ sudo umount /dev/sdb1
     ```bash
     clan flash --flake git+https://git.clan.lol/clan/clan-core \
       --ssh-pubkey $HOME/.ssh/id_ed25519.pub \
-      --keymap en \
+      --keymap us \
-      --language en \
+      --language en_US.utf-8 \
       --disk main /dev/sd<X> \
       flash-installer
     ```
 
     The `--ssh-pubkey`, `--language` and `--keymap` are optional.
+    You can get a list of all keymaps with the following command:
+
+    ```
+    $ find $(nix-build 'https://github.com/NixOS/nixpkgs/archive/refs/heads/nixpkgs-unstable.tar.gz' --no-out-link -A kbd)/share/keymaps -type f -name '*.map.gz'
+    ```
     Replace `$HOME/.ssh/id_ed25519.pub` with a path to your SSH public key.
     If you do not have an ssh key yet, you can generate one with `ssh-keygen -t ed25519` command.
 

docs/site/getting-started/mesh-vpn.md

@@ -29,7 +29,7 @@ peers. Once addresses are allocated, the controller's continuous operation is no
 2. **Add Configuration**: Input the following configuration to the NixOS
    configuration of the controller machine:
    ```nix
-   clan.networking.zerotier.controller = {
+   clan.core.networking.zerotier.controller = {
      enable = true;
      public = true;
    };
@@ -48,7 +48,7 @@ To introduce a new machine to the VPN, adhere to the following steps:
    configuration, substituting `<CONTROLLER>` with the controller machine name:
    ```nix
    { config, ... }: {
-     clan.networking.zerotier.networkId = builtins.readFile (config.clan.core.clanDir + "/machines/<CONTROLLER>/facts/zerotier-network-id");
+     clan.core.networking.zerotier.networkId = builtins.readFile (config.clan.core.clanDir + "/machines/<CONTROLLER>/facts/zerotier-network-id");
    }
    ```
 1. **Update the New Machine**: Execute:

docs/site/guides/index.md

@@ -0,0 +1,5 @@
+# Guides
+
+Detailed guides into the following subtopics:
+
+- [Inventory](./inventory.md): Configuring Services across machine boundaries

docs/site/guides/inventory.md

@@ -0,0 +1,196 @@
+# Inventory
+
+`Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries.
+
+See [Inventory API Documentation](../reference/nix-api/inventory.md)
+
+This guide will walk you through setting up a backup-service, where the inventory becomes useful.
+
+## Prerequisites Meta (optional)
+
+Metadata about the clan, will be displayed upfront in the upcomming clan-app, make sure to choose a unique name.
+
+Make sure to set `name` either via `inventory.meta` OR via `clan.meta`.
+
+```{.nix hl_lines="3-8"}
+buildClan {
+    inventory = {
+        meta = {
+            name = "Superclan"
+            description = "Awesome backups and family stuff"
+        };
+    };
+}
+```
+
+## How to add machines
+
+Machines can be added via `inventory.machines` OR via `buildClan` directly.
+
+!!! Note
+    It doesn't matter where the machine gets introduced to buildClan - All delarations are valid, duplications are merged.
+
+    However the clan-app (UI) will create machines in the inventory, because it cannot create arbitrary nix code or nixos configs.
+
+In the following example `backup_server` is one machine - it may specify parts of its configuration in different places.
+
+```{.nix hl_lines="3-5 12-20"}
+buildClan {
+    machines = {
+        "backup_server" = {
+            # Any valid nixos config
+        };
+        "jon" = {
+            # Any valid nixos config
+        };
+    };
+    inventory = {
+        machines = {
+            "backup_server" = {
+                # Don't include any nixos config here
+                # The following fields are avilable
+                # description: null | string
+                # icon:        null | string
+                # name:        string
+                # system:      null | string
+                # tags:        [...string]
+            };
+            "jon" = {
+                # Same as above
+            };
+        };
+    };
+}
+```
+
+## Services
+
+### Available clanModules
+
+Currently the inventory interface is implemented by the following clanModules
+
+- [borgbackup](../reference/clanModules/borgbackup.md)
+- [packages](../reference/clanModules/packages.md)
+- [single-disk](../reference/clanModules/single-disk.md)
+
+See the respective module documentation for available roles.
+
+### Adding services to machines
+
+A module can be added to one or multiple machines via `Roles`. clan's `Role` interface provide sane defaults for a module this allows the module author to reduce the configuration overhead to a minimum.
+
+Each service can still be customized and configured according to the modules options.
+
+- Per instance configuration via `services.<serviceName>.<instanceName>.config`
+- Per role configuration via `services.<serviceName>.<instanceName>.roles.<roleName>.config`
+- Per machine configuration via `services.<serviceName>.<instanceName>.machines.<machineName>.config`
+
+### Setting up the Backup Service
+
+!!! Example "Borgbackup Example"
+
+    To configure a service it needs to be added to the machine.
+    It is required to assign the service (`borgbackup`) an arbitrary instance name. (`instance_1`)
+
+    See also: [Multiple Service Instances](#multiple-service-instances)
+
+    ```{.nix hl_lines="14-17"}
+    buildClan {
+        inventory = {
+            machines = {
+                "backup_server" = {
+                    # Don't include any nixos config here
+                    # See inventory.Machines for available options
+                };
+                "jon" = {
+                    # Don't include any nixos config here
+                    # See inventory.Machines for available options
+                };
+            };
+            services = {
+                borgbackup.instance_1 = {
+                    roles.client.machines = [ "jon" ];
+                    roles.server.machines = [ "backup_server" ];
+                };
+            };
+        };
+    }
+    ```
+
+### Scalabling the Backup
+
+The inventory allows machines to set **Tags**
+
+It is possible to add services to multiple machines via tags. The service instance gets added in the specified role. In this case `role = "client"`
+
+!!! Example "Tags Example"
+
+    ```{.nix hl_lines="9 12 17"}
+    buildClan {
+        inventory = {
+            machines = {
+                "backup_server" = {
+                    # Don't include any nixos config here
+                    # See inventory.Machines for available options
+                };
+                "jon" = {
+                    tags = [ "backup" ];
+                };
+                "sara" = {
+                    tags = [ "backup" ];
+                };
+            };
+            services = {
+                borgbackup.instance_1 = {
+                    roles.client.tags = [ "backup" ];
+                    roles.server.machines = [ "backup_server" ];
+                };
+            };
+        };
+    }
+    ```
+
+### Multiple Service Instances
+
+!!! danger "Important"
+    Not all modules implement support for multiple instances yet.
+    Multiple instance usage could create complexity, refer to each modules documentation, for intended usage.
+
+!!! Example
+
+    In this example `backup_server` has role `client` and `server` in different instances.
+
+    ```{.nix hl_lines="11 14"}
+    buildClan {
+        inventory = {
+            machines = {
+                "jon" = {};
+                "backup_server" = {};
+                "backup_backup_server" = {}
+            };
+            services = {
+                borgbackup.instance_1 = {
+                    roles.client.machines = [ "jon" ];
+                    roles.server.machines = [ "backup_server" ];
+                };
+                borgbackup.instance_1 = {
+                    roles.client.machines = [ "backup_server" ];
+                    roles.server.machines = [ "backup_backup_server" ];
+                };
+            };
+        };
+    }
+    ```
+
+### API specification
+
+**The complete schema specification is available [here](../reference/nix-api/inventory.md)**
+
+Or it can build anytime via:
+
+```sh
+nix build git+https://git.clan.lol/clan/clan-core#inventory-schema
+> result
+> ├── schema.cue
+> └── schema.json
+```

docs/site/reference/index.md

@@ -0,0 +1,8 @@
+# Documentation
+
+This section of the site contains information about the following topics:
+
+- How to use the [Clan CLI](./cli/index.md)
+- Available services and application [modules](./clanModules/index.md)
+- [Configuration options](./clan-core/index.md) controlling the essential features
+- Descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan

docs/site/reference/nix-api/buildclan.md

@@ -0,0 +1,29 @@
+# buildClan
+
+The core [function](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/default.nix) that produces a Clan. It returns a set of consistent configurations for all machines with ready-to-use secrets, backups and other services.
+
+## Inputs
+
+`directory`
+: The directory containing the machines subdirectory
+
+`machines`
+: Allows to include machine-specific modules i.e. machines.${name} = { ... }
+
+`meta`
+: An optional set
+
+: `{ name :: string, icon :: string, description :: string }`
+
+`inventory`
+: Service set for easily configuring distributed services, such as backups
+
+: For more details see [Inventory](./inventory.md)
+
+`specialArgs`
+: Extra arguments to pass to nixosSystem i.e. useful to make self available
+
+`pkgsForSystem`
+: A function that maps from architecture to pkgs, if specified this nixpkgs will be only imported once for each system.
+  This improves performance, but all nipxkgs.* options will be ignored.
+  `(string -> pkgs )`

docs/site/reference/nix-api/index.md

@@ -0,0 +1,6 @@
+# Nix API Overview
+
+There are two top-level components of the Nix API, which together allow for the declarative definition of a Clan:
+
+- the [Inventory](./inventory.md), a structure representing the machines, services, custom configurations, and other data that constitute a Clan, and
+- the [`buildClan`](./buildclan.md) function, which constructs a Clan from an Inventory definition.

flake.lock

@@ -7,11 +7,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1718846788,
+        "lastModified": 1720661479,
-        "narHash": "sha256-9dtXYtEkmXoUJV+PGLqscqF7qTn4AIhAKpFWRFU2NYs=",
+        "narHash": "sha256-nsGgA14vVn0GGiqEfomtVgviRJCuSR3UEopfP8ixW1I=",
         "owner": "nix-community",
         "repo": "disko",
-        "rev": "e1174d991944a01eaaa04bc59c6281edca4c0e6e",
+        "rev": "786965e1b1ed3fd2018d78399984f461e2a44689",
         "type": "github"
       },
       "original": {
@@ -27,11 +27,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1717285511,
+        "lastModified": 1719994518,
-        "narHash": "sha256-iKzJcpdXih14qYVcZ9QC9XuZYnPc6T8YImb6dX166kw=",
+        "narHash": "sha256-pQMhCCHyQGRzdfAkdJ4cIWiw+JNuWsTX7f0ZYSyz0VY=",
         "owner": "hercules-ci",
         "repo": "flake-parts",
-        "rev": "2a55567fcf15b1b1c7ed712a2c6fadaec7412ea8",
+        "rev": "9227223f6d922fee3c7b190b2cc238a99527bbb7",
         "type": "github"
       },
       "original": {
@@ -40,42 +40,6 @@
         "type": "github"
       }
     },
-    "nixlib": {
-      "locked": {
-        "lastModified": 1712450863,
-        "narHash": "sha256-K6IkdtMtq9xktmYPj0uaYc8NsIqHuaAoRBaMgu9Fvrw=",
-        "owner": "nix-community",
-        "repo": "nixpkgs.lib",
-        "rev": "3c62b6a12571c9a7f65ab037173ee153d539905f",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nix-community",
-        "repo": "nixpkgs.lib",
-        "type": "github"
-      }
-    },
-    "nixos-generators": {
-      "inputs": {
-        "nixlib": "nixlib",
-        "nixpkgs": [
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1718025593,
-        "narHash": "sha256-WZ1gdKq/9u1Ns/oXuNsDm+W0salonVA0VY1amw8urJ4=",
-        "owner": "nix-community",
-        "repo": "nixos-generators",
-        "rev": "35c20ba421dfa5059e20e0ef2343c875372bdcf3",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nix-community",
-        "repo": "nixos-generators",
-        "type": "github"
-      }
-    },
     "nixos-images": {
       "inputs": {
         "nixos-stable": [],
@@ -84,11 +48,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1718845599,
+        "lastModified": 1720659757,
-        "narHash": "sha256-HbQ0iKohKJC5grC95HNjLxGPdgsc/BJgoENDYNbzkLo=",
+        "narHash": "sha256-ltzUuCsEfPA9CYM9BAnwObBGqDyQIs2OLkbVMeOOk00=",
         "owner": "nix-community",
         "repo": "nixos-images",
-        "rev": "c1e6a5f7b08f1c9993de1cfc5f15f838bf783b88",
+        "rev": "5eddae0afbcfd4283af5d6676d08ad059ca04b70",
         "type": "github"
       },
       "original": {
@@ -99,11 +63,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1719146883,
+        "lastModified": 1720977633,
-        "narHash": "sha256-DAyIfQgyqalov0DcEKRvDOUin7axELasaP6NCPt7UQA=",
+        "narHash": "sha256-if0qaFmAe8X01NsVRK5e9Asg9mEWVkHrA9WuqM5jB70=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "084f8df2f3ff80cdec6f515931036f63c5d2f36c",
+        "rev": "0af9d835c27984b3265145f8e3cbc6c153479196",
         "type": "github"
       },
       "original": {
@@ -117,7 +81,6 @@
       "inputs": {
         "disko": "disko",
         "flake-parts": "flake-parts",
-        "nixos-generators": "nixos-generators",
         "nixos-images": "nixos-images",
         "nixpkgs": "nixpkgs",
         "sops-nix": "sops-nix",
@@ -132,11 +95,11 @@
         "nixpkgs-stable": []
       },
       "locked": {
-        "lastModified": 1719111739,
+        "lastModified": 1720926522,
-        "narHash": "sha256-kr2QzRrplzlCP87ddayCZQS+dhGW98kw2zy7+jUXtF4=",
+        "narHash": "sha256-eTpnrT6yu1vp8C0B5fxHXhgKxHoYMoYTEikQx///jxY=",
         "owner": "Mic92",
         "repo": "sops-nix",
-        "rev": "5e2e9421e9ed2b918be0a441c4535cfa45e04811",
+        "rev": "0703ba03fd9c1665f8ab68cc3487302475164617",
         "type": "github"
       },
       "original": {
@@ -152,11 +115,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1718522839,
+        "lastModified": 1720930114,
-        "narHash": "sha256-ULzoKzEaBOiLRtjeY3YoGFJMwWSKRYOic6VNw2UyTls=",
+        "narHash": "sha256-VZK73b5hG5bSeAn97TTcnPjXUXtV7j/AtS4KN8ggCS0=",
         "owner": "numtide",
         "repo": "treefmt-nix",
-        "rev": "68eb1dc333ce82d0ab0c0357363ea17c31ea1f81",
+        "rev": "b92afa1501ac73f1d745526adc4f89b527595f14",
         "type": "github"
       },
       "original": {

flake.nix

@@ -13,8 +13,6 @@
     sops-nix.url = "github:Mic92/sops-nix";
     sops-nix.inputs.nixpkgs.follows = "nixpkgs";
     sops-nix.inputs.nixpkgs-stable.follows = "";
-    nixos-generators.url = "github:nix-community/nixos-generators";
-    nixos-generators.inputs.nixpkgs.follows = "nixpkgs";
     nixos-images.url = "github:nix-community/nixos-images";
     nixos-images.inputs.nixos-unstable.follows = "nixpkgs";
     # unused input
@@ -31,7 +29,7 @@
       { ... }:
       {
         clan = {
-          # meta.name = "clan-core";
+          meta.name = "clan-core";
           directory = self;
         };
         systems = [
@@ -51,10 +49,9 @@
           ./formatter.nix
           ./lib/flake-module.nix
           ./nixosModules/flake-module.nix
+          ./nixosModules/clanCore/vars/flake-module.nix
           ./pkgs/flake-module.nix
           ./templates/flake-module.nix
-
-          ./inventory/flake-module.nix
         ];
       }
     );

flakeModules/clan.nix

@@ -13,7 +13,6 @@ let
     inherit lib clan-core;
     inherit (inputs) nixpkgs;
   };
-
   cfg = config.clan;
 in
 {
@@ -60,6 +59,15 @@ in
       default = { };
       description = "Allows to include machine-specific modules i.e. machines.\${name} = { ... }";
     };
+    inventory = mkOption {
+      #type = types.submodule { imports = [ ../lib/inventory/build-inventory/interface.nix ]; };
+      type = types.attrsOf types.raw;
+      default = { };
+      description = ''
+        An abstract service layer for consistently configuring distributed services across machine boundaries.
+        See https://docs.clan.lol/concepts/inventory/ for more details.
+      '';
+    };
 
     # Checks are performed in 'buildClan'
     # Not everyone uses flake-parts
@@ -91,6 +99,11 @@ in
     clanInternals = lib.mkOption {
       type = lib.types.submodule {
         options = {
+          inventory = lib.mkOption { type = lib.types.attrsOf lib.types.unspecified; };
+          inventoryFile = lib.mkOption { type = lib.types.unspecified; };
+
+          clanModules = lib.mkOption { type = lib.types.attrsOf lib.types.path; };
+          source = lib.mkOption { type = lib.types.path; };
           meta = lib.mkOption { type = lib.types.attrsOf lib.types.unspecified; };
           all-machines-json = lib.mkOption { type = lib.types.attrsOf lib.types.unspecified; };
           machines = lib.mkOption { type = lib.types.attrsOf (lib.types.attrsOf lib.types.unspecified); };
@@ -107,6 +120,7 @@ in
         machines
         pkgsForSystem
         meta
+        inventory
         ;
     };
   };

formatter.nix

@@ -1,49 +1,93 @@
-{ lib, inputs, ... }:
+{ inputs, ... }:
 {
   imports = [ inputs.treefmt-nix.flakeModule ];
   perSystem =
     { self', pkgs, ... }:
     {
-      treefmt.projectRootFile = "flake.nix";
+      treefmt.projectRootFile = ".git/config";
       treefmt.programs.shellcheck.enable = true;
 
       treefmt.programs.mypy.enable = true;
-      treefmt.programs.mypy.directories = {
+      treefmt.programs.nixfmt.enable = true;
-        "pkgs/clan-cli".extraPythonPackages = self'.packages.clan-cli.testDependencies;
+      treefmt.programs.nixfmt.package = pkgs.nixfmt-rfc-style;
-        "pkgs/clan-app".extraPythonPackages =
+      treefmt.programs.deadnix.enable = true;
-          # clan-app currently only exists on linux
-          (self'.packages.clan-app.externalTestDeps or [ ]) ++ self'.packages.clan-cli.testDependencies;
-      };
 
-      treefmt.settings.formatter.nix = {
+      treefmt.programs.mypy.directories =
-        command = "sh";
+        {
-        options = [
+          "pkgs/clan-cli" = {
-          "-eucx"
+            extraPythonPackages = self'.packages.clan-cli.testDependencies;
-          ''
+            modules = [ "clan_cli" ];
-            # First deadnix
+          };
-            ${lib.getExe pkgs.deadnix} --edit "$@"
+          "pkgs/clan-app" = {
-            # Then nixpkgs-fmt
+            extraPythonPackages =
-            ${lib.getExe pkgs.nixfmt-rfc-style} "$@"
+              # clan-app currently only exists on linux
-          ''
+              (self'.packages.clan-app.externalTestDeps or [ ]) ++ self'.packages.clan-cli.testDependencies;
-          "--" # this argument is ignored by bash
+            modules = [ "clan_app" ];
-        ];
+          };
-        includes = [ "*.nix" ];
+        }
-        excludes = [
+        // (
-          # Was copied from nixpkgs. Keep diff minimal to simplify upstreaming.
+          if pkgs.stdenv.isLinux then
-          "pkgs/builders/script-writers.nix"
+            {
-        ];
+              "pkgs/clan-vm-manager" = {
-      };
+                extraPythonPackages =
-      treefmt.settings.formatter.python = {
+                  # clan-app currently only exists on linux
-        command = "sh";
+                  self'.packages.clan-vm-manager.testDependencies ++ self'.packages.clan-cli.testDependencies;
-        options = [
+                modules = [ "clan_vm_manager" ];
-          "-eucx"
+              };
-          ''
+            }
-            ${lib.getExe pkgs.ruff} check --fix "$@"
+          else
-            ${lib.getExe pkgs.ruff} format "$@"
+            { }
-          ''
+        );
-          "--" # this argument is ignored by bash
+      treefmt.programs.ruff.check = true;
-        ];
+      treefmt.programs.ruff.format = true;
-        includes = [ "*.py" ];
+
-      };
+      # FIXME: currently broken in CI
+      #treefmt.settings.formatter.vale =
+      #  let
+      #    vocab = "cLAN";
+      #    style = "Docs";
+      #    config = pkgs.writeText "vale.ini" ''
+      #      StylesPath = ${styles}
+      #      Vocab = ${vocab}
+
+      #      [*.md]
+      #      BasedOnStyles = Vale, ${style}
+      #      Vale.Terms = No
+      #    '';
+      #    styles = pkgs.symlinkJoin {
+      #      name = "vale-style";
+      #      paths = [
+      #        accept
+      #        headings
+      #      ];
+      #    };
+      #    accept = pkgs.writeTextDir "config/vocabularies/${vocab}/accept.txt" ''
+      #      Nix
+      #      NixOS
+      #      Nixpkgs
+      #      clan.lol
+      #      Clan
+      #      monorepo
+      #    '';
+      #    headings = pkgs.writeTextDir "${style}/headings.yml" ''
+      #      extends: capitalization
+      #      message: "'%s' should be in sentence case"
+      #      level: error
+      #      scope: heading
+      #      # $title, $sentence, $lower, $upper, or a pattern.
+      #      match: $sentence
+      #    '';
+      #  in
+      #  {
+      #    command = "${pkgs.vale}/bin/vale";
+      #    options = [ "--config=${config}" ];
+      #    includes = [ "*.md" ];
+      #    # TODO: too much at once, fix piecemeal
+      #    excludes = [
+      #      "docs/*"
+      #      "clanModules/*"
+      #      "pkgs/*"
+      #    ];
+      #  };
     };
 }

inventory.json

@@ -0,0 +1,99 @@
+{
+  "meta": {
+    "name": "clan-core",
+    "description": null,
+    "icon": null
+  },
+  "machines": {
+    "test-inventory-machine": {
+      "name": "foo",
+      "deploy": {
+        "targetHost": null
+      },
+      "description": "A nice thing",
+      "icon": "./path/to/icon.png",
+      "tags": ["1", "2", "3"],
+      "system": "x86_64-linux"
+    }
+  },
+  "services": {
+    "packages": {
+      "editors": {
+        "meta": {
+          "name": "Some editor packages",
+          "description": null,
+          "icon": null
+        },
+        "roles": {
+          "default": {
+            "imports": [],
+            "machines": ["test-inventory-machine"],
+            "tags": []
+          }
+        },
+        "config": {},
+        "imports": [],
+        "machines": {
+          "test-inventory-machine": {
+            "config": {
+              "packages": ["zed-editor"]
+            },
+            "imports": []
+          }
+        }
+      },
+      "browsing": {
+        "meta": {
+          "name": "Web browsing packages",
+          "description": null,
+          "icon": null
+        },
+        "roles": {
+          "default": {
+            "config": {},
+            "imports": [],
+            "machines": ["test-inventory-machine"],
+            "tags": []
+          }
+        },
+        "config": {},
+        "imports": [],
+        "machines": {
+          "test-inventory-machine": {
+            "config": {
+              "packages": ["chromium"]
+            },
+            "imports": []
+          }
+        }
+      }
+    },
+    "single-disk": {
+      "default": {
+        "meta": {
+          "name": "single-disk",
+          "description": null,
+          "icon": null
+        },
+        "roles": {
+          "default": {
+            "config": {},
+            "imports": [],
+            "machines": ["test-inventory-machine"],
+            "tags": []
+          }
+        },
+        "config": {},
+        "imports": [],
+        "machines": {
+          "test-inventory-machine": {
+            "config": {
+              "device": "/dev/null"
+            },
+            "imports": []
+          }
+        }
+      }
+    }
+  }
+}

inventory/README.md

@@ -1,57 +0,0 @@
-# Inventory
-
-This part provides a specification for the inventory.
-
-It is used for design phase and as validation helper.
-
-> Cue is less verbose and easier to understand and maintain than json-schema.
-> Json-schema, if needed can be easily generated on-the fly.
-
-## Checking validity
-
-Directly check a json against the schema
-
-`cue vet inventory.json root.cue -d '#Root'`
-
-## Json schema
-
-Export the json-schema i.e. for usage in python / javascript / nix
-
-`cue export --out openapi root.cue`
-
-## Usage
-
-Comments are rendered as descriptions in the json schema.
-
-```cue
-// A name of the clan (primarily shown by the UI)
-name: string
-```
-
-Cue open sets. In the following `foo = {...}` means that the key `foo` can contain any arbitrary json object.
-
-```cue
-foo: { ... }
-```
-
-Cue dynamic keys.
-
-```cue
-[string]: {
-    attr: string
-}
-```
-
-This is the schema of
-
-```json
-{
-    "a": {
-        "attr": "foo"
-    },
-    "b": {
-        "attr": "bar"
-    }
-    // ... Indefinitely more dynamic keys of type "string"
-}
-```

inventory/example_flake.nix

@@ -1,137 +0,0 @@
-{
-  description = "<Put your description here>";
-
-  inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-
-  outputs =
-    { clan-core, ... }:
-    let
-      pkgs = clan-core.inputs.nixpkgs.legacyPackages.${system};
-      system = "x86_64-linux";
-    in
-    # Usage see: https://docs.clan.lol
-    #  nice_flake_interface -> buildInventory() -> Inventory -> buildClanFromInventory() -> nixosConfigurations
-    # buildClanFromInventory = inventory: evalModules {
-    #     extraAttrs = { inherit inventory; };
-    #     # (attrNames inventory.machines)
-    # };
-    # clan =
-    #   clan-core.lib.buildClanFromInventory [
-    #     # Inventory 0 (loads the json file managed by the Python API)
-    #     (builtins.fromJSON (builtins.readFile ./inventory.json))
-    #     # ->
-    #     # {
-    #     #   services."backups_1".autoIncludeMachines = true;
-    #     #   services."backups_1".module = "borgbackup";
-    #     #   ... etc.
-    #     # }
-    #   ]
-    #   ++ (buildInventory {
-    #     clanName = "nice_flake_interface";
-    #     description = "A nice flake interface";
-    #     icon = "assets/icon.png";
-    #     machines = {
-    #       jon = {
-    #         # Just regular nixos/clan configuration ?
-    #         # config = {
-    #         #   imports = [
-    #         #     ./modules/shared.nix
-    #         #     ./machines/jon/configuration.nix
-    #         #   ];
-    #         #   nixpkgs.hostPlatform = system;
-    #         #   # Set this for clan commands use ssh i.e. `clan machines update`
-    #         #   # If you change the hostname, you need to update this line to root@<new-hostname>
-    #         #   # This only works however if you have avahi running on your admin machine else use IP
-    #         #   clan.networking.targetHost = pkgs.lib.mkDefault "root@jon";
-    #         #   # ssh root@flash-installer.local lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-    #         #   disko.devices.disk.main = {
-    #         #     device = "/dev/disk/by-id/__CHANGE_ME__";
-    #         #   };
-    #         #   # IMPORTANT! Add your SSH key here
-    #         #   # e.g. > cat ~/.ssh/id_ed25519.pub
-    #         #   users.users.root.openssh.authorizedKeys.keys = throw ''
-    #         #     Don't forget to add your SSH key here!
-    #         #     users.users.root.openssh.authorizedKeys.keys = [ "<YOUR SSH_KEY>" ]
-    #         #   '';
-    #         #   # Zerotier needs one controller to accept new nodes. Once accepted
-    #         #   # the controller can be offline and routing still works.
-    #         #   clan.networking.zerotier.controller.enable = true;
-    #         # };
-    #       };
-    #     };
-    #   })
-    #   ++ [
-    #     # Low level inventory overrides (comes at the end)
-    #     {
-    #       services."backups_2".autoIncludeMachines = true;
-    #       services."backups_2".module = "borgbackup";
-    #     }
-    #   ];
-    # # buildClan :: [ Partial<Inventory> ] -> Inventory
-    # # foldl' (acc: v: lib.recursiveUpdate acc v) {} []
-    # inventory = [
-    #   # import json
-    #   {...}
-    #   # power user flake
-    #   {...}
-    # ]
-    # # With Module system
-    # # Pros: Easy to understand,
-    # # Cons: Verbose, hard to maintain
-    # # buildClan :: { modules = [ { config = Partial<Inventory>; options :: InventoryOptions; } } ]; } -> Inventory
-    # eval = lib.evalModules {
-    #   modules = [
-    #     {
-    #       # Inventory Schema
-    #       # Python validation
-    #       options = {...}
-    #     }
-    #     {
-    #       config = map lib.mkDefault
-    #       (builtins.fromJSON (builtins.readFile ./inventory.json))
-    #     }
-    #     {
-    #       #  User provided
-    #       config = {...}
-    #     }
-    #     # Later overrides.
-    #     {
-    #       lib.mkForce ...
-    #     }
-    #   ];
-    # }
-    # nixosConfigurations = lib.evalModules inventory;
-    # eval.config.inventory
-    # #
-    # eval.config.machines.jon#nixosConfig
-    # eval.config.machines.sara#nixosConfig
-    #
-    # {inventory, config, ...}:{
-    #   hostname = config.machines.sara # Invalid
-    #   hostname = inventory.machines.sara.hostname # Valid
-    # }
-    /*
-      # Type
-
-      buildInventory :: {
-        clanName :: string
-        machines :: {
-          ${name} :: {
-            config :: {
-              # NixOS configuration
-            };
-          };
-        };
-        # ... More mapped inventory options
-        # i.e. shared config for all machines
-      } -> Inventory
-    */
-    {
-      # all machines managed by Clan
-      inherit (clan) nixosConfigurations clanInternals;
-      # add the Clan cli tool to the dev shell
-      devShells.${system}.default = pkgs.mkShell {
-        packages = [ clan-core.packages.${system}.clan-cli ];
-      };
-    };
-}

inventory/flake-module.nix

@@ -1,46 +0,0 @@
-{ ... }:
-{
-  perSystem =
-    { pkgs, config, ... }:
-    {
-      packages.inventory-schema = pkgs.stdenv.mkDerivation {
-        name = "inventory-schema";
-        src = ./src;
-
-        buildInputs = [ pkgs.cue ];
-
-        installPhase = ''
-          mkdir -p $out
-        '';
-      };
-      devShells.inventory-schema = pkgs.mkShell { inputsFrom = [ config.packages.inventory-schema ]; };
-
-      checks.inventory-schema-checks = pkgs.stdenv.mkDerivation {
-        name = "inventory-schema-checks";
-        src = ./src;
-        buildInputs = [ pkgs.cue ];
-        buildPhase = ''
-          echo "Running inventory tests..."
-
-          echo "Export cue as json-schema..."
-          cue export --out openapi root.cue
-
-          echo "Validate test/*.json against inventory-schema..."
-
-          test_dir="test"
-          for file in "$test_dir"/*; do
-            # Check if the item is a file
-            if [ -f "$file" ]; then
-              # Print the filename
-              echo "Running test on: $file"
-
-              # Run the cue vet command
-              cue vet "$file" root.cue -d "#Root"
-            fi
-          done
-
-          touch $out
-        '';
-      };
-    };
-}

inventory/src/cue.mod/module.cue

@@ -1,2 +0,0 @@
-module: "clan.lol/inventory"
-language: version: "v0.8.2"

inventory/src/machines/machines.cue

@@ -1,8 +0,0 @@
-package machines
-
-
-#machine: machines: [string]: {
-    name: string,
-    description?: string,
-    icon?: string
-}

inventory/src/root.cue

@@ -1,24 +0,0 @@
-package inventory
-
-import (
-	"clan.lol/inventory/services"
-	"clan.lol/inventory/machines"
-)
-
-@jsonschema(schema="http://json-schema.org/schema#")
-#Root: {
-	meta: {
-		// A name of the clan (primarily shown by the UI)
-		name: string
-		// A description of the clan
-		description?: string
-		// The icon path
-		icon?: string
-	}
-
-	// A map of services
-	services.#service
-
-	// A map of machines
-	machines.#machine
-}

inventory/src/services/services.cue

@@ -1,32 +0,0 @@
-package services
-
-#ServiceRole: "server" | "client" | "both"
-
-#service: services: [string]: {
-    // Required meta fields
-    meta: {
-        name: string,
-        icon?: string
-        description?: string,
-    },
-    // Required module specifies the behavior of the service.
-    module: string,
-
-    // We moved the machine sepcific config to "machines".
-    // It may be moved back depending on what makes more sense in the future.
-    machineConfig: {
-        [string]: {
-            roles?: [ ...#ServiceRole ],
-            config?: {
-                ...
-            }
-        }
-    },
-
-    // Configuration for the service
-    config: {
-        // Schema depends on the module.
-        // It declares the interface how the service can be configured.
-        ...
-    }
-}

inventory/src/tests/borgbackup.json

@@ -1,38 +0,0 @@
-{
-  "machines": {
-    "camina_machine": {
-      "name": "camina"
-    },
-    "vyr_machine": {
-      "name": "vyr"
-    },
-    "vi_machine": {
-      "name": "vi"
-    }
-  },
-  "meta": {
-    "name": "kenjis clan"
-  },
-  "services": {
-    "backup": {
-      "meta": {
-        "name": "My backup"
-      },
-      "module": "borbackup-static",
-      "machineConfig": {
-        "vyr": {
-          "roles": ["server"]
-        },
-        "vi": {
-          "roles": ["client"]
-        },
-        "camina_machine": {
-          "roles": ["client"]
-        }
-      },
-      "config": {
-        "folders": ["/home", "/root", "/var", "/etc"]
-      }
-    }
-  }
-}

inventory/src/tests/syncthing.json

@@ -1,45 +0,0 @@
-{
-  "machines": {
-    "camina_machine": {
-      "name": "camina"
-    },
-    "vyr": {
-      "name": "vyr"
-    },
-    "vi": {
-      "name": "vi"
-    }
-  },
-  "meta": {
-    "name": "kenjis clan"
-  },
-  "services": {
-    "sync_files": {
-      "meta": {
-        "name": "My sync"
-      },
-      "module": "syncthing-static-peers",
-      "machineConfig": {
-        "vyr": {},
-        "vi": {},
-        "camina_machine": {}
-      },
-      "config": {
-        "folders": {
-          "test": {
-            "path": "~/data/docs",
-            "devices": ["camina", "vyr", "vi"]
-          },
-          "videos": {
-            "path": "~/data/videos",
-            "devices": ["camina", "vyr", "ezra"]
-          },
-          "playlist": {
-            "path": "~/data/playlist",
-            "devices": ["camina", "vyr", "ezra"]
-          }
-        }
-      }
-    }
-  }
-}

inventory/src/tests/zerotier.json

@@ -1,36 +0,0 @@
-{
-  "machines": {
-    "camina_machine": {
-      "name": "camina"
-    },
-    "vyr_machine": {
-      "name": "vyr"
-    },
-    "vi_machine": {
-      "name": "vi"
-    }
-  },
-  "meta": {
-    "name": "kenjis clan"
-  },
-  "services": {
-    "backup": {
-      "meta": {
-        "name": "My backup"
-      },
-      "module": "borbackup-static",
-      "machineConfig": {
-        "vyr_machine": {
-          "roles": ["server"]
-        },
-        "vi_machine": {
-          "roles": ["peer"]
-        },
-        "camina_machine": {
-          "roles": ["peer"]
-        }
-      },
-      "config": {}
-    }
-  }
-}

lib/build-clan/default.nix

@@ -12,73 +12,171 @@
   # DEPRECATED: use meta.icon instead
   clanIcon ? null, # A path to an icon to be used for the clan, should be the same for all machines
   meta ? { }, # A set containing clan meta: name :: string, icon :: string, description :: string
-  pkgsForSystem ? (_system: null), # A map from arch to pkgs, if specified this nixpkgs will be only imported once for each system.
+  # A map from arch to pkgs, if specified this nixpkgs will be only imported once for each system.
-# This improves performance, but all nipxkgs.* options will be ignored.
+  # This improves performance, but all nipxkgs.* options will be ignored.
+  pkgsForSystem ? (_system: null),
+  /*
+    Low level inventory configuration.
+    Overrides the services configuration.
+  */
+  inventory ? { },
 }:
 let
-  deprecationWarnings = [
+  # Internal inventory, this is the result of merging all potential inventory sources:
-    (lib.warnIf (
+  # - Default instances configured via 'services'
-      clanName != null
+  # - The inventory overrides
-    ) "clanName is deprecated, please use meta.name instead. ${clanName}" null)
+  #   - Machines that exist in inventory.machines
-    (lib.warnIf (clanIcon != null) "clanIcon is deprecated, please use meta.icon instead" null)
+  # - Machines explicitly configured via 'machines' argument
-  ];
+  # - Machines that exist in the machines directory
+  # Checks on the module level:
+  # - Each service role must reference a valid machine after all machines are merged
+
+  clanToInventory =
+    config:
+    { clanPath, inventoryPath }:
+    let
+      v = lib.attrByPath clanPath null config;
+    in
+    lib.optionalAttrs (v != null) (lib.setAttrByPath inventoryPath v);
+
+  mergedInventory =
+    (lib.evalModules {
+      modules = [
+        clan-core.lib.inventory.interface
+        { inherit meta; }
+        (
+          if
+            builtins.pathExists "${directory}/inventory.json"
+          # Is recursively applied. Any explicit nix will override.
+          then
+            (builtins.fromJSON (builtins.readFile "${directory}/inventory.json"))
+          else
+            { }
+        )
+        inventory
+        # Machines explicitly configured via 'machines' argument
+        {
+          # { ${name} :: meta // { name, tags } }
+          machines = lib.mapAttrs (
+            name: config:
+            (lib.attrByPath [
+              "clan"
+              "meta"
+            ] { } config)
+            // {
+              # meta.name default is the attribute name of the machine
+              name = lib.mkDefault (
+                lib.attrByPath [
+                  "clan"
+                  "meta"
+                  "name"
+                ] name config
+              );
+            }
+            # tags
+            // (clanToInventory config {
+              clanPath = [
+                "clan"
+                "tags"
+              ];
+              inventoryPath = [ "tags" ];
+            })
+            # system
+            // (clanToInventory config {
+              clanPath = [
+                "nixpkgs"
+                "hostSystem"
+              ];
+              inventoryPath = [ "system" ];
+            })
+            # deploy.targetHost
+            // (clanToInventory config {
+              clanPath = [
+                "clan"
+                "core"
+                "networking"
+                "targetHost"
+              ];
+              inventoryPath = [
+                "deploy"
+                "targetHost"
+              ];
+            })
+          ) machines;
+        }
+
+        # Will be deprecated
+        {
+          machines =
+            lib.mapAttrs
+              (
+                name: _:
+                # Use mkForce to make sure users migrate to the inventory system.
+                # When the settings.json exists the evaluation will print the deprecation warning.
+                lib.mkForce {
+                  inherit name;
+                  system = (machineSettings name).nixpkgs.hostSystem or null;
+                }
+              )
+              (
+                lib.filterAttrs (
+                  machineName: _: builtins.pathExists "${directory}/machines/${machineName}/settings.json"
+                ) machinesDirs
+              );
+        }
+
+        # Deprecated interface
+        (if clanName != null then { meta.name = clanName; } else { })
+        (if clanIcon != null then { meta.icon = clanIcon; } else { })
+      ];
+    }).config;
+
+  inherit (clan-core.lib.inventory) buildInventory;
+
+  # map from machine name to service configuration
+  # { ${machineName} :: Config }
+  serviceConfigs = buildInventory {
+    inventory = mergedInventory;
+    inherit directory;
+  };
 
   machinesDirs = lib.optionalAttrs (builtins.pathExists "${directory}/machines") (
     builtins.readDir (directory + /machines)
   );
 
-  mergedMeta =
-    let
-      metaFromFile =
-        if (builtins.pathExists "${directory}/clan/meta.json") then
-          let
-            settings = builtins.fromJSON (builtins.readFile "${directory}/clan/meta.json");
-          in
-          settings
-        else
-          { };
-      legacyMeta = lib.filterAttrs (_: v: v != null) {
-        name = clanName;
-        icon = clanIcon;
-      };
-      optionsMeta = lib.filterAttrs (_: v: v != null) meta;
-
-      warnings =
-        builtins.map (
-          name:
-          if
-            metaFromFile.${name} or null != optionsMeta.${name} or null && optionsMeta.${name} or null != null
-          then
-            lib.warn "meta.${name} is set in different places. (exlicit option meta.${name} overrides ${directory}/clan/meta.json)" null
-          else
-            null
-        ) (builtins.attrNames metaFromFile)
-        ++ [ (if (res.name or null == null) then (throw "meta.name should be set") else null) ];
-      res = metaFromFile // legacyMeta // optionsMeta;
-    in
-    # Print out warnings before returning the merged result
-    builtins.deepSeq warnings res;
-
   machineSettings =
     machineName:
+    let
+      warn = lib.warn ''
+        The use of ./machines/<machine>/settings.json is deprecated.
+        If your settings.json is empty, you can safely remove it.
+        !!! Consider using the inventory system. !!!
+
+        File: ${directory + /machines/${machineName}/settings.json}
+
+        If there are still features missing in the inventory system, please open an issue on the clan-core repository.
+      '';
+    in
     # CLAN_MACHINE_SETTINGS_FILE allows to override the settings file temporarily
     # This is useful for doing a dry-run before writing changes into the settings.json
     # Using CLAN_MACHINE_SETTINGS_FILE requires passing --impure to nix eval
     if builtins.getEnv "CLAN_MACHINE_SETTINGS_FILE" != "" then
-      builtins.fromJSON (builtins.readFile (builtins.getEnv "CLAN_MACHINE_SETTINGS_FILE"))
+      warn (builtins.fromJSON (builtins.readFile (builtins.getEnv "CLAN_MACHINE_SETTINGS_FILE")))
     else
       lib.optionalAttrs (builtins.pathExists "${directory}/machines/${machineName}/settings.json") (
-        builtins.fromJSON (builtins.readFile (directory + /machines/${machineName}/settings.json))
+        warn (builtins.fromJSON (builtins.readFile (directory + /machines/${machineName}/settings.json)))
       );
 
-  # Read additional imports specified via a config option in settings.json
-  # This is not an infinite recursion, because the imports are discovered here
-  #   before calling evalModules.
-  # It is still useful to have the imports as an option, as this allows for type
-  #   checking and easy integration with the config frontend(s)
   machineImports =
     machineSettings: map (module: clan-core.clanModules.${module}) (machineSettings.clanImports or [ ]);
 
+  deprecationWarnings = [
+    (lib.warnIf (
+      clanName != null
+    ) "clanName in buildClan is deprecated, please use meta.name instead." null)
+    (lib.warnIf (clanIcon != null) "clanIcon is deprecated, please use meta.icon instead" null)
+  ];
+
   # TODO: remove default system once we have a hardware-config mechanism
   nixosConfiguration =
     {
@@ -94,10 +192,20 @@ let
         in
         (machineImports settings)
         ++ [
+          {
+            # Autoinclude configuration.nix and hardware-configuration.nix
+            imports = builtins.filter (p: builtins.pathExists p) [
+              "${directory}/machines/${name}/configuration.nix"
+              "${directory}/machines/${name}/hardware-configuration.nix"
+            ];
+          }
           settings
           clan-core.nixosModules.clanCore
           extraConfig
           (machines.${name} or { })
+          # Inherit the inventory assertions ?
+          { inherit (mergedInventory) assertions; }
+          { imports = serviceConfigs.${name} or { }; }
           (
             {
               # Settings
@@ -125,7 +233,7 @@ let
       } // specialArgs;
     };
 
-  allMachines = machinesDirs // machines;
+  allMachines = mergedInventory.machines or { };
 
   supportedSystems = [
     "x86_64-linux"
@@ -177,9 +285,13 @@ builtins.deepSeq deprecationWarnings {
   inherit nixosConfigurations;
 
   clanInternals = {
-    # Evaluated clan meta
+    inherit (clan-core) clanModules;
-    # Merged /clan/meta.json with overrides from buildClan
+    source = "${clan-core}";
-    meta = mergedMeta;
+
+    meta = mergedInventory.meta;
+    inventory = mergedInventory;
+
+    inventoryFile = "${directory}/inventory.json";
 
     # machine specifics
     machines = configsPerSystem;

lib/default.nix

@@ -5,7 +5,10 @@
   ...
 }:
 {
+  evalClanModules = import ./eval-clan-modules { inherit clan-core nixpkgs lib; };
+  buildClan = import ./build-clan { inherit clan-core lib nixpkgs; };
+  facts = import ./facts.nix { inherit lib; };
+  inventory = import ./inventory { inherit lib clan-core; };
   jsonschema = import ./jsonschema { inherit lib; };
   modules = import ./description.nix { inherit clan-core lib; };
-  buildClan = import ./build-clan { inherit clan-core lib nixpkgs; };
 }

lib/description.nix

@@ -1,5 +1,4 @@
-{ lib, clan-core, ... }:
+{ clan-core, lib }:
-
 rec {
   getReadme =
     modulename:
@@ -16,18 +15,20 @@ rec {
   getShortDescription =
     modulename:
     let
-      content = (getReadme modulename);
+      content = getReadme modulename;
       parts = lib.splitString "---" content;
-      description = builtins.head parts;
+      # Partition the parts into the first part (the readme content) and the rest (the metadata)
-      number_of_newlines = builtins.length (lib.splitString "\n" description);
+      parsed = builtins.partition ({ index, ... }: if index >= 2 then false else true) (
+        lib.filter ({ index, ... }: index != 0) (lib.imap0 (index: part: { inherit index part; }) parts)
+      );
+
+      # Use this if the content is needed
+      # readmeContent = lib.concatMapStrings (v: "---" + v.part) parsed.wrong;
+
+      meta = builtins.fromTOML (builtins.head parsed.right).part;
     in
-    if (builtins.length parts) > 1 then
+    if (builtins.length parts >= 3) then
-      if number_of_newlines > 4 then
+      meta.description
-        throw "Short description in README.md for module ${modulename} is too long. Max 3 newlines."
-      else if number_of_newlines <= 1 then
-        throw "Missing short description in README.md for module ${modulename}."
-      else
-        description
     else
       throw "Short description delimiter `---` not found in README.md for module ${modulename}";
 }

lib/eval-clan-modules/default.nix

@@ -0,0 +1,34 @@
+{
+  nixpkgs,
+  clan-core,
+  lib,
+}:
+let
+  inherit (import nixpkgs { system = "x86_64-linux"; }) pkgs;
+
+  inherit (clan-core) clanModules;
+
+  baseModule = {
+    imports = (import (pkgs.path + "/nixos/modules/module-list.nix")) ++ [
+      {
+        nixpkgs.hostPlatform = "x86_64-linux";
+        clan.core.clanName = "dummy";
+      }
+    ];
+  };
+
+  # This function takes a list of module names and evaluates them
+  # evalClanModules :: [ String ] -> { config, options, ... }
+  evalClanModules =
+    modulenames:
+    let
+      evaled = lib.evalModules {
+        modules = [
+          baseModule
+          clan-core.nixosModules.clanCore
+        ] ++ (map (name: clanModules.${name}) modulenames);
+      };
+    in
+    evaled;
+in
+evalClanModules

lib/facts.nix

@@ -0,0 +1,71 @@
+{ lib, ... }:
+clanDir:
+let
+
+  allMachineNames = lib.mapAttrsToList (name: _: name) (builtins.readDir clanDir);
+
+  getFactPath = machine: fact: "${clanDir}/machines/${machine}/facts/${fact}";
+
+  readFact =
+    machine: fact:
+    let
+      path = getFactPath machine fact;
+    in
+    if builtins.pathExists path then builtins.readFile path else null;
+
+  # Example:
+  #
+  # readFactFromAllMachines zerotier-ip
+  # => {
+  #   machineA = "1.2.3.4";
+  #   machineB = "5.6.7.8";
+  # };
+  readFactFromAllMachines =
+    fact:
+    let
+      machines = allMachineNames;
+      facts = lib.genAttrs machines (machine: readFact machine fact);
+      filteredFacts = lib.filterAttrs (_machine: fact: fact != null) facts;
+    in
+    filteredFacts;
+
+  # all given facts are are set and factvalues are never null.
+  #
+  # Example:
+  #
+  # readFactsFromAllMachines [ "zerotier-ip" "syncthing.pub" ]
+  # => {
+  #   machineA =
+  #     {
+  #       "zerotier-ip" = "1.2.3.4";
+  #       "synching.pub" = "1234";
+  #     };
+  #   machineB =
+  #     {
+  #       "zerotier-ip" = "5.6.7.8";
+  #       "synching.pub" = "23456719";
+  #     };
+  # };
+  readFactsFromAllMachines =
+    facts:
+    let
+      # machine -> fact -> factvalue
+      machinesFactsAttrs = lib.genAttrs allMachineNames (
+        machine: lib.genAttrs facts (fact: readFact machine fact)
+      );
+      # remove all machines which don't have all facts set
+      filteredMachineFactAttrs = lib.filterAttrs (
+        _machine: values: builtins.all (fact: values.${fact} != null) facts
+      ) machinesFactsAttrs;
+    in
+    filteredMachineFactAttrs;
+in
+{
+  inherit
+    allMachineNames
+    getFactPath
+    readFact
+    readFactFromAllMachines
+    readFactsFromAllMachines
+    ;
+}

lib/flake-module.nix

@@ -5,9 +5,12 @@
   ...
 }:
 {
-  imports = [ ./jsonschema/flake-module.nix ];
+  imports = [
+    ./jsonschema/flake-module.nix
+    ./inventory/flake-module.nix
+  ];
   flake.lib = import ./default.nix {
-    inherit lib;
+    inherit lib inputs;
     inherit (inputs) nixpkgs;
     clan-core = self;
   };

lib/inventory/.envrc

@@ -1,3 +1,4 @@
+# shellcheck shell=bash
 source_up
 
 watch_file flake-module.nix

lib/inventory/README.md

@@ -0,0 +1,90 @@
+# Inventory
+
+The inventory is our concept for distributed services. Users can configure multiple machines with minimal effort.
+
+- The inventory acts as a declarative source of truth for all machine configurations.
+- Users can easily add or remove machines to/from services.
+- Ensures that all machines and services are configured consistently, across multiple nixosConfigs.
+- Defaults and predefined roles in our modules minimizes the need for manual configuration.
+
+Open questions:
+
+- [ ] How do we set default role, description and other metadata?
+  - It must be accessible from Python.
+  - It must set the value in the module system.
+
+- [ ] Inventory might use assertions. Should each machine inherit the inventory assertions ?
+
+- [ ] Is the service config interface the same as the module config interface ?
+
+- [ ] As a user do I want to see borgbackup as the high level category?
+
+
+Architecture
+
+```
+nixosConfig < machine_module        < inventory
+---------------------------------------------
+nixos   < borgbackup            <- inventory <-> UI
+
+        creates the config      Maps from high level services to the borgbackup clan module
+        for ONE machine         Inventory is completely serializable.
+                                UI can interact with the inventory to define machines, and services
+                                Defining Users is out of scope for the first prototype.
+```
+
+## Provides a specification for the inventory
+
+It is used for design phase and as validation helper.
+
+> Cue is less verbose and easier to understand and maintain than json-schema.
+> Json-schema, if needed can be easily generated on-the fly.
+
+## Checking validity
+
+Directly check a json against the schema
+
+`cue vet inventory.json root.cue -d '#Root'`
+
+## Json schema
+
+Export the json-schema i.e. for usage in python / javascript / nix
+
+`cue export --out openapi root.cue`
+
+## Usage
+
+Comments are rendered as descriptions in the json schema.
+
+```cue
+// A name of the clan (primarily shown by the UI)
+name: string
+```
+
+Cue open sets. In the following `foo = {...}` means that the key `foo` can contain any arbitrary json object.
+
+```cue
+foo: { ... }
+```
+
+Cue dynamic keys.
+
+```cue
+[string]: {
+    attr: string
+}
+```
+
+This is the schema of
+
+```json
+{
+    "a": {
+        "attr": "foo"
+    },
+    "b": {
+        "attr": "bar"
+    }
+    // ... Indefinitely more dynamic keys of type "string"
+}
+```

lib/inventory/build-inventory/default.nix

@@ -0,0 +1,157 @@
+# Generate partial NixOS configurations for every machine in the inventory
+# This function is responsible for generating the module configuration for every machine in the inventory.
+{ lib, clan-core }:
+{ inventory, directory }:
+let
+  machines = machinesFromInventory inventory;
+
+  resolveTags =
+    # Inventory, { machines :: [string], tags :: [string] }
+    {
+      serviceName,
+      instanceName,
+      roleName,
+      inventory,
+      members,
+    }:
+    {
+      machines =
+        members.machines or [ ]
+        ++ (builtins.foldl' (
+          acc: tag:
+          let
+            # For error printing
+            availableTags = lib.foldlAttrs (
+              acc: _: v:
+              v.tags or [ ] ++ acc
+            ) [ ] (inventory.machines);
+
+            tagMembers = builtins.attrNames (
+              lib.filterAttrs (_n: v: builtins.elem tag v.tags or [ ]) inventory.machines
+            );
+          in
+          if tagMembers == [ ] then
+            throw ''
+              inventory.services.${serviceName}.${instanceName}: - ${roleName} tags: no machine with tag '${tag}' found.
+              Available tags: ${builtins.toJSON (lib.unique availableTags)}
+            ''
+          else
+            acc ++ tagMembers
+        ) [ ] members.tags or [ ]);
+    };
+
+  /*
+    Returns a NixOS configuration for every machine in the inventory.
+
+    machinesFromInventory :: Inventory -> { ${machine_name} :: NixOSConfiguration }
+  */
+  machinesFromInventory =
+    inventory:
+    # For every machine in the inventory, build a NixOS configuration
+    # For each machine generate config, forEach service, if the machine is used.
+    builtins.mapAttrs (
+      machineName: machineConfig:
+      lib.foldlAttrs (
+        # [ Modules ], String, { ${instance_name} :: ServiceConfig }
+        acc: serviceName: serviceConfigs:
+        acc
+        # Collect service config
+        ++ (lib.foldlAttrs (
+          # [ Modules ], String, ServiceConfig
+          acc2: instanceName: serviceConfig:
+          let
+            resolvedRoles = builtins.mapAttrs (
+              roleName: members:
+              resolveTags {
+                inherit
+                  serviceName
+                  instanceName
+                  roleName
+                  inventory
+                  members
+                  ;
+              }
+            ) serviceConfig.roles;
+
+            isInService = builtins.any (members: builtins.elem machineName members.machines) (
+              builtins.attrValues resolvedRoles
+            );
+
+            # Inverse map of roles. Allows for easy lookup of roles for a given machine.
+            # { ${machine_name} :: [roles]
+            inverseRoles = lib.foldlAttrs (
+              acc: roleName:
+              { machines }:
+              acc
+              // builtins.foldl' (
+                acc2: machineName: acc2 // { ${machineName} = (acc.${machineName} or [ ]) ++ [ roleName ]; }
+              ) { } machines
+            ) { } resolvedRoles;
+
+            machineServiceConfig = (serviceConfig.machines.${machineName} or { }).config or { };
+            globalConfig = serviceConfig.config or { };
+
+            globalImports = serviceConfig.imports or [ ];
+            machineImports = serviceConfig.machines.${machineName}.imports or [ ];
+            roleServiceImports = builtins.foldl' (
+              acc: role: acc ++ serviceConfig.roles.${role}.imports or [ ]
+            ) [ ] inverseRoles.${machineName} or [ ];
+
+            # TODO: maybe optimize this dont lookup the role in inverse roles. Imports are not lazy
+            roleModules = builtins.map (
+              role:
+              let
+                path = "${clan-core.clanModules.${serviceName}}/roles/${role}.nix";
+              in
+              if builtins.pathExists path then
+                path
+              else
+                throw "Module doesn't have role: '${role}'. Path: ${path} not found."
+            ) inverseRoles.${machineName} or [ ];
+
+            roleServiceConfigs = builtins.map (
+              role: serviceConfig.roles.${role}.config or { }
+            ) inverseRoles.${machineName} or [ ];
+
+            customImports = map (s: "${directory}/${s}") (
+              globalImports ++ machineImports ++ roleServiceImports
+            );
+          in
+
+          if isInService then
+            acc2
+            ++ [
+              {
+                imports = [ clan-core.clanModules.${serviceName} ] ++ roleModules ++ customImports;
+                config.clan.${serviceName} = lib.mkMerge (
+                  [
+                    globalConfig
+                    machineServiceConfig
+                  ]
+                  ++ roleServiceConfigs
+                );
+              }
+              {
+                config.clan.inventory.services.${serviceName}.${instanceName} = {
+                  roles = resolvedRoles;
+                  # TODO: Add inverseRoles to the service config if needed
+                  # inherit inverseRoles;
+                };
+              }
+            ]
+          else
+            acc2
+        ) [ ] serviceConfigs)
+      ) [ ] inventory.services
+      # Append each machine config
+      ++ [
+        (lib.optionalAttrs (machineConfig.system or null != null) {
+          config.nixpkgs.hostPlatform = machineConfig.system;
+        })
+        (lib.optionalAttrs (machineConfig.deploy.targetHost or null != null) {
+          config.clan.core.networking.targetHost = machineConfig.deploy.targetHost;
+        })
+      ]
+    ) inventory.machines or { };
+in
+machines

lib/inventory/build-inventory/interface.nix

@@ -0,0 +1,164 @@
+{ config, lib, ... }:
+let
+  types = lib.types;
+
+  metaOptions = {
+    name = lib.mkOption { type = types.str; };
+    description = lib.mkOption {
+      default = null;
+      type = types.nullOr types.str;
+    };
+    icon = lib.mkOption {
+      default = null;
+      type = types.nullOr types.str;
+    };
+  };
+
+  moduleConfig = lib.mkOption {
+    default = { };
+    type = types.attrsOf types.anything;
+  };
+
+  importsOption = lib.mkOption {
+    description = ''
+      List of imported '.nix' files.
+
+          Each filename must be a string and is interpreted relative to the 'directory' passed to buildClan.
+          The import only happens if the machine is part of the service or role.
+
+          ## Example
+
+          To import the `special.nix` file
+
+          ```
+          . Clan Directory
+          ├── flake.nix
+          ...
+          └── modules
+              ├── special.nix
+              └── ...
+          ```
+
+          ```nix
+          {
+            imports = [ "modules/special.nix" ];
+          }
+          ```
+
+    '';
+    default = [ ];
+    type = types.listOf types.str;
+  };
+in
+{
+  options = {
+    assertions = lib.mkOption {
+      type = types.listOf types.unspecified;
+      internal = true;
+      visible = false;
+      default = [ ];
+    };
+    meta = metaOptions;
+
+    machines = lib.mkOption {
+      default = { };
+      type = types.attrsOf (
+        types.submodule {
+          options = {
+            inherit (metaOptions) name description icon;
+            tags = lib.mkOption {
+
+              default = [ ];
+              apply = lib.unique;
+              type = types.listOf types.str;
+            };
+            system = lib.mkOption {
+              default = null;
+              type = types.nullOr types.str;
+            };
+            deploy.targetHost = lib.mkOption {
+              description = "Configuration for the deployment of the machine";
+              default = null;
+              type = types.nullOr types.str;
+            };
+          };
+        }
+      );
+    };
+
+    services = lib.mkOption {
+      default = { };
+      type = types.attrsOf (
+        types.attrsOf (
+          types.submodule {
+            options.meta = metaOptions;
+            options.imports = importsOption;
+            options.config = moduleConfig;
+            options.machines = lib.mkOption {
+              default = { };
+              type = types.attrsOf (
+                types.submodule {
+                  options.imports = importsOption;
+                  options.config = moduleConfig;
+                }
+              );
+            };
+            options.roles = lib.mkOption {
+              default = { };
+              type = types.attrsOf (
+                types.submodule {
+                  options.machines = lib.mkOption {
+                    default = [ ];
+                    type = types.listOf types.str;
+                  };
+                  options.tags = lib.mkOption {
+                    default = [ ];
+                    apply = lib.unique;
+                    type = types.listOf types.str;
+                  };
+                  options.config = moduleConfig;
+                  options.imports = importsOption;
+                }
+              );
+            };
+          }
+        )
+      );
+    };
+  };
+
+  # Smoke validation of the inventory
+  config.assertions =
+    let
+      # Inventory assertions
+      # - All referenced machines must exist in the top-level machines
+      serviceAssertions = lib.foldlAttrs (
+        ass1: serviceName: c:
+        ass1
+        ++ lib.foldlAttrs (
+          ass2: instanceName: instanceConfig:
+          let
+            serviceMachineNames = lib.attrNames instanceConfig.machines;
+            topLevelMachines = lib.attrNames config.machines;
+            # All machines must be defined in the top-level machines
+            assertions = builtins.map (m: {
+              assertion = builtins.elem m topLevelMachines;
+              message = "${serviceName}.${instanceName}.machines.${m}. Should be one of [ ${builtins.concatStringsSep " | " topLevelMachines} ]";
+            }) serviceMachineNames;
+          in
+          ass2 ++ assertions
+        ) [ ] c
+      ) [ ] config.services;
+
+      # Machine assertions
+      # - A machine must define their host system
+      machineAssertions = map (
+        { name, ... }:
+        {
+          assertion = true;
+          message = "Machine ${name} should define its host system in the inventory. ()";
+        }
+      ) (lib.attrsToList (lib.filterAttrs (_n: v: v.system or null == null) config.machines));
+    in
+    machineAssertions ++ serviceAssertions;
+}

lib/inventory/default.nix

@@ -0,0 +1,5 @@
+{ lib, clan-core }:
+{
+  buildInventory = import ./build-inventory { inherit lib clan-core; };
+  interface = ./build-inventory/interface.nix;
+}

lib/inventory/example.nix

@@ -0,0 +1,39 @@
+{ self, ... }:
+self.lib.buildClan {
+  # Name of the clan in the UI, should be unique
+  meta.name = "Inventory clan";
+
+  # Should usually point to the directory of flake.nix
+  directory = self;
+
+  inventory = {
+    services = {
+      borgbackup.instance_1 = {
+        roles.server.machines = [ "backup_server" ];
+        roles.client.tags = [ "backup" ];
+      };
+    };
+  };
+
+  # merged with
+  machines = {
+    "backup_server" = {
+      clan.tags = [ "all" ];
+      # ... rest of the machine config
+    };
+    "client_1_machine" = {
+      clan.tags = [
+        "all"
+        "backup"
+      ];
+    };
+    "client_2_machine" = {
+      clan.tags = [
+        "all"
+        "backup"
+      ];
+      # Name of the machine in the UI
+      clan.meta.name = "camina";
+    };
+  };
+}

lib/inventory/examples/borgbackup.json

@@ -0,0 +1,53 @@
+{
+  "machines": {
+    "camina_machine": {
+      "name": "camina",
+      "tags": ["laptop"]
+    },
+    "vyr_machine": {
+      "name": "vyr"
+    },
+    "vi_machine": {
+      "name": "vi",
+      "tags": ["laptop"]
+    }
+  },
+  "meta": {
+    "name": "kenjis clan"
+  },
+  "services": {
+    "borgbackup": {
+      "instance_1": {
+        "meta": {
+          "name": "My backup"
+        },
+        "roles": {
+          "server": {
+            "machines": ["vyr_machine"]
+          },
+          "client": {
+            "machines": ["vyr_machine"],
+            "tags": ["laptop"]
+          }
+        },
+        "machines": {},
+        "config": {}
+      },
+      "instance_2": {
+        "meta": {
+          "name": "My backup"
+        },
+        "roles": {
+          "server": {
+            "machines": ["vi_machine"]
+          },
+          "client": {
+            "machines": ["camina_machine"]
+          }
+        },
+        "machines": {},
+        "config": {}
+      }
+    }
+  }
+}

lib/inventory/flake-module.nix

@@ -0,0 +1,147 @@
+{ self, inputs, ... }:
+let
+  inputOverrides = builtins.concatStringsSep " " (
+    builtins.map (input: " --override-input ${input} ${inputs.${input}}") (builtins.attrNames inputs)
+  );
+in
+{
+  flake.inventory = import ./example.nix { inherit self; };
+
+  perSystem =
+    {
+      pkgs,
+      lib,
+      config,
+      system,
+      self',
+      ...
+    }:
+    let
+      buildInventory = import ./build-inventory {
+        clan-core = self;
+        inherit lib;
+      };
+
+      getSchema = import ./interface-to-schema.nix { inherit lib self; };
+
+      # The schema for the inventory, without default values, from the module system.
+      # This is better suited for human reading and for generating code.
+      bareSchema = getSchema { includeDefaults = false; };
+      # The schema for the inventory with default values, from the module system.
+      # This is better suited for validation, since default values are included.
+      fullSchema = getSchema { };
+    in
+    {
+      legacyPackages.inventory = {
+        inherit fullSchema;
+        inherit bareSchema;
+      };
+
+      devShells.inventory-schema = pkgs.mkShell {
+        inputsFrom = with config.checks; [
+          lib-inventory-examples-cue
+          lib-inventory-eval
+          self'.devShells.default
+        ];
+      };
+
+      # Inventory schema with concrete module implementations
+      packages.inventory-api-docs = pkgs.stdenv.mkDerivation {
+        name = "inventory-schema";
+        buildInputs = [ ];
+        src = ./.;
+        buildPhase = ''
+          cat <<EOF > "$out"
+          # Inventory API
+
+          *Inventory* is an abstract service layer for consistently configuring distributed services across machine boundaries.
+
+          The following is a specification of the inventory in [cuelang](https://cuelang.org/) format.
+
+          \`\`\`cue
+          EOF
+
+          cat ${self'.packages.inventory-schema-pretty}/schema.cue >> $out
+
+          cat <<EOF >> $out
+          \`\`\`
+          EOF
+        '';
+      };
+
+      packages.inventory-schema = pkgs.stdenv.mkDerivation {
+        name = "inventory-schema";
+        buildInputs = [ pkgs.cue ];
+        src = ./.;
+        buildPhase = ''
+          export SCHEMA=${builtins.toFile "inventory-schema.json" (builtins.toJSON fullSchema.schemaWithModules)}
+          cp $SCHEMA schema.json
+          cue import -f -p compose -l '#Root:' schema.json
+          mkdir $out
+          cp schema.cue $out
+          cp schema.json $out
+        '';
+      };
+      packages.inventory-schema-pretty = pkgs.stdenv.mkDerivation {
+        name = "inventory-schema-pretty";
+        buildInputs = [ pkgs.cue ];
+        src = ./.;
+        buildPhase = ''
+          export SCHEMA=${builtins.toFile "inventory-schema.json" (builtins.toJSON bareSchema.schemaWithModules)}
+          cp $SCHEMA schema.json
+          cue import -f -p compose -l '#Root:' schema.json
+          mkdir $out
+          cp schema.cue $out
+          cp schema.json $out
+        '';
+      };
+
+      # Run: nix-unit --extra-experimental-features flakes --flake .#legacyPackages.x86_64-linux.evalTests
+      legacyPackages.evalTests-inventory = import ./tests {
+        inherit buildInventory;
+        clan-core = self;
+      };
+
+      checks = {
+        lib-inventory-examples-cue = pkgs.stdenv.mkDerivation {
+          name = "inventory-schema-checks";
+          src = ./.;
+          buildInputs = [ pkgs.cue ];
+          buildPhase = ''
+            echo "Running inventory tests..."
+            # Cue is easier to run in the same directory as the schema
+            cp ${self'.packages.inventory-schema}/schema.cue root.cue
+
+            ls -la .
+
+            echo "Validate test/*.json against inventory-schema..."
+            cat root.cue
+
+            test_dir="./examples"
+            for file in "$test_dir"/*; do
+              # Check if the item is a file
+              if [ -f "$file" ]; then
+                # Print the filename
+                echo "Running test on: $file"
+
+                # Run the cue vet command
+                cue vet "$file" root.cue -d "#Root"
+              fi
+            done
+
+            touch $out
+          '';
+        };
+        lib-inventory-eval = pkgs.runCommand "tests" { nativeBuildInputs = [ pkgs.nix-unit ]; } ''
+          export HOME="$(realpath .)"
+
+          nix-unit --eval-store "$HOME" \
+            --extra-experimental-features flakes \
+            ${inputOverrides} \
+            --flake ${self}#legacyPackages.${system}.evalTests-inventory
+
+          touch $out
+        '';
+      };
+    };
+}

lib/inventory/interface-to-schema.nix

@@ -0,0 +1,132 @@
+{ lib, self, ... }:
+{
+  includeDefaults ? true,
+}:
+let
+  optionsFromModule =
+    mName:
+    let
+      eval = self.lib.evalClanModules [ mName ];
+    in
+    if (eval.options.clan ? "${mName}") then eval.options.clan.${mName} else { };
+
+  modulesSchema = lib.mapAttrs (
+    moduleName: _: jsonLib'.parseOptions (optionsFromModule moduleName) { }
+  ) self.clanModules;
+
+  jsonLib = self.lib.jsonschema { inherit includeDefaults; };
+  jsonLib' = self.lib.jsonschema {
+    inherit includeDefaults;
+    header = { };
+  };
+  inventorySchema = jsonLib.parseModule (import ./build-inventory/interface.nix);
+
+  getRoles =
+    modulePath:
+    let
+      rolesDir = "${modulePath}/roles";
+    in
+    if builtins.pathExists rolesDir then
+      lib.pipe rolesDir [
+        builtins.readDir
+        (lib.filterAttrs (_n: v: v == "regular"))
+        lib.attrNames
+        (map (fileName: lib.removeSuffix ".nix" fileName))
+      ]
+    else
+      null;
+
+  # The actual schema for the inventory
+  # !!! We cannot import the module into the interface.nix, because it would cause evaluation overhead.
+  # Modifies:
+  # - service.<serviceName>.<instanceName>.config = moduleSchema
+  # - service.<serviceName>.<instanceName>.machine.<machineName>.config = moduleSchema
+  # - service.<serviceName>.<instanceName>.roles = acutalRoles
+
+  schema =
+    let
+      moduleToService = moduleName: moduleSchema: {
+        type = "object";
+        additionalProperties = {
+          type = "object";
+          additionalProperties = false;
+          properties = {
+            meta = {
+              title = "service-meta";
+            } // inventorySchema.properties.services.additionalProperties.additionalProperties.properties.meta;
+
+            config = {
+              title = "${moduleName}-config";
+              default = { };
+            } // moduleSchema;
+            roles = {
+              type = "object";
+              additionalProperties = false;
+              required = [ ];
+              properties = lib.listToAttrs (
+                map (role: {
+                  name = role;
+                  value =
+                    lib.recursiveUpdate
+                      inventorySchema.properties.services.additionalProperties.additionalProperties.properties.roles.additionalProperties
+                      {
+                        properties.config = {
+                          title = "${moduleName}-config";
+                          default = { };
+                        } // moduleSchema;
+                      };
+                }) (rolesOf moduleName)
+              );
+            };
+            machines =
+              lib.recursiveUpdate
+                inventorySchema.properties.services.additionalProperties.additionalProperties.properties.machines
+                {
+                  additionalProperties.properties.config = {
+                    title = "${moduleName}-config";
+                    default = { };
+                  } // moduleSchema;
+                };
+          };
+        };
+      };
+
+      rolesOf =
+        moduleName:
+        let
+          roles = getRoles self.clanModules.${moduleName};
+        in
+        if roles == null then [ ] else roles;
+      moduleServices = lib.mapAttrs moduleToService (
+        lib.filterAttrs (n: _v: rolesOf n != [ ]) modulesSchema
+      );
+    in
+    inventorySchema
+    // {
+      properties = inventorySchema.properties // {
+        services = {
+          type = "object";
+          additionalProperties = false;
+          properties = moduleServices;
+        };
+      };
+    };
+in
+{
+  /*
+    The abstract inventory without the exact schema for each module filled
+
+    InventorySchema<T extends Any> :: {
+      serviceConfig :: dict[str, T];
+    }
+  */
+  abstractSchema = inventorySchema;
+  /*
+    The inventory with each module schema filled.
+
+    InventorySchema<T extends ModuleSchema> :: {
+      ${serviceConfig} :: T; # <- each concrete module name is filled
+    }
+  */
+  schemaWithModules = schema;
+}

lib/inventory/tests/default.nix

@@ -0,0 +1,173 @@
+{ buildInventory, clan-core, ... }:
+{
+  test_inventory_empty = {
+    # Empty inventory should return an empty module
+    expr = buildInventory {
+      inventory = { };
+      directory = ./.;
+    };
+    expected = { };
+  };
+  test_inventory_role_imports =
+    let
+      configs = buildInventory {
+        directory = ./.;
+        inventory = {
+          services = {
+            borgbackup.instance_1 = {
+              roles.server.machines = [ "backup_server" ];
+              roles.client.machines = [
+                "client_1_machine"
+                "client_2_machine"
+              ];
+            };
+          };
+          machines = {
+            "backup_server" = { };
+            "client_1_machine" = { };
+            "client_2_machine" = { };
+          };
+        };
+      };
+    in
+    {
+      expr = {
+        server_imports = (builtins.head configs."backup_server").imports;
+        client_1_imports = (builtins.head configs."client_1_machine").imports;
+        client_2_imports = (builtins.head configs."client_2_machine").imports;
+      };
+
+      expected = {
+        server_imports = [
+          clan-core.clanModules.borgbackup
+          "${clan-core.clanModules.borgbackup}/roles/server.nix"
+        ];
+        client_1_imports = [
+          clan-core.clanModules.borgbackup
+          "${clan-core.clanModules.borgbackup}/roles/client.nix"
+        ];
+        client_2_imports = [
+          clan-core.clanModules.borgbackup
+          "${clan-core.clanModules.borgbackup}/roles/client.nix"
+        ];
+      };
+    };
+  test_inventory_tag_resolve =
+    let
+      configs = buildInventory {
+        directory = ./.;
+        inventory = {
+          services = {
+            borgbackup.instance_1 = {
+              roles.client.tags = [ "backup" ];
+            };
+          };
+          machines = {
+            "not_used_machine" = { };
+            "client_1_machine" = {
+              tags = [ "backup" ];
+            };
+            "client_2_machine" = {
+              tags = [ "backup" ];
+            };
+          };
+        };
+      };
+    in
+    {
+      expr = {
+        # A machine that includes the backup service should have 3 imports
+        # - one for some service agnostic properties of the machine itself
+        # - One for the service itself (default.nix)
+        # - one for the role (roles/client.nix)
+        client_1_machine = builtins.length configs.client_1_machine;
+        client_2_machine = builtins.length configs.client_2_machine;
+        not_used_machine = builtins.length configs.not_used_machine;
+      };
+      expected = {
+        client_1_machine = 4;
+        client_2_machine = 4;
+        not_used_machine = 2;
+      };
+    };
+
+  test_inventory_multiple_roles =
+    let
+      configs = buildInventory {
+        directory = ./.;
+        inventory = {
+          services = {
+            borgbackup.instance_1 = {
+              roles.client.machines = [ "machine_1" ];
+              roles.server.machines = [ "machine_1" ];
+            };
+          };
+          machines = {
+            "machine_1" = { };
+          };
+        };
+      };
+    in
+    {
+      expr = {
+        machine_1_imports = (builtins.head configs."machine_1").imports;
+      };
+      expected = {
+        machine_1_imports = [
+          clan-core.clanModules.borgbackup
+          "${clan-core.clanModules.borgbackup}/roles/client.nix"
+          "${clan-core.clanModules.borgbackup}/roles/server.nix"
+        ];
+      };
+    };
+
+  test_inventory_role_doesnt_exist =
+    let
+      configs = buildInventory {
+        directory = ./.;
+        inventory = {
+          services = {
+            borgbackup.instance_1 = {
+              roles.roleXYZ.machines = [ "machine_1" ];
+            };
+          };
+          machines = {
+            "machine_1" = { };
+          };
+        };
+      };
+    in
+    {
+      expr = configs;
+      expectedError = {
+        type = "ThrownError";
+        msg = "Module doesn't have role.*";
+      };
+    };
+  test_inventory_tag_doesnt_exist =
+    let
+      configs = buildInventory {
+        directory = ./.;
+        inventory = {
+          services = {
+            borgbackup.instance_1 = {
+              roles.client.machines = [ "machine_1" ];
+              roles.client.tags = [ "tagXYZ" ];
+            };
+          };
+          machines = {
+            "machine_1" = {
+              tags = [ "tagABC" ];
+            };
+          };
+        };
+      };
+    in
+    {
+      expr = configs;
+      expectedError = {
+        type = "ThrownError";
+        msg = "no machine with tag '\\w+' found";
+      };
+    };
+}

lib/jsonschema/default.nix

@@ -1,9 +1,16 @@
 {
   lib ? import <nixpkgs/lib>,
+}:
+{
   excludedTypes ? [
     "functionTo"
     "package"
   ],
+  includeDefaults ? true,
+  header ? {
+    "$schema" = "http://json-schema.org/draft-07/schema#";
+  },
+  specialArgs ? { },
 }:
 let
   # remove _module attribute from options
@@ -40,39 +47,52 @@ let
   ];
 in
 rec {
-
   # parses a nixos module to a jsonschema
   parseModule =
     module:
     let
-      evaled = lib.evalModules { modules = [ module ]; };
+      evaled = lib.evalModules {
+        modules = [ module ];
+        inherit specialArgs;
+      };
     in
-    parseOptions evaled.options;
+    parseOptions evaled.options { };
+
+  parseOptions' = lib.flip parseOptions { addHeader = false; };
 
   # parses a set of evaluated nixos options to a jsonschema
   parseOptions =
-    options':
+    options:
+    {
+      # The top-level header object should specify at least the schema version
+      # Can be customized if needed
+      # By default the header is not added to the schema
+      addHeader ? true,
+    }:
     let
-      options = filterInvisibleOpts (filterExcludedAttrs (clean options'));
+      options' = filterInvisibleOpts (filterExcludedAttrs (clean options));
       # parse options to jsonschema properties
-      properties = lib.mapAttrs (_name: option: parseOption option) options;
+      properties = lib.mapAttrs (_name: option: parseOption option) options';
       # TODO: figure out how to handle if prop.anyOf is used
       isRequired = prop: !(prop ? default || prop.type or null == "object");
       requiredProps = lib.filterAttrs (_: prop: isRequired prop) properties;
       required = lib.optionalAttrs (requiredProps != { }) { required = lib.attrNames requiredProps; };
+      header' = if addHeader then header else { };
     in
     # return jsonschema
-    required
+    header'
+    // required
     // {
       type = "object";
       inherit properties;
+      additionalProperties = false;
     };
 
   # parses and evaluated nixos option to a jsonschema property definition
   parseOption =
     option:
     let
-      default = lib.optionalAttrs (option ? default) { inherit (option) default; };
+      default = lib.optionalAttrs (option ? default && includeDefaults) { inherit (option) default; };
       example = lib.optionalAttrs (option ? example) {
         examples =
           if (builtins.typeOf option.example) == "list" then option.example else [ option.example ];
@@ -81,7 +101,6 @@ rec {
         description = option.description.text or option.description;
       };
     in
-
     # either type
     # TODO: if all nested options are excluded, the parent should be excluded too
     if
@@ -103,16 +122,13 @@ rec {
         ];
         optionsList = filterExcluded optionsList';
       in
-      default // example // description // { anyOf = map parseOption optionsList; }
+      default // example // description // { oneOf = map parseOption optionsList; }
-
     # handle nested options (not a submodule)
     else if !option ? _type then
-      parseOptions option
+      parseOptions' option
-
     # throw if not an option
     else if option._type != "option" && option._type != "option-type" then
       throw "parseOption: not an option"
-
     # parse nullOr
     else if
       option.type.name == "nullOr"
@@ -129,32 +145,28 @@ rec {
       // example
       // description
       // {
-        anyOf = [
+        oneOf = [
           { type = "null"; }
         ] ++ (lib.optional (!isExcludedOption nestedOption) (parseOption nestedOption));
       }
-
     # parse bool
     else if
       option.type.name == "bool"
     # return jsonschema property definition for bool
     then
       default // example // description // { type = "boolean"; }
-
     # parse float
     else if
       option.type.name == "float"
     # return jsonschema property definition for float
     then
       default // example // description // { type = "number"; }
-
     # parse int
     else if
       (option.type.name == "int" || option.type.name == "positiveInt")
     # return jsonschema property definition for int
     then
       default // example // description // { type = "integer"; }
-
     # TODO: Add support for intMatching in jsonschema
     # parse port type aka. "unsignedInt16"
     else if
@@ -164,7 +176,6 @@ rec {
       || option.type.name == "intBetween"
     then
       default // example // description // { type = "integer"; }
-
     # parse string
     # TODO: parse more precise string types
     else if
@@ -175,51 +186,43 @@ rec {
     # return jsonschema property definition for string
     then
       default // example // description // { type = "string"; }
-
     # TODO: Add support for stringMatching in jsonschema
     # parse stringMatching
     else if lib.strings.hasPrefix "strMatching" option.type.name then
       default // example // description // { type = "string"; }
-
     # TODO: Add support for separatedString in jsonschema
     else if lib.strings.hasPrefix "separatedString" option.type.name then
       default // example // description // { type = "string"; }
-
     # parse string
     else if
       option.type.name == "path"
     # return jsonschema property definition for path
     then
       default // example // description // { type = "string"; }
-
     # parse anything
     else if
       option.type.name == "anything"
     # return jsonschema property definition for anything
     then
       default // example // description // { type = allBasicTypes; }
-
     # parse unspecified
     else if
       option.type.name == "unspecified"
     # return jsonschema property definition for unspecified
     then
       default // example // description // { type = allBasicTypes; }
-
     # parse raw
     else if
       option.type.name == "raw"
     # return jsonschema property definition for raw
     then
       default // example // description // { type = allBasicTypes; }
-
     # parse enum
     else if
       option.type.name == "enum"
     # return jsonschema property definition for enum
     then
       default // example // description // { enum = option.type.functor.payload; }
-
     # parse listOf submodule
     else if
       option.type.name == "listOf" && option.type.functor.wrapped.name == "submodule"
@@ -230,9 +233,8 @@ rec {
       // description
       // {
         type = "array";
-        items = parseOptions (option.type.functor.wrapped.getSubOptions option.loc);
+        items = parseOptions' (option.type.functor.wrapped.getSubOptions option.loc);
       }
-
     # parse list
     else if
       (option.type.name == "listOf")
@@ -252,14 +254,12 @@ rec {
         type = "array";
       }
       // (lib.optionalAttrs (!isExcludedOption nestedOption) { items = parseOption nestedOption; })
-
     # parse list of unspecified
     else if
       (option.type.name == "listOf") && (option.type.functor.wrapped.name == "unspecified")
     # return jsonschema property definition for list
     then
       default // example // description // { type = "array"; }
-
     # parse attrsOf submodule
     else if
       option.type.name == "attrsOf" && option.type.nestedTypes.elemType.name == "submodule"
@@ -270,9 +270,8 @@ rec {
       // description
       // {
         type = "object";
-        additionalProperties = parseOptions (option.type.nestedTypes.elemType.getSubOptions option.loc);
+        additionalProperties = parseOptions' (option.type.nestedTypes.elemType.getSubOptions option.loc);
       }
-
     # parse attrs
     else if
       option.type.name == "attrs"
@@ -285,7 +284,6 @@ rec {
         type = "object";
         additionalProperties = true;
       }
-
     # parse attrsOf
     # TODO: if nested option is excluded, the parent sould be excluded too
     else if
@@ -314,15 +312,13 @@ rec {
           else
             false;
       }
-
     # parse submodule
     else if
       option.type.name == "submodule"
     # return jsonschema property definition for submodule
     # then (lib.attrNames (option.type.getSubOptions option.loc).opt)
     then
-      parseOptions (option.type.getSubOptions option.loc)
+      example // description // parseOptions' (option.type.getSubOptions option.loc)
-
     # throw error if option type is not supported
     else
       notSupported option;