nixos-config/docs/content/en-US/03-project-specific-setup/01-declarative-host-management/index.adoc

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

This project uses a custom setup for declarative host management.
It is a custom github:hercules-ci/flake-parts[opts=repo] module that allows you to easily initialize NixOS systems of multiple platforms (with multiple images output) while making it purely-built as much as possible.

This custom flake-parts modules integrates the following projects:

* It automatically adds github:serokell/deploy-rs[opts=repo] nodes ready to be deployed with `deploy` CLI tool when given the right parameters.
* Mandatory inclusion of github:nix-community/home-manager[opts=repo].
* Image output generation made easy with github:nix-community/nixos-generators[opts=repo].

Each of the declared hosts are then exported either as part of the `images` or `nixosConfigurations` (or both) flake output attribute.
The `images` flake output attribute contains a per-system set of packages of the NixOS systems as the indicated package format.
For example, you can build my personalized NixOS installer ISO with the following command.

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

The following code listing is an example of a declarative NixOS setup.
It should have the following effects in the flake output:

* Two additional NixOS configurations to be deployed at `nixosConfigurations.plover-{x86_64-linux,aarch64-linux}`.
By default, declarative NixOS setups are not added automatically to `nixosConfigurations` output unless we have `configs.<config>.formats = null;` but we did configure `configs.<config>.deploy` so that makes it even.

* Four additional derivations added in `images` flake output (since there's 2 formats and 2 platforms) at `images.{x86_64-linux,aarch64-linux}.plover-{do,gce}`.

[#lst:images-metadata-example]
[source, nix]
----
{
  setups.nixos.configs.plover = {
    systems = [ "x86_64-linux" "aarch64-linux" ];
    formats = [ "do" "gce" ];
    domain = "foodogsquared.one";
    nixpkgsBranch = "nixos-unstable-small";
    homeManagerBranch = "home-manager-unstable";
    modules = [
      ({ config, lib, ... }: {
        services.foo.enable = true;
      })
    ];
    overlays = [
      inputs.neovim-nightly-overlay.overlays.default
    ];
    deploy = {
      fastConnection = true;
      autoRollback = true;
      magicRollback = true;
      remoteBuild = true;
      profiles = os: {
        system = {
          sshUser = "root";
          user = "admin";
          path = inputs.deploy.lib.${os.system}.activate.nixos os.config;
        };
      };
    };
  };
}
----