diff --git a/docs/.gitignore b/docs/.gitignore index 932a47563..128ca295b 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,3 +1,5 @@ -/site/reference +/site/reference/clan-core +/site/reference/clanModules +/site/reference/cli /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 e704599ec..8ae87c39f 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -48,11 +48,10 @@ nav: - Mesh VPN: getting-started/mesh-vpn.md - Backup & Restore: getting-started/backups.md - Flake-parts: getting-started/flake-parts.md - - Concepts: - - Configuration: concepts/configuration.md - - Inventory: concepts/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 @@ -77,13 +76,13 @@ nav: - reference/clanModules/zerotier-static-peers.md - reference/clanModules/zt-tcp-relay.md - CLI: + - reference/cli/index.md - reference/cli/backups.md - reference/cli/config.md - reference/cli/facts.md - reference/cli/flakes.md - reference/cli/flash.md - reference/cli/history.md - - reference/cli/index.md - reference/cli/machines.md - reference/cli/secrets.md - reference/cli/show.md @@ -98,6 +97,10 @@ nav: - 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 diff --git a/docs/nix/scripts/renderOptions.py b/docs/nix/scripts/renderOptions.py index 807cb12b7..323dbc528 100644 --- a/docs/nix/scripts/renderOptions.py +++ b/docs/nix/scripts/renderOptions.py @@ -220,6 +220,11 @@ def render_roles(roles: list[str] | None, module_name: str) -> str: 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( @@ -245,6 +250,12 @@ def produce_clan_modules_docs() -> None: # 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 += '
\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) @@ -254,6 +265,8 @@ def produce_clan_modules_docs() -> None: 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}...") @@ -282,6 +295,39 @@ def produce_clan_modules_docs() -> None: with open(outfile, "w") as of: of.write(output) + modules_index += "
" + 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() diff --git a/docs/site/concepts/configuration.md b/docs/site/concepts/configuration.md deleted file mode 100644 index 1ba0df378..000000000 --- a/docs/site/concepts/configuration.md +++ /dev/null @@ -1,56 +0,0 @@ -# Configuration - -## Introduction - -When managing machine configuration this can be done through many possible ways. -Ranging from writing `nix` expression in a `flake.nix` file; placing `autoincluded` files into your machine directory; or configuring everything in a simple UI (upcomming). - -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 - -## BuildClan - -The core function 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 )` diff --git a/docs/site/concepts/inventory.md b/docs/site/concepts/inventory.md deleted file mode 100644 index 6d966ab0e..000000000 --- a/docs/site/concepts/inventory.md +++ /dev/null @@ -1,206 +0,0 @@ -# Inventory - -`Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries. - -## Meta - -Metadata about the clan, will be displayed upfront in the upcomming clan-app, make sure to choose a unique name. - -```{.nix hl_lines="3-8"} -buildClan { - inventory = { - meta = { - # The following options are available - # name: string # Required, name of the clan. - # description: null | string - # icon: null | string - }; - }; -} -``` - -## Machines - -Machines and a small pieve of their configuration can be added via `inventory.machines`. - -!!! 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 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...config` -- Per machine configuration via `services...machines..config` - -### Configuration Examples - -!!! 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" ]; - }; - }; - }; - } - ``` - -!!! Example "Packages Example" - - This example shows how to add `pkgs.firefox` via the inventory interface. - - ```{.nix hl_lines="8-11"} - buildClan { - inventory = { - machines = { - "sara" = {}; - "jon" = {}; - }; - services = { - packages.set_1 = { - roles.default.machines = [ "jon" "sara" ]; - # Packages is a configuration option of the "packages" clanModule - config.packages = ["firefox"]; - }; - }; - }; - } - ``` - -### 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 = "default"` - -!!! Example "Tags Example" - - ```{.nix hl_lines="5 8 13"} - buildClan { - inventory = { - machines = { - "sara" = { - tags = ["browsing"]; - }; - "jon" = { - tags = ["browsing"]; - }; - }; - services = { - packages.set_1 = { - roles.default.tags = [ "browsing" ]; - config.packages = ["firefox"]; - }; - }; - }; - } - ``` - -### Multiple Service Instances - -!!! danger "Important" - Not all modules support multiple instances yet. - -Some modules have support for adding multiple instances of the same service in different roles or configurations. - -!!! 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" ]; - }; - }; - }; - } - ``` - -### Schema specification - -The complete schema specification can be retrieved via: - -```sh -nix build git+https://git.clan.lol/clan/clan-core#inventory-schema -> result -> ├── schema.cue -> └── schema.json -``` diff --git a/docs/site/getting-started/configure.md b/docs/site/getting-started/configure.md index 8f191d532..c06b25cf9 100644 --- a/docs/site/getting-started/configure.md +++ b/docs/site/getting-started/configure.md @@ -1,5 +1,31 @@ # 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: diff --git a/docs/site/reference/index.md b/docs/site/reference/index.md new file mode 100644 index 000000000..d9e1b00fd --- /dev/null +++ b/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 diff --git a/docs/site/reference/nix-api/buildclan.md b/docs/site/reference/nix-api/buildclan.md new file mode 100644 index 000000000..089e03f64 --- /dev/null +++ b/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 )` diff --git a/docs/site/reference/nix-api/index.md b/docs/site/reference/nix-api/index.md new file mode 100644 index 000000000..00e148b35 --- /dev/null +++ b/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. diff --git a/docs/site/reference/nix-api/inventory.md b/docs/site/reference/nix-api/inventory.md new file mode 100644 index 000000000..297a03927 --- /dev/null +++ b/docs/site/reference/nix-api/inventory.md @@ -0,0 +1,57 @@ +# Inventory + +`Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries. + +The following is the specification of the inventory in `cuelang` + +```cue +{ + 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: [string]: [string]: { + // Required meta fields + meta: { + name: string, + icon?: string + description?: string, + }, + // Machines are added via the avilable roles + // Membership depends only on this field + roles: [string]: { + machines: [...string], + tags: [...string], + } + machines?: { + [string]: { + config?: { + ... + } + } + }, + + // Global Configuration for the service + // Applied to all machines. + config?: { + // Schema depends on the module. + // It declares the interface how the service can be configured. + ... + } + } + // A map of machines, extends the machines of `buildClan` + machines: [string]: { + name: string, + description?: string, + icon?: string + tags: [...string] + system: string + } +} +```