---
title: Declarative host management
---
= Declarative host management

This project uses a custom setup for declarative host management.
Specifically, it is done with a simple file at github:{github-repo}[`./images.toml`, path=./images.toml, rev=master] where it expects a table of the hosts' metadata.
Each host in the table represents one of the hosts at github:{github-repo}[`./hosts/`, path=./hosts/, rev=master].

Each of declared hosts are then exported as part of the `images` flake output attribute where each is a derivation for building them as an image output.
For example, you can build my personalized NixOS installer ISO with the following command.

[source, shell, subs=attributes]
----
nix build {canonical-flake-url}#images.bootstrap
----

A host metadata has a certain schema which the following example is a complete version of it.
The data is then used for certain functions in the flake definition file (i.e., `flake.nix`).

[#lst:images-metadata-example]
[source, toml]
----
[plover]
system = "x86_64-linux"
format = "iso"
hostname = "ploverrific"
domain = "foodogsquared.one"
nixpkgs-channel = "nixos-unstable-small"

[plover.deploy]
hostname = "plover.foodogsquared.one"
ssh-user = "admin"
fast-connection = true
auto-rollback = true
magic-rollback = true
remote-build = true
----

For a complete reference, here are the expected attributes.

- `system` contains the platform of the host system.
This is mainly used to indicate the platform used for the nixpkgs repository.

- `format` is the image output format for the host.
It expects an accepted value from github:nix-community/nixos-generators[opts=repo] project.

- `hostname` is the canonical hostname for the host.
If unset, the hostname is the name of the table key.
In the <<lst:images-metadata-example, previous example>>, if `plover.hostname` is unset, the value would be `plover` instead of `ploverrific`.

- `domain` is the domain used for networking configuration.
It is set for `networking.domain` in NixOS configuration.

- `nixpkgs-channel` is the nixpkgs channel to be used for the host.
The value could be any one of the nixpkgs flake inputs imported into this flake.
By default, it uses `nixpkgs` flake input which points to the `nixos-unstable` channel.

- `deploy` is a table containing arguments from github:serokell/deploy-rs[opts=repo].
Only a few arguments are accepted (i.e., `hostname`, `fast-connection`, `remote-build`, `magic-rollback`, and `auto-rollback`).

Take note only certain hosts can be considered as a NixOS configuration (e.g., `nixosConfigurations`).
Specifically, those images with a format of `iso` and those without (since they fall back to `iso` anyways).
Otherwise, most images are intended to be built.
footnote:[Though, one could create a custom activation and deployment script with deploy-rs.]

Furthermore, those imported NixOS configurations are also exported as part of the deploy nodes for deploy-rs with the `nixos` prefix.
For example, here's the command to deploy my Plover server.

[source, shell, subs=attributes]
----
deploy {canonical-flake-url}#nixos-plover
----