Authoring a clanModule
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.
Under construction
Note
Currently ClanModules should be contributed to the clan-core repository via a PR.
Ad-hoc loading of custom modules is not recommended / supported yet.
Bootstrapping the clanModule
A ClanModule is a specific subset of a NixOS Module, but it has some constraints and might be used via the Inventory 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:
# Example: borgbackup
clanModules/borgbackup
├── README.md
└── roles
├── client.nix
└── server.nix
Tip
README.md
is always required. See section Readme for further details.
The roles
folder is strictly required for features = [ "inventory" ]
.
The clanModule must be registered via the clanModules
attribute in clan-core
{ ... }:
{
flake.clanModules = {
admin = ./admin;
borgbackup = ./borgbackup;
borgbackup-static = ./borgbackup-static;
# Register your new module here
# ...
Readme
The README.md
is a required file for all modules. It MUST contain frontmatter in toml
format.
See the frontmatter reference for 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
Adds the roles: client
and server
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 inventory modules. 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:
By utilizing this pattern the module (moduleA
) can then be imported into any regular NixOS module via:
Organizing the ClanModule
Each {role}.nix
is included into the machine if the machine is declared to have the role.
For example
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:
The server doesn't offer any configuration option. Because everything is set-up automatically.
Assuming that there is a common code path or a common interface between server
and client
this can be structured as:
Frontmatter Reference
description
(RequiredString
)- Short description of the module
categories
(Optional[ String ]
)-
default
[ "Uncategorized" ]
Categories are used for Grouping and searching.
While initial oriented on freedesktop the following categories are allowed
- AudioVideo
- Audio
- Video
- Development
- Education
- Game
- Graphics
- Social
- Network
- Office
- Science
- System
- Settings
- Utility
- Uncategorized
features
(Optional[ String ]
)-
default
[]
Clans Features that the module implements support for.
Available feature flags are:
inventory
Important
Every ClanModule, that specifies
features = [ "inventory" ]
MUST have at least one role. Many modules useroles/default.nix
which registers the roledefault
.If you are a clan module author and your module has only one role where you cannot determine the name, then we would like you to follow the convention.