From 21f87f169ac659045993b0320207c3e0266d3e96 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Fri, 16 May 2025 13:56:33 +0200 Subject: [PATCH] Docs: improve clanService docs --- clanServices/hello-world/default.nix | 12 ----- docs/mkdocs.yml | 2 + docs/nix/render_options/__init__.py | 43 ++++++++++++++++ docs/site/guides/clanServices.md | 76 ++++++++++++++++++++++++++++ 4 files changed, 121 insertions(+), 12 deletions(-) create mode 100644 docs/site/guides/clanServices.md diff --git a/clanServices/hello-world/default.nix b/clanServices/hello-world/default.nix index fca39d13d..15e53a7b3 100644 --- a/clanServices/hello-world/default.nix +++ b/clanServices/hello-world/default.nix @@ -5,18 +5,6 @@ manifest.name = "clan-core/hello-word"; manifest.description = "This is a test"; - roles.test = { - interface = - { lib, ... }: - { - options.foo = lib.mkOption { - type = lib.types.str; - # default = ""; - description = "Some option"; - }; - }; - }; - roles.peer = { interface = { lib, ... }: diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 19c931449..bc5a99ce8 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -54,6 +54,7 @@ nav: - Deploy Machine: getting-started/deploy.md - Continuous Integration: getting-started/check.md - Guides: + - clanServices: guides/clanServices.md - Disk Encryption: getting-started/disk-encryption.md - Mesh VPN: getting-started/mesh-vpn.md - Backup & Restore: getting-started/backups.md @@ -86,6 +87,7 @@ nav: - 03-adr-numbering-process: decisions/03-adr-numbering-process.md - Template: decisions/_template.md - Clan Services: + - reference/clanServices/index.md - reference/clanServices/admin.md - reference/clanServices/hello-world.md - reference/clanServices/wifi.md diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index 57f56c280..1451ef24b 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -438,6 +438,33 @@ def produce_clan_service_docs() -> None: msg = f"Environment variables are not set correctly: $out={OUT}" raise ClanError(msg) + indexfile = Path(OUT) / "clanServices/index.md" + indexfile.parent.mkdir( + parents=True, + exist_ok=True, + ) + index = "# Clan Services\n\n" + index += """ +**`clanServices`** are modular building blocks that simplify the configuration and orchestration of multi-host services. + +Each `clanService`: + +* Is a module of class **`clan.service`** +* Can define **roles** (e.g., `client`, `server`) +* Uses **`inventory.instances`** to configure where and how it is deployed +* Replaces the legacy `clanModules` and `inventory.services` system altogether + +!!! Note + `clanServices` are part of Clan's next-generation service model and are intended to replace `clanModules`. + + See [Migration Guide](../../guides/migrate-inventory-services.md) for help on migrating. + +Learn how to use `clanServices` in practice in the [Using clanServices guide](../../guides/clanServices.md). +""" + + with indexfile.open("w") as of: + of.write(index) + with Path(CLAN_MODULES_VIA_SERVICE).open() as f3: service_links: dict[str, dict[str, dict[str, Any]]] = json.load(f3) @@ -527,6 +554,22 @@ def produce_clan_modules_docs() -> None: if frontmatter.description: output += f"*{frontmatter.description}*\n\n" + # 2. Deprecation note if the module is deprecated + if "deprecated" in frontmatter.features: + output += f""" +!!! Warning "Deprecated" + The `{module_name}` module is deprecated.* + + Use: [clanServices/{module_name}](../clanServices/{module_name}.md) instead +""" + else: + output += f""" +!!! Warning "Will be deprecated" + The `{module_name}` module might eventually be migrated to 'clanServices'* + + See: [clanServices](../../guides/clanServices.md) +""" + # 3. Categories from README.md output += "## Categories\n\n" output += render_categories(frontmatter.categories, frontmatter.categories_info) diff --git a/docs/site/guides/clanServices.md b/docs/site/guides/clanServices.md new file mode 100644 index 000000000..fb1cd2f88 --- /dev/null +++ b/docs/site/guides/clanServices.md @@ -0,0 +1,76 @@ +# Using `clanServices` + +Clanโ€™s `clanServices` system is a composable way to define and deploy services across machines. It replaces the legacy `clanModules` approach and introduces better structure, flexibility, and reuse. + +This guide shows how to **instantiate** a `clanService`, explains how service definitions are structured in your inventory, and how to pick or create services from modules exposed by flakes. + +--- + +## Overview + +A `clanService` is used in: + +```nix +inventory.instances. +``` + +Each instance includes a reference to a **module specification** โ€” this is how Clan knows which service module to use and where it came from. +You can reference services from any flake input, allowing you to compose services from multiple flake sources. + +--- + +## Basic Example + +Example of instantiating a `borgbackup` service using `clan-core`: + +```nix +inventory.instances = { + # Arbitrary unique name for this 'borgbackup' instance + borgbackup-example = { + module = { + name = "borgbackup"; # <-- Name of the module + input = "clan-core"; # <-- The flake input where the service is defined + }; + # Participation of the machines is defined via roles + roles.client.machines."machine-a" = {}; + roles.server.machines."backup-host" = {}; + }; +} +``` + +If you used `clan-core` as an input attribute for your flake: + +```nix + # โ†“ module.input = "clan-core" +inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core" +``` + +## Picking a clanService + +You can use services exposed by Clanโ€™s core module library, `clan-core`. + +๐Ÿ”— See: [List of Available Services in clan-core](../reference/clanServices/index.md) + +## Defining Your Own Service + +You can also author your own `clanService` modules. + +๐Ÿ”— Learn how to write your own service: [Authoring a clanService](../authoring/clanServices/index.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. + +--- + +## ๐Ÿ’ก Tips for Working with clanServices + +* You can add multiple inputs to your flake (`clan-core`, `your-org-modules`, etc.) to mix and match services. +* Each service instance is isolated by its key in `inventory.instances`, allowing you to deploy multiple versions or roles of the same service type. +* Roles can target different machines or be scoped dynamically. + +--- + +## Whatโ€™s Next? + +* [Author your own clanService โ†’](../authoring/clanServices/index.md) +* [Migrate from clanModules โ†’](../guides/migrate-inventory-services.md) +