Doc: add conceptual documentation
This commit is contained in:
parent
e6179ab829
commit
be71b17474
@ -14,6 +14,7 @@ markdown_extensions:
|
|||||||
- attr_list
|
- attr_list
|
||||||
- footnotes
|
- footnotes
|
||||||
- md_in_html
|
- md_in_html
|
||||||
|
- def_list
|
||||||
- meta
|
- meta
|
||||||
- plantuml_markdown
|
- plantuml_markdown
|
||||||
- pymdownx.emoji:
|
- pymdownx.emoji:
|
||||||
@ -49,6 +50,8 @@ nav:
|
|||||||
- Mesh VPN: getting-started/mesh-vpn.md
|
- Mesh VPN: getting-started/mesh-vpn.md
|
||||||
- Backup & Restore: getting-started/backups.md
|
- Backup & Restore: getting-started/backups.md
|
||||||
- Flake-parts: getting-started/flake-parts.md
|
- Flake-parts: getting-started/flake-parts.md
|
||||||
|
- Concepts:
|
||||||
|
- Configuration: concepts/configuration.md
|
||||||
- Reference:
|
- Reference:
|
||||||
- Clan Modules:
|
- Clan Modules:
|
||||||
- reference/clanModules/borgbackup-static.md
|
- reference/clanModules/borgbackup-static.md
|
||||||
|
114
docs/site/concepts/configuration.md
Normal file
114
docs/site/concepts/configuration.md
Normal file
@ -0,0 +1,114 @@
|
|||||||
|
# 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)
|
||||||
|
|
||||||
|
`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 )`
|
||||||
|
|
||||||
|
## 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
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
@ -1,4 +1,7 @@
|
|||||||
{
|
{
|
||||||
|
"meta": {
|
||||||
|
"name": "Minimal inventory"
|
||||||
|
},
|
||||||
"machines": {
|
"machines": {
|
||||||
"minimal-inventory-machine": {
|
"minimal-inventory-machine": {
|
||||||
"name": "foo",
|
"name": "foo",
|
||||||
|
@ -5,6 +5,7 @@ package schema
|
|||||||
description?: string,
|
description?: string,
|
||||||
icon?: string
|
icon?: string
|
||||||
tags: [...string]
|
tags: [...string]
|
||||||
|
system: string
|
||||||
}
|
}
|
||||||
|
|
||||||
#role: string
|
#role: string
|
||||||
|
Loading…
Reference in New Issue
Block a user