diff --git a/README.md b/README.md index 2b56ecfe2..6a7e71e3b 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ If you're new to Clan and eager to dive in, start with our quickstart guide and In the Clan ecosystem, security is paramount. Learn how to handle secrets effectively: -- **Secrets Management**: Securely manage secrets by consulting [Vars](https://docs.clan.lol/guides/vars-backend/). +- **Secrets Management**: Securely manage secrets by consulting [Vars](https://docs.clan.lol/concepts/generators/). ### Contributing to Clan diff --git a/clanModules/borgbackup-static/README.md b/clanModules/borgbackup-static/README.md index a0dda99da..d93c0f6e2 100644 --- a/clanModules/borgbackup-static/README.md +++ b/clanModules/borgbackup-static/README.md @@ -4,7 +4,7 @@ description = "Statically configure borgbackup with sane defaults." !!! Danger "Deprecated" Use [borgbackup](borgbackup.md) instead. - Don't use borgbackup-static through [inventory](../../guides/inventory.md). + Don't use borgbackup-static through [inventory](../../concepts/inventory.md). This module implements the `borgbackup` backend and implements sane defaults for backup management through `borgbackup` for members of the clan. diff --git a/clanModules/root-password/README.md b/clanModules/root-password/README.md index 58e7cf467..59e5e6be7 100644 --- a/clanModules/root-password/README.md +++ b/clanModules/root-password/README.md @@ -12,7 +12,7 @@ After the system was installed/deployed the following command can be used to dis clan vars get [machine_name] root-password/root-password ``` -See also: [Vars](../../guides/vars-backend.md) +See also: [Vars](../../concepts/generators.md) To regenerate the password run: ``` diff --git a/clanModules/user-password/README.md b/clanModules/user-password/README.md index 049e1a780..9106a8d81 100644 --- a/clanModules/user-password/README.md +++ b/clanModules/user-password/README.md @@ -16,7 +16,7 @@ After the system was installed/deployed the following command can be used to dis clan vars get [machine_name] root-password/root-password ``` -See also: [Vars](../../guides/vars-backend.md) +See also: [Vars](../../concepts/generators.md) To regenerate the password run: ``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index dbf4f90f4..ca867d620 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -55,29 +55,39 @@ nav: - Add Services: guides/getting-started/add-services.md - Deploy Machine: guides/getting-started/deploy.md - Continuous Integration: guides/getting-started/check.md - - Inventory: guides/inventory.md - Using Services: guides/clanServices.md - Backup & Restore: guides/backups.md - Disk Encryption: guides/disk-encryption.md - - Vars: guides/vars-backend.md - Age Plugins: guides/age-plugins.md - - Advanced Secrets: guides/secrets.md - - Machine Autoincludes: guides/more-machines.md + - Secrets management: guides/secrets.md - Target Host: guides/target-host.md - Zerotier VPN: guides/mesh-vpn.md - Secure Boot: guides/secure-boot.md - Flake-parts: guides/flake-parts.md + - macOS: guides/macos.md + - Contributing: + - Contributing: guides/contributing/CONTRIBUTING.md + - Debugging: guides/contributing/debugging.md + - Testing: guides/contributing/testing.md + + - Writing a Service Module: guides/services/community.md + - Writing a Disko Template: guides/disko-templates/community.md - Migrations: - Migrate existing Flakes: guides/migrations/migration-guide.md - Migrate inventory Services: guides/migrations/migrate-inventory-services.md - Facts Vars Migration: guides/migrations/migration-facts-vars.md - Disk id: guides/migrations/disk-id.md - - macOS: guides/macos.md + - Concepts: + - Inventory: concepts/inventory.md + - Generators: concepts/generators.md + - Autoincludes: concepts/autoincludes.md - Reference: - Overview: reference/index.md + - Clan Options: options.md - Services: - - List: - - Overview: reference/clanServices/index.md + - Overview: + - reference/clanServices/index.md + - reference/clanServices/admin.md - reference/clanServices/borgbackup.md - reference/clanServices/data-mesher.md @@ -94,66 +104,7 @@ nav: - reference/clanServices/wifi.md - reference/clanServices/zerotier.md - API: reference/clanServices/clan-service-author-interface.md - - Writing a Service Module: developer/extensions/clanServices/index.md - - Modules: - - List: - - Overview: reference/clanModules/index.md - - reference/clanModules/frontmatter/index.md - # TODO: display the docs of the clan.service modules - - reference/clanModules/admin.md - # This is the module overview and should stay at the top - - reference/clanModules/borgbackup-static.md - - reference/clanModules/data-mesher.md - - reference/clanModules/borgbackup.md - - reference/clanModules/deltachat.md - - reference/clanModules/disk-id.md - - reference/clanModules/dyndns.md - - reference/clanModules/ergochat.md - - reference/clanModules/garage.md - - reference/clanModules/heisenbridge.md - - reference/clanModules/importer.md - - reference/clanModules/iwd.md - - reference/clanModules/localbackup.md - - reference/clanModules/localsend.md - - reference/clanModules/matrix-synapse.md - - reference/clanModules/moonlight.md - - reference/clanModules/mumble.md - - reference/clanModules/mycelium.md - - reference/clanModules/nginx.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/state-version.md - - reference/clanModules/static-hosts.md - - reference/clanModules/sunshine.md - - reference/clanModules/syncthing-static-peers.md - - reference/clanModules/syncthing.md - - reference/clanModules/thelounge.md - - reference/clanModules/trusted-nix-caches.md - - reference/clanModules/user-password.md - - reference/clanModules/auto-upgrade.md - - reference/clanModules/vaultwarden.md - - reference/clanModules/xfce.md - - reference/clanModules/zerotier-static-peers.md - - reference/clanModules/zerotier.md - - reference/clanModules/zt-tcp-relay.md - - Writing a Clan Module: developer/extensions/clanModules/index.md - - Nix API: - - inputs.clan-core.lib.clan: reference/nix-api/clan.md - - config.clan.core: - - Overview: reference/clan.core/index.md - - reference/clan.core/backups.md - - reference/clan.core/deployment.md - - reference/clan.core/facts.md - - reference/clan.core/networking.md - - reference/clan.core/settings.md - - reference/clan.core/sops.md - - reference/clan.core/state.md - - reference/clan.core/vars.md - - Inventory: reference/nix-api/inventory.md - CLI: - Overview: reference/cli/index.md @@ -170,8 +121,63 @@ nav: - reference/cli/templates.md - reference/cli/vars.md - reference/cli/vms.md + - Modules (deprecated): + - Overview: reference/clanModules/index.md + - reference/clanModules/frontmatter/index.md + # TODO: display the docs of the clan.service modules + - reference/clanModules/admin.md + # This is the module overview and should stay at the top + - reference/clanModules/borgbackup-static.md + - reference/clanModules/data-mesher.md + - reference/clanModules/borgbackup.md + - reference/clanModules/deltachat.md + - reference/clanModules/disk-id.md + - reference/clanModules/dyndns.md + - reference/clanModules/ergochat.md + - reference/clanModules/garage.md + - reference/clanModules/heisenbridge.md + - reference/clanModules/importer.md + - reference/clanModules/iwd.md + - reference/clanModules/localbackup.md + - reference/clanModules/localsend.md + - reference/clanModules/matrix-synapse.md + - reference/clanModules/moonlight.md + - reference/clanModules/mumble.md + - reference/clanModules/mycelium.md + - reference/clanModules/nginx.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/state-version.md + - reference/clanModules/static-hosts.md + - reference/clanModules/sunshine.md + - reference/clanModules/syncthing-static-peers.md + - reference/clanModules/syncthing.md + - reference/clanModules/thelounge.md + - reference/clanModules/trusted-nix-caches.md + - reference/clanModules/user-password.md + - reference/clanModules/auto-upgrade.md + - reference/clanModules/vaultwarden.md + - reference/clanModules/xfce.md + - reference/clanModules/zerotier-static-peers.md + - reference/clanModules/zerotier.md + - reference/clanModules/zt-tcp-relay.md + + - clan.core (NixOS Options): + - Overview: reference/clan.core/index.md + - reference/clan.core/backups.md + - reference/clan.core/deployment.md + - reference/clan.core/facts.md + - reference/clan.core/networking.md + - reference/clan.core/settings.md + - reference/clan.core/sops.md + - reference/clan.core/state.md + - reference/clan.core/vars.md + + - Developer-api: api.md - - Glossary: reference/glossary.md - Decisions: - Architecture Decisions: decisions/README.md - 01-clanModules: decisions/01-ClanModules.md @@ -180,16 +186,7 @@ nav: - 04-fetching-nix-from-python: decisions/04-fetching-nix-from-python.md - 05-deployment-parameters: decisions/05-deployment-parameters.md - Template: decisions/_template.md - - Options: options.md - - Developer: - - Introduction: developer/index.md - - Dev Setup: developer/contributing/CONTRIBUTING.md - - Writing a Service Module: developer/extensions/clanServices/index.md - - Writing a Clan Module: developer/extensions/clanModules/index.md - - Writing a Disko Template: developer/extensions/templates/disk/disko-templates.md - - Debugging: developer/contributing/debugging.md - - Testing: developer/contributing/testing.md - - Python API: developer/api.md + - Glossary: reference/glossary.md docs_dir: site site_dir: out @@ -249,4 +246,4 @@ plugins: - redoc-tag - redirects: redirect_maps: - guides/getting-started/secrets.md: guides/vars-backend.md + guides/getting-started/secrets.md: concepts/generators.md diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index b057da5c0..2feae390a 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -193,7 +193,7 @@ def module_header(module_name: str, has_inventory_feature: bool = False) -> str: def module_nix_usage(module_name: str) -> str: return f"""## Usage via Nix -**This module can be also imported directly in your nixos configuration. Although it is recommended to use the [inventory](../../reference/nix-api/inventory.md) interface if available.** +**This module can be also imported directly in your nixos configuration. Although it is recommended to use the [inventory](../../concepts/inventory.md) interface if available.** Some modules are considered 'low-level' or 'expert modules' and are not available via the inventory interface. @@ -373,7 +373,7 @@ This module can be used via predefined roles """ Every role has its own configuration options, which are each listed below. -For more information, see the [inventory guide](../../guides/inventory.md). +For more information, see the [inventory guide](../../concepts/inventory.md). ??? Example For example the `admin` module adds the following options globally to all machines where it is used. @@ -402,7 +402,7 @@ certain option types restricted to enable configuration through a graphical interface. !!! note "πŸ”Ή" - Modules with this indicator support the [inventory](../../guides/inventory.md) feature. + Modules with this indicator support the [inventory](../../concepts/inventory.md) feature. """ @@ -679,86 +679,6 @@ def build_option_card(module_name: str, frontmatter: Frontmatter) -> str: return f"{to_md_li(module_name, frontmatter)}\n\n" -def produce_build_clan_docs() -> None: - if not BUILD_CLAN_PATH: - msg = f"Environment variables are not set correctly: BUILD_CLAN_PATH={BUILD_CLAN_PATH}. Expected a path to the optionsJSON" - raise ClanError(msg) - - if not OUT: - msg = f"Environment variables are not set correctly: $out={OUT}" - raise ClanError(msg) - - output = """# Clan - -This provides an overview of the available arguments of the `clan` interface. - -Each attribute is documented below - -- **clan-core.lib.clan**: A function that takes an attribute set. - - ??? example "clan Example" - - ```nix - clan { - self = self; - machines = { - jon = { }; - sara = { }; - }; - }; - ``` - -- **clan with flake-parts**: Import the FlakeModule - - After importing the FlakeModule you can define your `clan` as a flake attribute - - All attribute can be defined via `clan.*` - - Further information see: [flake-parts](../../guides/flake-parts.md) guide. - - ??? example "flake-parts Example" - - ```nix - flake-parts.lib.mkFlake { inherit inputs; } ({ - systems = []; - imports = [ - clan-core.flakeModules.default - ]; - clan = { - machines = { - jon = { }; - sara = { }; - }; - }; - }); - ``` - -""" - with Path(BUILD_CLAN_PATH).open() as f: - options: dict[str, dict[str, Any]] = json.load(f) - - split = split_options_by_root(options) - for option_name, options in split.items(): - # Skip underscore options - if option_name.startswith("_"): - continue - # Skip inventory sub options - # Inventory model has its own chapter - if option_name.startswith("inventory."): - continue - - print(f"[build_clan_docs] Rendering option of {option_name}...") - root = options_to_tree(options) - - for option in root.suboptions: - output += options_docs_from_tree(option, init_level=2) - - outfile = Path(OUT) / "nix-api/clan.md" - outfile.parent.mkdir(parents=True, exist_ok=True) - with Path.open(outfile, "w") as of: - of.write(output) - - def split_options_by_root(options: dict[str, Any]) -> dict[str, dict[str, Any]]: """ Split the flat dictionary of options into a dict of which each entry will construct complete option trees. @@ -805,7 +725,7 @@ Typically needed by module authors to define roles, behavior and metadata for di !!! Note This is not a user-facing documentation, but rather meant as a reference for *module authors* - See: [clanService Authoring Guide](../../developer/extensions/clanServices/index.md) + See: [clanService Authoring Guide](../../guides/services/community.md) """ # Inventory options are already included under the clan attribute # We just omitted them in the clan docs, because we want a separate output for the inventory model @@ -834,48 +754,6 @@ class Option: suboptions: list["Option"] = field(default_factory=list) -def produce_inventory_docs() -> None: - if not BUILD_CLAN_PATH: - msg = f"Environment variables are not set correctly: BUILD_CLAN_PATH={BUILD_CLAN_PATH}. Expected a path to the optionsJSON" - raise ClanError(msg) - - if not OUT: - msg = f"Environment variables are not set correctly: $out={OUT}" - raise ClanError(msg) - - output = """# Inventory -This provides an overview of the available attributes of the `inventory` model. - -It can be set via the `inventory` attribute of the [`clan`](./clan.md#inventory) function, or via the [`clan.inventory`](./clan.md#inventory) attribute of flake-parts. - -""" - # Inventory options are already included under the clan attribute - # We just omitted them in the clan docs, because we want a separate output for the inventory model - with Path(BUILD_CLAN_PATH).open() as f: - options: dict[str, dict[str, Any]] = json.load(f) - - clan_root_option = options_to_tree(options) - # Find the inventory options - inventory_opt: None | Option = None - for opt in clan_root_option.suboptions: - if opt.name == "inventory": - inventory_opt = opt - break - - if not inventory_opt: - print("No inventory options found.") - exit(1) - # Render the inventory options - # This for loop excludes the root node - for option in inventory_opt.suboptions: - output += options_docs_from_tree(option, init_level=2) - - outfile = Path(OUT) / "nix-api/inventory.md" - outfile.parent.mkdir(parents=True, exist_ok=True) - with Path.open(outfile, "w") as of: - of.write(output) - - def option_short_name(option_name: str) -> str: parts = option_name.split(".") short_name = "" @@ -984,9 +862,6 @@ def options_docs_from_tree( if __name__ == "__main__": # produce_clan_core_docs() - produce_build_clan_docs() - produce_inventory_docs() - produce_clan_service_author_docs() produce_clan_modules_docs() diff --git a/docs/site/developer/api.md b/docs/site/api.md similarity index 100% rename from docs/site/developer/api.md rename to docs/site/api.md diff --git a/docs/site/concepts/autoincludes.md b/docs/site/concepts/autoincludes.md new file mode 100644 index 000000000..40f1631ff --- /dev/null +++ b/docs/site/concepts/autoincludes.md @@ -0,0 +1,15 @@ + +Clan automatically imports the following files from a directory and registers them. + +## Machine registration + +Every folder `machines/{machineName}` will be registered automatically as a Clan machine. + +!!! info "Automatically loaded files" + + The following files are loaded automatically for each Clan machine: + + - [x] `machines/{machineName}/configuration.nix` + - [x] `machines/{machineName}/hardware-configuration.nix` + - [x] `machines/{machineName}/facter.json` Automatically configured, for further information see [nixos-facter](https://clan.lol/blog/nixos-facter/) + - [x] `machines/{machineName}/disko.nix` Automatically loaded, for further information see the [disko docs](https://github.com/nix-community/disko/blob/master/docs/quickstart.md). diff --git a/docs/site/guides/vars-backend.md b/docs/site/concepts/generators.md similarity index 96% rename from docs/site/guides/vars-backend.md rename to docs/site/concepts/generators.md index 1d44b978f..759da6ad9 100644 --- a/docs/site/guides/vars-backend.md +++ b/docs/site/concepts/generators.md @@ -1,7 +1,4 @@ - -!!! Note - Vars is the new secret backend that will soon replace the Facts backend - +# Generators Defining a linux user's password via the nixos configuration previously required running `mkpasswd ...` and then copying the hash back into the nix configuration. @@ -11,7 +8,7 @@ For a more general explanation of what clan vars are and how it works, see the i This guide assumes - Clan is set up already (see [Getting Started](../guides/getting-started/index.md)) -- a machine has been added to the clan (see [Adding Machines](./more-machines.md)) +- a machine has been added to the clan (see [Adding Machines](../guides/getting-started/add-machines.md)) This section will walk you through the following steps: @@ -23,7 +20,7 @@ This section will walk you through the following steps: 6. share the root password between machines 7. change the password -## Declare the generator +## Declare a generator In this example, a `vars` `generator` is used to: diff --git a/docs/site/guides/inventory.md b/docs/site/concepts/inventory.md similarity index 96% rename from docs/site/guides/inventory.md rename to docs/site/concepts/inventory.md index 878a6cf57..e0712bf51 100644 --- a/docs/site/guides/inventory.md +++ b/docs/site/concepts/inventory.md @@ -9,8 +9,6 @@ The inventory logic will automatically derive the modules and configurations to The following tutorial will walk through setting up a Backup service where the terms `Service` and `Role` will become more clear. -See also: [Inventory API Documentation](../reference/nix-api/inventory.md) - !!! example "Experimental status" The inventory implementation is not considered stable yet. We are actively soliciting feedback from users. @@ -19,7 +17,7 @@ See also: [Inventory API Documentation](../reference/nix-api/inventory.md) ## Prerequisites -- [x] [Add multiple machines](./more-machines.md) to your Clan. +- [x] [Add some machines](../guides/getting-started/add-machines.md) to your Clan. ## Services diff --git a/docs/site/developer/extensions/clanModules/index.md b/docs/site/developer/extensions/clanModules/index.md deleted file mode 100644 index 6bbb559dc..000000000 --- a/docs/site/developer/extensions/clanModules/index.md +++ /dev/null @@ -1,229 +0,0 @@ -# Authoring a clanModule - -!!! Danger "Will get deprecated soon" - Please consider twice creating new modules in this format - - [`clan.service` module](../clanServices/index.md) will be the new standard soon. - -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. - - -!!! Tip - External ClanModules can be ad-hoc loaded via [`clan.inventory.modules`](../../../reference/nix-api/inventory.md#inventory.modules) - -## Bootstrapping the `clanModule` - -A ClanModule is a specific subset of a [NixOS Module](https://nix.dev/tutorials/module-system/index.html), but it has some constraints and might be used via the [Inventory](../../../guides/inventory.md) interface. -In fact a `ClanModule` can be thought of as a layer of abstraction on-top of NixOS and/or other ClanModules. It may configure sane defaults and provide an ergonomic interface that is easy to use and can also be used via a UI that is under development currently. - -Because ClanModules should be configurable via `json`/`API` all of its interface (`options`) must be serializable. - -!!! Tip - ClanModules interface can be checked by running the json schema converter as follows. - - `nix build .#legacyPackages.x86_64-linux.schemas.inventory` - - If the build succeeds the module is compatible. - -## Directory structure - -Each module SHOULD be a directory of the following format: - -```sh -# Example: borgbackup -clanModules/borgbackup -β”œβ”€β”€ README.md -└── roles - β”œβ”€β”€ client.nix - └── server.nix -``` - -!!! Tip - `README.md` is always required. See section [Readme](#readme) for further details. - - The `roles` folder is strictly required for `features = [ "inventory" ]`. - -## Registering the module - -=== "User module" - - If the module should be ad-hoc loaded. - It can be made available in any project via the [`clan.inventory.modules`](../../../reference/nix-api/inventory.md#inventory.modules) attribute. - - ```nix title="flake.nix" - # ... - # Sometimes this attribute set is defined in clan.nix - clan-core.lib.clan { - # 1. Add the module to the available clanModules with inventory support - inventory.modules = { - custom-module = ./modules/my_module; - }; - # 2. Use the module in the inventory - inventory.services = { - custom-module.instance_1 = { - roles.default.machines = [ "machineA" ]; - }; - }; - }; - ``` - -=== "Upstream module" - - If the module will be contributed to [`clan-core`](https://git.clan.lol/clan-core) - The clanModule must be registered within the `clanModules` attribute in `clan-core` - - ```nix title="clanModules/flake-module.nix" - --8<-- "clanModules/flake-module.nix:0:5" - # Register our new module here - # ... - ``` - -## Readme - -The `README.md` is a required file for all modules. It MUST contain frontmatter in [`toml`](https://toml.io) format. - -```markdown ---- -description = "Module A" ---- - -This is the example module that does xyz. -``` - -See the [Full Frontmatter reference](../../../reference/clanModules/frontmatter/index.md) further details and all supported attributes. - -## Roles - -If the module declares to implement `features = [ "inventory" ]` then it MUST contain a roles directory. - -Each `.nix` file in the `roles` directory is added as a role to the inventory service. - -Other files can also be placed alongside the `.nix` files - -```sh -└── roles - β”œβ”€β”€ client.nix - └── server.nix -``` - -Adds the roles: `client` and `server` - -??? Tip "Good to know" - Sometimes a `ClanModule` should be usable via both clan's `inventory` concept but also natively as a NixOS module. - - > In the long term, we want most modules to implement support for the inventory, - > but we are also aware that there are certain low-level modules that always serve as a backend for other higher-level `clanModules` with inventory support. - > These modules may not want to implement inventory interfaces as they are always used directly by other modules. - - This can be achieved by placing an additional `default.nix` into the root of the ClanModules directory as shown: - - ```sh - # ModuleA - β”œβ”€β”€ README.md - β”œβ”€β”€ default.nix - └── roles - └── default.nix - ``` - - ```nix title="default.nix" - {...}:{ - imports = [ ./roles/default.nix ]; - } - ``` - - By utilizing this pattern the module (`moduleA`) can then be imported into any regular NixOS module via: - - ```nix - {...}:{ - imports = [ clanModules.moduleA ]; - } - ``` - -## Adding configuration options - -While we recommend to keep the interface as minimal as possible and deriving all required information from the `roles` model it might sometimes be required or convenient to expose customization options beyond `roles`. - -The following shows how to add options to your module. - -**It is important to understand that every module has its own namespace where it should declare options** - -**`clan.{moduleName}`** - -???+ Example - The following example shows how to register options in the module interface - - and how it can be set via the inventory - - - ```nix title="/default.nix" - custom-module = ./modules/custom-module; - ``` - - Since the module is called `custom-module` all of its exposed options should be added to `options.clan.custom-module.*...*` - - ```nix title="custom-module/roles/default.nix" - { - options = { - clan.custom-module.foo = mkOption { - type = types.str; - default = "bar"; - }; - }; - } - ``` - - If the module is [registered](#registering-the-module). - Configuration can be set as follows. - - ```nix title="flake.nix" - # Sometimes this attribute set is defined in clan.nix - clan-core.lib.clan { - inventory.services = { - custom-module.instance_1 = { - roles.default.machines = [ "machineA" ]; - roles.default.config = { - # All configuration here is scoped to `clan.custom-module` - foo = "foobar"; - }; - }; - }; - } - ``` - -## Organizing the ClanModule - -Each `{role}.nix` is included into the machine if the machine is declared to have the role. - -For example - -```nix -roles.client.machines = ["MachineA"]; -``` - -Then `roles/client.nix` will be added to the machine `MachineA`. - -This behavior makes it possible to split the interface and common code paths when using multiple roles. -In the concrete example of `borgbackup` this allows a `server` to declare a different interface than the corresponding `client`. - -The client offers configuration option, to exclude certain local directories from being backed up: - -```nix title="roles/client.nix" -# Example client interface - options.clan.borgbackup.exclude = ... -``` - -The server doesn't offer any configuration option. Because everything is set-up automatically. - -```nix title="roles/server.nix" -# Example server interface - options.clan.borgbackup = {}; -``` - -Assuming that there is a common code path or a common interface between `server` and `client` this can be structured as: - -```nix title="roles/server.nix, roles/client.nix" -{...}: { - # ... - imports = [ ../common.nix ]; -} -``` diff --git a/docs/site/developer/index.md b/docs/site/developer/index.md deleted file mode 100644 index cbf897802..000000000 --- a/docs/site/developer/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Developer Documentation - -!!! Danger - This documentation is **not** intended for external users. It may contain low-level details and internal-only interfaces.* - -Welcome to the internal developer documentation. - -This section is intended for contributors, engineers, and internal stakeholders working directly with our system, tooling, and APIs. It provides a technical overview of core components, internal APIs, conventions, and patterns that support the platform. - -Our goal is to make the internal workings of the system **transparent, discoverable, and consistent** β€” helping you contribute confidently, troubleshoot effectively, and build faster. - -## What's Here? - -!!! note "docs migration ongoing" - -- [ ] **API Reference**: 🚧🚧🚧 Detailed documentation of internal API functions, inputs, and expected outputs. 🚧🚧🚧 -- [ ] **System Concepts**: Architectural overviews and domain-specific guides. -- [ ] **Development Guides**: How to test, extend, or integrate with key components. -- [ ] **Design Notes**: Rationales behind major design decisions or patterns. - -## Who is This For? - -* Developers contributing to the platform -* Engineers debugging or extending internal systems -* Anyone needing to understand **how** and **why** things work under the hood diff --git a/docs/site/guides/clanServices.md b/docs/site/guides/clanServices.md index 94df37f01..88f3a4962 100644 --- a/docs/site/guides/clanServices.md +++ b/docs/site/guides/clanServices.md @@ -138,7 +138,7 @@ You can use services exposed by Clan’s core module library, `clan-core`. You can also author your own `clanService` modules. -πŸ”— Learn how to write your own service: [Authoring a clanService](../developer/extensions/clanServices/index.md) +πŸ”— Learn how to write your own service: [Authoring a service](../guides/services/community.md) You might expose your service module from your flake β€” this makes it easy for other people to also use your module in their clan. @@ -154,6 +154,6 @@ You might expose your service module from your flake β€” this makes it easy for ## What’s Next? -* [Author your own clanService β†’](../developer/extensions/clanServices/index.md) +* [Author your own clanService β†’](../guides/services/community.md) * [Migrate from clanModules β†’](../guides/migrations/migrate-inventory-services.md) diff --git a/docs/site/developer/contributing/CONTRIBUTING.md b/docs/site/guides/contributing/CONTRIBUTING.md similarity index 100% rename from docs/site/developer/contributing/CONTRIBUTING.md rename to docs/site/guides/contributing/CONTRIBUTING.md diff --git a/docs/site/developer/contributing/debugging.md b/docs/site/guides/contributing/debugging.md similarity index 100% rename from docs/site/developer/contributing/debugging.md rename to docs/site/guides/contributing/debugging.md diff --git a/docs/site/developer/contributing/testing.md b/docs/site/guides/contributing/testing.md similarity index 100% rename from docs/site/developer/contributing/testing.md rename to docs/site/guides/contributing/testing.md diff --git a/docs/site/developer/extensions/templates/disk/disko-templates.md b/docs/site/guides/disko-templates/community.md similarity index 100% rename from docs/site/developer/extensions/templates/disk/disko-templates.md rename to docs/site/guides/disko-templates/community.md diff --git a/docs/site/guides/flake-parts.md b/docs/site/guides/flake-parts.md index 6a3c8bf04..7fd87da1b 100644 --- a/docs/site/guides/flake-parts.md +++ b/docs/site/guides/flake-parts.md @@ -27,7 +27,7 @@ inputs = { ## Import the Clan flake-parts Module -After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](../reference/nix-api/clan.md) available within `mkFlake`. +After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](../options.md) available within `mkFlake`. ```nix { diff --git a/docs/site/guides/getting-started/add-machines.md b/docs/site/guides/getting-started/add-machines.md index 5cf0ee197..b3d93ad29 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/guides/getting-started/add-machines.md @@ -6,7 +6,7 @@ Machines can be added using the following methods - Editing machines/`machine_name`/configuration.nix (automatically included if it exists) - `clan machines create` (imperative) -See the complete [list](../../guides/more-machines.md#automatic-registration) of auto-loaded files. +See the complete [list](../../concepts/autoincludes.md) of auto-loaded files. ## Create a machine diff --git a/docs/site/guides/getting-started/add-services.md b/docs/site/guides/getting-started/add-services.md index 5052f3dbd..8c561059c 100644 --- a/docs/site/guides/getting-started/add-services.md +++ b/docs/site/guides/getting-started/add-services.md @@ -41,7 +41,7 @@ To learn more: [Guide about clanService](../clanServices.md) ``` 1. See [reference/clanServices](../../reference/clanServices/index.md) for all available services and how to configure them. - Or read [authoring/clanServices](../../developer/extensions/clanServices/index.md) if you want to bring your own + Or read [authoring/clanServices](../../guides/services/community.md) if you want to bring your own 2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine. diff --git a/docs/site/guides/macos.md b/docs/site/guides/macos.md index 0eccbca58..fce5ac2dd 100644 --- a/docs/site/guides/macos.md +++ b/docs/site/guides/macos.md @@ -7,7 +7,7 @@ This guide explains how to manage macOS machines using Clan. Currently, Clan supports the following features for macOS: - `clan machines update` for existing [nix-darwin](https://github.com/nix-darwin/nix-darwin) installations -- Support for [vars](../guides/vars-backend.md) +- Support for [vars](../concepts/generators.md) ## Add Your Machine to Your Clan Flake diff --git a/docs/site/guides/migrations/migrate-inventory-services.md b/docs/site/guides/migrations/migrate-inventory-services.md index ebeaa35d8..94716316c 100644 --- a/docs/site/guides/migrations/migrate-inventory-services.md +++ b/docs/site/guides/migrations/migrate-inventory-services.md @@ -1,7 +1,7 @@ # Migrating from using `clanModules` to `clanServices` **Audience**: This is a guide for **people using `clanModules`**. -If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../../developer/extensions/clanServices/index.md) +If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../../guides/services/community.md) ## What's Changing? @@ -329,6 +329,6 @@ instances = { ## Further reference -* [Authoring a 'clan.service' module](../../developer/extensions/clanServices/index.md) +* [Inventory Concept](../../concepts/inventory.md) +* [Authoring a 'clan.service' module](../../guides/services/community.md) * [ClanServices](../clanServices.md) -* [Inventory Reference](../../reference/nix-api/inventory.md) diff --git a/docs/site/guides/migrations/migration-facts-vars.md b/docs/site/guides/migrations/migration-facts-vars.md index 14e24aad7..6dcde4dbe 100644 --- a/docs/site/guides/migrations/migration-facts-vars.md +++ b/docs/site/guides/migrations/migration-facts-vars.md @@ -3,7 +3,7 @@ For a high level overview about `vars` see our [blog post](https://clan.lol/blog/vars/). This guide will help you migrate your modules that still use our [`facts`](../../guides/secrets.md) backend -to the [`vars`](../../guides/vars-backend.md) backend. +to the [`vars`](../../concepts/generators.md) backend. The `vars` [module](../../reference/clan.core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync. diff --git a/docs/site/guides/more-machines.md b/docs/site/guides/more-machines.md deleted file mode 100644 index 5ce064626..000000000 --- a/docs/site/guides/more-machines.md +++ /dev/null @@ -1,50 +0,0 @@ - -Clan has two general methods of adding machines: - -- **Automatic**: Detects every folder in the `machines` folder. -- **Declarative**: Explicit declarations in Nix. - -## Automatic registration - -Every folder `machines/{machineName}` will be registered automatically as a Clan machine. - -!!! info "Automatically loaded files" - - The following files are loaded automatically for each Clan machine: - - - [x] `machines/{machineName}/configuration.nix` - - [x] `machines/{machineName}/hardware-configuration.nix` - - [x] `machines/{machineName}/facter.json` Automatically configured, for further information see [nixos-facter](https://clan.lol/blog/nixos-facter/) - - [x] `machines/{machineName}/disko.nix` Automatically loaded, for further information see the [disko docs](https://github.com/nix-community/disko/blob/master/docs/quickstart.md). - -## Manual declaration - -Machines can be added via [`clan.inventory.machines`](../guides/inventory.md) or in `clan.machines`, which allows for defining NixOS options. - -=== "**Individual Machine Configuration**" - - ```{.nix} - clan-core.lib.clan { - machines = { - "jon" = { - # Any valid nixos config - }; - }; - } - ``` - -=== "**Inventory Configuration**" - - ```{.nix} - clan-core.lib.clan { - inventory = { - machines = { - "jon" = { - # Inventory can set tags and other metadata - tags = [ "zone1" ]; - deploy.targetHost = "root@jon"; - }; - }; - }; - } - ``` diff --git a/docs/site/guides/secrets.md b/docs/site/guides/secrets.md index 4f3faee9b..4c78f0f0b 100644 --- a/docs/site/guides/secrets.md +++ b/docs/site/guides/secrets.md @@ -1,5 +1,5 @@ -This article provides an overview over the underlying secrets system which is used by [Vars](../guides/vars-backend.md). -Under most circumstances you should use [Vars](../guides/vars-backend.md) directly instead. +This article provides an overview over the underlying secrets system which is used by [Vars](../concepts/generators.md). +Under most circumstances you should use [Vars](../concepts/generators.md) directly instead. Consider using `clan secrets` only for managing admin users and groups, as well as a debugging tool. diff --git a/docs/site/developer/extensions/clanServices/index.md b/docs/site/guides/services/community.md similarity index 93% rename from docs/site/developer/extensions/clanServices/index.md rename to docs/site/guides/services/community.md index 3f0ab86b3..fa92d008f 100644 --- a/docs/site/developer/extensions/clanServices/index.md +++ b/docs/site/guides/services/community.md @@ -1,16 +1,16 @@ # Authoring a 'clan.service' module !!! Tip - This is the successor format to the older [clanModules](../clanModules/index.md) + This is the successor format to the older [clanModules](../../reference/clanModules/index.md) While some features might still be missing we recommend to adapt this format early and give feedback. ## Service Module Specification This section explains how to author a clan service module. -We discussed the initial architecture in [01-clan-service-modules](../../../decisions/01-ClanModules.md) and decided to rework the format. +We discussed the initial architecture in [01-clan-service-modules](../../decisions/01-ClanModules.md) and decided to rework the format. -For the full specification and current state see: **[Service Author Reference](../../../reference/clanServices/clan-service-author-interface.md)** +For the full specification and current state see: **[Service Author Reference](../../reference/clanServices/clan-service-author-interface.md)** ### A Minimal module @@ -52,7 +52,7 @@ The imported module file must fulfill at least the following requirements: } ``` -For more attributes see: **[Service Author Reference](../../../reference/clanServices/clan-service-author-interface.md)** +For more attributes see: **[Service Author Reference](../../reference/clanServices/clan-service-author-interface.md)** ### Adding functionality to the module @@ -266,6 +266,6 @@ The benefit of this approach is that downstream users can override the value of ## Further -- [Reference Documentation for Service Authors](../../../reference/clanServices/clan-service-author-interface.md) -- [Migration Guide from ClanModules to ClanServices](../../../guides/migrations/migrate-inventory-services.md) -- [Decision that lead to ClanServices](../../../decisions/01-ClanModules.md) +- [Reference Documentation for Service Authors](../../reference/clanServices/clan-service-author-interface.md) +- [Migration Guide from ClanModules to ClanServices](../../guides/migrations/migrate-inventory-services.md) +- [Decision that lead to ClanServices](../../decisions/01-ClanModules.md) diff --git a/docs/site/index.md b/docs/site/index.md index 178bcaa36..44081b7a9 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -28,47 +28,49 @@ services](./guides/clanServices.md) tailored to your specific needs.
-- [Adding more machines](./guides/more-machines.md) +- [Create a Machine](./guides/getting-started/add-machines.md) --- - Learn how Clan automatically includes machines and Nix files. + How to create your first machine -- [Vars Backend](./guides/vars-backend.md) +- [macOS](./guides/macos.md) --- - Learn how to manage secrets with vars. + How to manage macOS machines with nix-darwin -- [Inventory](./guides/inventory.md) +- [Contribute](./guides/contributing/CONTRIBUTING.md) --- - Clan's declaration format for running **services** on one or multiple **machines**. + How to set up a development environment -- [Flake-parts](./guides/flake-parts.md) +
+ +## Concepts + +Explore the foundational ideas. + +
+ +- [Generators](./concepts/generators.md) --- - Use Clan with [https://flake.parts/]() + Learn about Generators -- [Contribute](./developer/contributing/CONTRIBUTING.md) +- [Inventory](./concepts/inventory.md) --- - Discover how to set up a development environment to contribute to Clan! - -- [macOS machines](./guides/macos.md) - - --- - - Manage macOS machines with nix-darwin + Learn about Inventory
## API Reference -**Reference API Documentation** +Technical reference for Clan's CLI and Nix modules
@@ -76,29 +78,22 @@ services](./guides/clanServices.md) tailored to your specific needs. --- - The `clan` CLI command + Command-line interface. + + Full reference for the `clan` CLI tool. - [Service Modules](./reference/clanServices/index.md) --- - An overview of available service modules + Overview of built-in service modules that provide composable functionality across machines. -- [Core](./reference/clan.core/index.md) +- [Core NixOS-module](./reference/clan.core/index.md) --- - The clan core nix module. - This is imported when using clan and is the basis of the extra functionality - that can be provided. - -- [(Legacy) Modules](./reference/clanModules/index.md) - - --- - - An overview of available clanModules - - !!! Example "These will be deprecated soon" + The foundation of Clan's functionality + Reference for the `clan-core` NixOS module β€” automatically part of any machine to enable Clan's core features.
diff --git a/docs/site/reference/index.md b/docs/site/reference/index.md index bb08355a8..c5c0eda8f 100644 --- a/docs/site/reference/index.md +++ b/docs/site/reference/index.md @@ -4,10 +4,10 @@ This section of the site provides an overview of available options and commands --- +- [Clan Configuration Option](../options.md) - for defining a Clan - Learn how to use the [Clan CLI](./cli/index.md) - Explore available services and application [modules](./clanModules/index.md) -- Discover [configuration options](./clan.core/index.md) that manage essential features -- Find descriptions of the [Nix interfaces](./nix-api/clan.md) for defining a Clan +- [NixOS Configuration Options](./clan.core/index.md) - Additional options avilable on a NixOS machine. --- diff --git a/lib/modules/inventoryClass/interface.nix b/lib/modules/inventoryClass/interface.nix index 9dd43d467..f3a7508bd 100644 --- a/lib/modules/inventoryClass/interface.nix +++ b/lib/modules/inventoryClass/interface.nix @@ -142,7 +142,7 @@ in - The module MUST have at least `features = [ "inventory" ]` in the frontmatter section. - The module MUST have a subfolder `roles` with at least one `{roleName}.nix` file. - For further information see: [Module Authoring Guide](../../developer/extensions/clanServices/index.md). + For further information see: [Module Authoring Guide](../../guides/services/community.md). ???+ example ```nix @@ -179,8 +179,7 @@ in map (m: "'${m}'") (lib.attrNames (lib.filterAttrs (n: _v: !builtins.elem n allowedNames) moduleSet)) )} - See: https://docs.clan.lol/developer/extensions/clanServices/ - And: https://docs.clan.lol/developer/extensions/clanServices/ + See: https://docs.clan.lol/guides/services/community/ '' moduleSet; }; diff --git a/nixosModules/clanCore/outputs.nix b/nixosModules/clanCore/outputs.nix index 9104926ae..20d549a2b 100644 --- a/nixosModules/clanCore/outputs.nix +++ b/nixosModules/clanCore/outputs.nix @@ -31,6 +31,7 @@ The deployment data is now accessed directly from the configuration instead of being written to a separate JSON file. ''; + defaultText = "error: deployment.json file generation has been removed in favor of direct selectors."; }; deployment.buildHost = lib.mkOption { type = lib.types.nullOr lib.types.str; @@ -54,10 +55,10 @@ deployment.nixosMobileWorkaround = lib.mkOption { type = lib.types.bool; description = '' - if true, the deployment will first do a nixos-rebuild switch + if true, the deployment will first do a nixos-rebuild switch to register the boot profile the command will fail applying it to the running system - which is why afterwards we execute a nixos-rebuild test to apply - the new config without having to reboot. + which is why afterwards we execute a nixos-rebuild test to apply + the new config without having to reboot. This is a nixos-mobile deployment bug and will be removed in the future ''; default = false;