headplane/docs/Nix.md

# Nix

[flake.nix](https://github.com/tale/headplane/blob/main/flake.nix) provided:
```sh
$ nix flake show github:tale/headplane --all-systems
github:tale/headplane/ec6d455461955242393b60d9ce60c5123fa9784f?narHash=sha256-CM/vXzUiOed7i1Pp15KyV4FuIvumRlXnpF33dSWZZH4%3D
├───checks
│   ├───aarch64-darwin
│   │   └───default: derivation 'headplane-with-agent'
│   ├───x86_64-darwin
│   │   └───default: derivation 'headplane-with-agent'
│   └───x86_64-linux
│       └───default: derivation 'headplane-with-agent'
├───devShells
│   ├───aarch64-darwin
│   │   └───default: development environment 'headplane'
│   ├───x86_64-darwin
│   │   └───default: development environment 'headplane'
│   └───x86_64-linux
│       └───default: development environment 'headplane'
├───formatter
│   ├───aarch64-darwin: package 'alejandra-4.0.0'
│   ├───x86_64-darwin: package 'alejandra-4.0.0'
│   └───x86_64-linux: package 'alejandra-4.0.0'
├───nixosModules
│   └───headplane: NixOS module
├───overlays
│   └───default: Nixpkgs overlay
└───packages
    ├───aarch64-darwin
    │   ├───headplane: package 'headplane-0.6.1'
    │   ├───headplane-agent: package 'hp_agent-0.6.1'
    │   ├───headplane-nixos-docs: package 'headplane-nixos-docs.md'
    │   └───headplane-ssh-wasm: package 'headplane-ssh-wasm-0.6.1'
    ├───x86_64-darwin
    │   ├───headplane: package 'headplane-0.6.1'
    │   ├───headplane-agent: package 'hp_agent-0.6.1'
    │   ├───headplane-nixos-docs: package 'headplane-nixos-docs.md'
    │   └───headplane-ssh-wasm: package 'headplane-ssh-wasm-0.6.1'
    └───x86_64-linux
        ├───headplane: package 'headplane-0.6.1'
        ├───headplane-agent: package 'hp_agent-0.6.1'
        ├───headplane-nixos-docs: package 'headplane-nixos-docs.md'
        └───headplane-ssh-wasm: package 'headplane-ssh-wasm-0.6.1'
```

## NixOS module options
Defined as `services.headplane.*`, check the `./nix/` directory for details.\
The full (generated by `mise run nixos-docs`) list of `services.headplane.settings.*` options: [./NixOS-options.md](./NixOS-options.md)

## Usage
1. Add the `github:tale/headplane` flake input.
2. Import a default overlay to add `pkgs.headplane`.
3. Import NixOS module for `services.headplane.*`.

```nix
# Your flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    headplane = {
      url = "github:tale/headplane";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = {
    nixpkgs,
    headplane,
    ...
  }: {
    nixosConfigurations.MY_MACHINE = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        # provides `services.headplane.*` NixOS options.
        headplane.nixosModules.headplane
        {
          # provides `pkgs.headplane`
          nixpkgs.overlays = [ headplane.overlays.default ];
        }
        {
          {config, pkgs, ...}:
          let
            format = pkgs.formats.yaml {};

            # A workaround generate a valid Headscale config accepted by Headplane when `config_strict == true`.
            settings = lib.recursiveUpdate config.services.headscale.settings {
              tls_cert_path = "/dev/null";
              tls_key_path = "/dev/null";
              policy.path = "/dev/null";
            };

            headscaleConfig = format.generate "headscale.yml" settings;
          in {
            services.headplane = {
              enable = true;
              settings = {
                server = {
                  host = "127.0.0.1";
                  port = 3000;
                  # Using `sops-nix` as an example, can be a path to any file with a secret.
                  cookie_secret_path = config.sops.secrets."headplane/serverCookieSecret".path;
                };
                headscale = {
                  url = "https://example.com";
                  config_path = "${headscaleConfig}";
                };
                integration.agent = {
                  enabled = true;
                  # Using `sops-nix` as an example, can be a path to any file with a secret.
                  pre_authkey_path = config.sops.secrets."headplane/integrationAgentPreAuthkeyPath".path;
                };
                oidc = {
                  issuer = "https://oidc.example.com";
                  client_id = "headplane";
                  # Using `sops-nix` as an example, can be a path to any file with a secret.
                  client_secret_path = config.sops.secrets."headplane/oidcClientSecret".path;
                  disable_api_key_login = true;
                  # Might needed when integrating with Authelia.
                  token_endpoint_auth_method = "client_secret_basic";
                  # Using `sops-nix` as an example, can be a path to any file with a secret.
                  headscale_api_key_path = config.sops.secrets."headplane/oidcHeadscaleApiKey".path;
                  redirect_uri = "https://oidc.example.com/admin/oidc/callback";
                };
              };
            };
          }
        }
      ];
    };
  };
}
```