clan/clan-core
12
4
Fork 19
Code Issues 108 Pull Requests 2 Actions Packages Projects 1 Releases Wiki Activity

docs: add reference index pages

Browse Source 
- add index pages for each reference documentation category
- move concepts pages into the reference hierarchy
- render clanModules overview page in the style of the CLI overview
This commit is contained in:
Valentin Gagarin 2024-07-12 19:02:19 -04:00 committed by Johannes Kirschbauer
parent 3a3f8e0756
commit 13b8b949f9
Signed by: hsjobeki
SSH Key Fingerprint: SHA256:vX3utDqig7Ph5L0JPv87ZTPb/w7cMzREKVZzzLFg9qU
10 changed files with 182 additions and 267 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/.gitignore vendored
View File

@ -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

11
docs/mkdocs.yml
View File

@ -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

46
docs/nix/scripts/renderOptions.py
View File

@ -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 += '<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)
@ -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 += "</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()

56
docs/site/concepts/configuration.md
View File

@ -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 )`

206
docs/site/concepts/inventory.md
View File

@ -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.<serviceName>.<instanceName>.config`
- Per machine configuration via `services.<serviceName>.<instanceName>.machines.<machineName>.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
```

26
docs/site/getting-started/configure.md
View File

@ -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:

8
docs/site/reference/index.md Normal file
View File

@ -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

29
docs/site/reference/nix-api/buildclan.md Normal file
View File

@ -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 )`

6
docs/site/reference/nix-api/index.md Normal file
View File

@ -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.

57
docs/site/reference/nix-api/inventory.md Normal file
View File

@ -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
}
}
```