From 053082c932dead22dee5c93d688cbd05e23fd39b Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 25 Sep 2024 13:33:46 +0200 Subject: [PATCH 1/5] Docs/buildClan: add documentation descriptions --- lib/build-clan/eval-docs.nix | 16 +++++++++++++++ lib/build-clan/flake-module.nix | 15 ++++++++++---- lib/build-clan/interface.nix | 36 ++++++++++++++++++++++++++++++++- 3 files changed, 62 insertions(+), 5 deletions(-) create mode 100644 lib/build-clan/eval-docs.nix diff --git a/lib/build-clan/eval-docs.nix b/lib/build-clan/eval-docs.nix new file mode 100644 index 000000000..bac768666 --- /dev/null +++ b/lib/build-clan/eval-docs.nix @@ -0,0 +1,16 @@ +{ pkgs, lib }: +let + eval = lib.evalModules { + modules = [ + ./interface.nix + ]; + }; + evalDocs = pkgs.nixosOptionsDoc { + options = eval.options; + warningsAreErrors = false; + }; +in +{ + inherit (evalDocs) optionsJSON optionsNix; + inherit eval; +} diff --git a/lib/build-clan/flake-module.nix b/lib/build-clan/flake-module.nix index 13310663a..66a5a665f 100644 --- a/lib/build-clan/flake-module.nix +++ b/lib/build-clan/flake-module.nix @@ -1,11 +1,14 @@ -{ self, inputs, ... }: +{ + self, + inputs, + ... +}: let inputOverrides = builtins.concatStringsSep " " ( builtins.map (input: " --override-input ${input} ${inputs.${input}}") (builtins.attrNames inputs) ); in { - perSystem = { pkgs, @@ -13,10 +16,14 @@ in system, ... }: - # let + let + jsonDocs = import ./eval-docs.nix { + inherit pkgs lib; + }; - # in + in { + legacyPackages.clan-internals-docs = jsonDocs.optionsJSON; # Run: nix-unit --extra-experimental-features flakes --flake .#legacyPackages.x86_64-linux.evalTests legacyPackages.evalTests-build-clan = import ./tests.nix { diff --git a/lib/build-clan/interface.nix b/lib/build-clan/interface.nix index b33275165..1a85c998c 100644 --- a/lib/build-clan/interface.nix +++ b/lib/build-clan/interface.nix @@ -33,15 +33,36 @@ in # Optional machines = lib.mkOption { - type = types.attrsOf types.deferredModule; + type = types.deferredModule; default = { }; + description = '' + A mapping of machine names to their nixos configuration. + + ???+ example + + ```nix + machines = { + my-machine = { + # Your nixos configuration + }; + }; + ``` + ''; }; inventory = lib.mkOption { type = types.submodule { imports = [ ../inventory/build-inventory/interface.nix ]; }; + description = '' + The `Inventory` submodule. + + For details see the [Inventory](./inventory.md) documentation. + ''; }; # Meta meta = lib.mkOption { + description = '' + Global information about the clan. + ''; type = types.nullOr ( types.submodule { options = { @@ -58,15 +79,28 @@ in pkgsForSystem = lib.mkOption { type = types.functionTo (types.nullOr types.attrs); default = _: null; + defaultText = "Lambda :: String -> { ... } | null"; + description = '' + A function that maps from architecture to pkg. `( string -> pkgs )` + + If specified this nixpkgs will be only imported once for each system. + This improves performance, but all nipxkgs.* options will be ignored. + ''; }; # Outputs nixosConfigurations = lib.mkOption { + # Hide from documentation. + # Exposed at the top-level of the flake, clan.nixosConfigurations should not used by the user. + # Instead, the user should use the `.#nixosConfigurations` attribute of the flake output. + visible = false; type = types.lazyAttrsOf types.raw; default = { }; }; # flake.clanInternals clanInternals = lib.mkOption { + # Hide from documentation. Exposes internals to the cli. + visible = false; # type = types.raw; # ClanInternals type = types.submodule { From 21343e403287bfc49cbe2d5324ded86a680309b2 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 25 Sep 2024 13:36:33 +0200 Subject: [PATCH 2/5] Docs/inventory: add documentation for inventory attributes --- lib/inventory/build-inventory/interface.nix | 193 +++++++++++++++++--- 1 file changed, 170 insertions(+), 23 deletions(-) diff --git a/lib/inventory/build-inventory/interface.nix b/lib/inventory/build-inventory/interface.nix index e77046a8b..363417464 100644 --- a/lib/inventory/build-inventory/interface.nix +++ b/lib/inventory/build-inventory/interface.nix @@ -7,60 +7,89 @@ let description = lib.mkOption { default = null; type = types.nullOr types.str; + description = '' + Optional freeform description + ''; }; icon = lib.mkOption { default = null; type = types.nullOr types.str; + description = '' + Under construction, will be used for the UI + ''; }; }; metaOptionsWith = name: { name = lib.mkOption { type = types.str; default = name; + description = '' + Name of the machine or service + ''; }; description = lib.mkOption { default = null; type = types.nullOr types.str; + description = '' + Optional freeform description + ''; }; icon = lib.mkOption { default = null; type = types.nullOr types.str; + description = '' + Under construction, will be used for the UI + ''; }; }; moduleConfig = lib.mkOption { default = { }; type = types.attrsOf types.anything; + description = '' + Configuration of the specific clanModule. + + !!! Note + Configuration is passed to the nixos configuration scoped to the module. + + ```nix + clan. = { ... # Config } + ``` + ''; }; extraModulesOption = lib.mkOption { description = '' - List of imported '.nix' expressions. + List of addtionally imported `.nix` expressions. - Strings are interpreted relative to the 'directory' passed to buildClan. - The import only happens if the machine is part of the service or role. + Supported types: + + - **Strings**: Interpreted relative to the 'directory' passed to buildClan. + - **Paths**: should be relative to the current file. + - **Any**: Nix expression must be serializable to JSON. + + !!! Note + **The import only happens if the machine is part of the service or role.** Other types are passed through to the nixos configuration. - ## Example + ???+ Example + To import the `special.nix` file - To import the `special.nix` file - - ``` - . Clan Directory - ├── flake.nix - ... - └── modules - ├── special.nix - └── ... - ``` - - ```nix - { - extraModules = [ "modules/special.nix" ]; - } - ``` + ``` + . Clan Directory + ├── flake.nix + ... + └── modules + ├── special.nix + └── ... + ``` + ```nix + { + extraModules = [ "modules/special.nix" ]; + } + ``` ''; apply = value: if lib.isString value then value else builtins.seq (builtins.toJSON value) value; default = [ ]; @@ -84,6 +113,11 @@ in meta = metaOptions; machines = lib.mkOption { + description = '' + Machines in the inventory. + + Each machine declared here can be referencd via its `attributeName` by the `inventory.service`s `roles`. + ''; default = { }; type = types.attrsOf ( types.submodule ( @@ -93,7 +127,25 @@ in inherit (metaOptionsWith name) name description icon; tags = lib.mkOption { + description = '' + List of tags for the machine. + The machine can be referenced by its tags in `inventory.services` + + ???+ Example + ```nix + inventory.machines.machineA.tags = [ "tag1" "tag2" ]; + ``` + + ```nix + services.borgbackup."instance_1".roles.client.tags = [ "tag1" ]; + ``` + + !!! Note + Tags can be used to determine the membership of the machine in the services. + Without changing the service configuration, the machine can be added to a service by adding the correct tags to the machine. + + ''; default = [ ]; apply = lib.unique; type = types.listOf types.str; @@ -114,6 +166,25 @@ in }; services = lib.mkOption { + description = '' + Services of the inventory. + + - The first `` is the moduleName. It must be a valid clanModule name. + - The second `` is an arbitrary instance name. + + ???+ Example + ```nix + # ClanModule name. See the module documentation for the available modules. + # ↓ ↓ Instance name, can be anything, some services might use it as a unique identifier. + services.borgbackup."instance_1" = { + roles.client.machines = ["machineA"]; + }; + ``` + + !!! Note + Services MUST be added to machines via `roles` exclusively. + See [`roles..machines`](#servicesrolesmachines) or [`roles..tags`](#servicesrolesmachines) for more information. + ''; default = { }; type = types.attrsOf ( types.attrsOf ( @@ -122,13 +193,67 @@ in { options.meta = metaOptionsWith name; options.extraModules = extraModulesOption; - options.config = moduleConfig; + options.config = moduleConfig // { + description = '' + Configuration of the specific clanModule. + + !!! Note + Configuration is passed to the nixos configuration scoped to the module. + + ```nix + clan. = { ... # Config } + ``` + + ???+ Example + + For `services.borgbackup` the config is the passed to the machine with the prefix of `clan.borgbackup`. + This means all config values are mapped to the `borgbackup` clanModule exclusively (`config.clan.borgbackup`). + + ```nix + { + services.borgbackup."instance_1".config = { + destinations = [ ... ]; + # See the 'borgbackup' module docs for all options + }; + } + ``` + + !!! Note + The module author is responsible for supporting multiple instance configurations in different roles. + See each clanModule's documentation for more information. + ''; + }; options.machines = lib.mkOption { + description = '' + Attribute set of machines specific config for the service. + + Will be merged with other service configs, such as the role config and the global config. + For machine specific overrides use `mkForce` or other higher priority methods. + + ???+ Example + + ```{.nix hl_lines="4-7"} + services.borgbackup."instance_1" = { + roles.client.machines = ["machineA"]; + + machineA.config = { + # Additional specific config for the machine + # This is merged with all other config places + }; + }; + ``` + ''; default = { }; type = types.attrsOf ( types.submodule { options.extraModules = extraModulesOption; - options.config = moduleConfig; + options.config = moduleConfig // { + description = '' + Additional configuration of the specific machine. + + See how [`service...config`](#servicesconfig) works in general for further information. + ''; + }; } ); }; @@ -139,13 +264,35 @@ in options.machines = lib.mkOption { default = [ ]; type = types.listOf types.str; + example = [ "machineA" ]; + description = '' + List of machines which are part of the role. + + The machines are referenced by their `attributeName` in the `inventory.machines` attribute set. + + Memberships are decaled here to determine which machines are part of the service. + + Alternatively, `tags` can be used to determine the membership, more dynamically. + ''; }; options.tags = lib.mkOption { default = [ ]; apply = lib.unique; type = types.listOf types.str; + description = '' + List of tags which are used to determine the membership of the role. + + The tags are matched against the `inventory.machines..tags` attribute set. + If a machine has at least one tag of the role, it is part of the role. + ''; + }; + options.config = moduleConfig // { + description = '' + Additional configuration of the specific role. + + See how [`service...config`](#servicesconfig) works in general for further information. + ''; }; - options.config = moduleConfig; options.extraModules = extraModulesOption; } ); From 2c4981e2a7cb5488edfaa78e492648dbff2b6c39 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 25 Sep 2024 13:37:27 +0200 Subject: [PATCH 3/5] Docs: restructure apply diataxis --- docs/.gitignore | 5 +- docs/mkdocs.yml | 28 ++-- docs/site/clanmodules/index.md | 7 + docs/site/concepts/index.md | 3 + docs/site/getting-started/secrets.md | 3 +- docs/site/index.md | 20 ++- docs/site/manual/index.md | 42 +++++- docs/site/reference/nix-api/buildclan.md | 179 ++++++++++++++++++++--- docs/site/reference/nix-api/index.md | 6 - 9 files changed, 241 insertions(+), 52 deletions(-) create mode 100644 docs/site/clanmodules/index.md create mode 100644 docs/site/concepts/index.md delete mode 100644 docs/site/reference/nix-api/index.md diff --git a/docs/.gitignore b/docs/.gitignore index 1658c2ad8..932a47563 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,6 +1,3 @@ -/site/reference/clan-core -/site/reference/clanModules -/site/reference/nix-api/inventory.md -/site/reference/cli +/site/reference /site/static/Roboto-Regular.ttf /site/static/FiraCode-VF.ttf \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f706fe312..faf7462ef 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -40,24 +40,27 @@ exclude_docs: | nav: - index.md - - Manual: + - Getting Started: + - getting-started/index.md + - Installer: getting-started/installer.md + - Configure: getting-started/configure.md + - Secrets & Facts: getting-started/secrets.md + - Deploy Machine: getting-started/deploy.md + - Guides: - Overview: manual/index.md - - Tutorials: - - Getting Started: - - getting-started/index.md - - Installer: getting-started/installer.md - - Configure: getting-started/configure.md - - Secrets & Facts: getting-started/secrets.md - - Deploy Machine: getting-started/deploy.md - - Disk Encryption: getting-started/disk-encryption.md - - Mesh VPN: getting-started/mesh-vpn.md - - Backup & Restore: getting-started/backups.md - - Adding Machines: manual/adding-machines.md + - Disk Encryption: getting-started/disk-encryption.md + - Mesh VPN: getting-started/mesh-vpn.md + - Backup & Restore: getting-started/backups.md + - Machines: manual/include-machines.md - Inventory: manual/inventory.md - Secrets: manual/secrets.md - Secure Boot: manual/secure-boot.md - Flake-parts: manual/flake-parts.md + - Authoring ClanModules: + - clanmodules/index.md - Contribute: manual/contribute.md + - Concepts: + - Overview: concepts/index.md - Reference: - Overview: reference/index.md - Clan Modules: @@ -119,7 +122,6 @@ nav: - 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 - Blog: diff --git a/docs/site/clanmodules/index.md b/docs/site/clanmodules/index.md new file mode 100644 index 000000000..844de7d91 --- /dev/null +++ b/docs/site/clanmodules/index.md @@ -0,0 +1,7 @@ +# Authoring a clanModule + +This site will guide you through authoring your first module. Explaining which conventions must be followed, such that others will have an enjoyable experience and the module can be used with minimal effort. + +:fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: +Under construction +:fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: diff --git a/docs/site/concepts/index.md b/docs/site/concepts/index.md new file mode 100644 index 000000000..c6065e3d2 --- /dev/null +++ b/docs/site/concepts/index.md @@ -0,0 +1,3 @@ +# Core Concepts + +TODO diff --git a/docs/site/getting-started/secrets.md b/docs/site/getting-started/secrets.md index 65cfec8e3..350fde04e 100644 --- a/docs/site/getting-started/secrets.md +++ b/docs/site/getting-started/secrets.md @@ -60,5 +60,4 @@ If you followed the quickstart tutorial all necessary secrets are initialized at ## Whats next? - [Deployment](deploy.md): How to remotely deploy your machine -- [Advanced Secrets](../manual/secrets.md) If you want to know more about how to save and share passwords in your clan - +- Full [Secrets](../manual/secrets.md) guide If you want to know more about how to save and share passwords in your clan diff --git a/docs/site/index.md b/docs/site/index.md index d6f08ae57..ed40c8b52 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -1,8 +1,14 @@ +--- +hide: + - navigation + - toc +--- + # Home ## Welcome to **Clan**'s documentation -[Quickstart Guide](./getting-started/index.md){ .md-button } +[Getting Started](./getting-started/index.md){ .md-button } ## What's inside @@ -19,13 +25,21 @@ This documentation is structured into the following sections [:octicons-arrow-right-24: Getting started](./getting-started/index.md) -- :material-sign-direction:{ .lg .middle } __Manual__ +- :simple-abstract:{ .lg .middle } __Concepts__ + + --- + + Important Core Concepts that should be inderstood to get the best experience. + + [:octicons-arrow-right-24: Core Concepts](./concepts/index.md) + +- :material-sign-direction:{ .lg .middle } __Guides__ --- Instructions and explanations for practical Implementations ordered by Topic. - [:octicons-arrow-right-24: Manual](./manual/index.md) + [:octicons-arrow-right-24: Guides](./manual/index.md) - :material-api:{ .lg .middle } __Reference__ diff --git a/docs/site/manual/index.md b/docs/site/manual/index.md index a73594132..865210c2d 100644 --- a/docs/site/manual/index.md +++ b/docs/site/manual/index.md @@ -17,18 +17,50 @@ Instructions and explanations for practical Implementations ordered by Topics. [:octicons-arrow-right-24: Getting started](../getting-started/index.md) +- :fontawesome-solid-user-group:{ .lg .middle } __Authoring Modules__ + + --- + + Create clanModules that can be reused by the community. + + [:octicons-arrow-right-24: Authoring clanModules](../clanmodules/index.md) + ## Guides **How-to Guides for achieving a certain goal or solving a specific issue.** -- [Adding Machines](./adding-machines.md): Learn how Clan automatically includes machines and Nix files. +
-- [Secrets](./secrets.md): Learn how to manage secrets. +- [Machines](./include-machines.md) -- [Inventory](./inventory.md): Clan's declaration format for running **services** on one or multiple **machines**. + --- -- [Flake-parts guide](./flake-parts.md): Use clan with [flake-parts](https://flake.parts/). + Learn how Clan automatically includes machines and Nix files. -- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan! +- [Secrets](./secrets.md) + + --- + + Learn how to manage secrets. + +- [Inventory](./inventory.md) + + --- + + Clan's declaration format for running **services** on one or multiple **machines**. + +- [Flake-parts](./flake-parts.md) + + --- + + Use clan with [https://flake-parts.dev]() + +- [Contribute](./contribute.md) + + --- + + Discover how to set up a development environment to contribute to Clan! + +
\ No newline at end of file diff --git a/docs/site/reference/nix-api/buildclan.md b/docs/site/reference/nix-api/buildclan.md index 089e03f64..89a897c86 100644 --- a/docs/site/reference/nix-api/buildclan.md +++ b/docs/site/reference/nix-api/buildclan.md @@ -1,29 +1,170 @@ -# buildClan +# 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. +This provides an overview of the available arguments of the `buildClan` function. -## Inputs +!!! Note "Flake-parts" + Each attribute is also available via `clan.