feat: add a nix flake (#132)

* feat: wip `nix` Add initial code to be used when working with `nix` and `NixOS`. * a Nix flake * building a package * a NixOS module * feat: build `hp_agent` with `nix` * feat: add `hp_agent` as a flake output * feat: nix: start `headplane` after `headscale` * feat: do not rely on `git` for versioning It causes lots of pain when building with `nix` for a local `flake.nix`. Not sure if it's a good general solution: * now it requires a manual step of updating `./version` on each release. * we're losing commit hash abbreviation, like `0.5.3-5-gbe5a291` I guess, this can be fixed by installing git-pre-commit-hook, but even then it'd be wrong, because the output of `git describe --tags --always` won't be the same before and after commit. * feat: include `hp_agent` to the NixOS module * fix: version error message * fix: use relative path imports in `nix` * fix: NixOS module: generate `/etc/headplane/config.yaml` from `services.headplane.settings` * fix: NixOS module: allow passing `bool` in `services.headplane.settings.*` * fix: NixOS module: fix `/etc/headplane/config.yaml` generation * docs: add Nix/NixOS docs * feat: nix: read version from `package.json` * fix: nix: fix `agent` env vars configuration * feat: nix: add `services.headplane.agent.debug` option * fix: delete unnecessary `version` file * fix: nix: remove unnecessary `sed` substitutions A left over from previous versions. See: https://github.com/tale/headplane/issues/95#issue-2807487849 * feat: nix: do not hardcode `headplane-agent` configuration environment variables To make the module more flexible and to reduce the dependency on the config API. * docs: improve `Nix` documentation * Reflect recent changes. * Link `Nix` in README * feat: nix: setup Nix CI * feat: nix: CI without depending on flakehub.com * chore: begin bundling all deps into the server * fix: loosen headscale config validation * fix: navigate back to machines page on node deletion * fix: slice off trailing slash if present on headscale url * feat: switch to a central singleton handler This also adds support for Headscale TLS installations * fix: shamefully-hoist dependencies * fix: handle localized number fields * fix: revert dependency bundling for now * chore: cleanup and remove from readme for now --------- Co-authored-by: Aarnav Tale <aarnavtale@icloud.com>
2025-03-18 05:31:37 +01:00 · 2025-03-18 05:31:37 +01:00 · 03a7e51384
commit 03a7e51384
parent 483f86c457
9 changed files with 492 additions and 0 deletions
--- a/.envrc
+++ b/.envrc
@ -0,0 +1 @@
+use_flake
--- a/.github/workflows/nix-update-lock.yaml
+++ b/.github/workflows/nix-update-lock.yaml
@ -0,0 +1,20 @@
+name: Update flake.lock
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * 0'
+ 
+jobs:
+  update-flake-inputs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/update-flake-lock@main
+        with:
+          pr-title: "chore: update flake.lock"
+          pr-labels: |
+            dependencies
+            automated
+      - uses: DeterminateSystems/flake-checker-action@main
+      - run: nix flake check --all-systems
--- a/.github/workflows/nix.yaml
+++ b/.github/workflows/nix.yaml
@ -0,0 +1,24 @@
+  name: 
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    tags:
+      - v?[0-9]+.[0-9]+.[0-9]+*
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+ 
+jobs:
+  nix-ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@main
+        with:
+          determinate: true
+      - uses: DeterminateSystems/flake-checker-action@main
+      - run: nix flake check --all-systems
--- a/docs/Nix.md
+++ b/docs/Nix.md
@ -0,0 +1,127 @@
+# Nix
+
+[flake.nix](../flake.nix) provided:
+```
+$ nix flake show . --all-systems
+git+file:///home/igor/personal/headplane?ref=refs/heads/nix&rev=2d78a95a0648a3778e114fb246ea436e96475d62
+├───devShell
+│   ├───aarch64-darwin: development environment 'headplane'
+│   ├───x86_64-darwin: development environment 'headplane'
+│   └───x86_64-linux: development environment 'headplane'
+├───formatter
+│   ├───aarch64-darwin: package 'alejandra-3.1.0'
+│   ├───x86_64-darwin: package 'alejandra-3.1.0'
+│   └───x86_64-linux: package 'alejandra-3.1.0'
+├───nixosModules
+│   └───headplane: NixOS module
+├───overlays
+│   └───default: Nixpkgs overlay
+└───packages
+    ├───aarch64-darwin
+    │   ├───headplane: package 'headplane-0.5.3-SNAPSHOT'
+    │   └───headplane-agent: package 'hp_agent-0.5.3-SNAPSHOT'
+    ├───x86_64-darwin
+    │   ├───headplane: package 'headplane-0.5.3-SNAPSHOT'
+    │   └───headplane-agent: package 'hp_agent-0.5.3-SNAPSHOT'
+    └───x86_64-linux
+        ├───headplane: package 'headplane-0.5.3-SNAPSHOT'
+        └───headplane-agent: package 'hp_agent-0.5.3-SNAPSHOT'
+```
+
+## NixOS module options
+Defined as `services.headplane.*`, check the `./nix/` directory for details.
+
+## Usage
+
+1. Add the `github:tale/headplane` flake input.
+2. Import a default overlay to add `pkgs.headplane` and `pkgs.headplane-agent`.
+3. Import NixOS module for `services.headplane.*`.
+
+```nix
+# Your flake.nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    headplane = {
+      url = "github:igor-ramazanov/headplane/nix";
+      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` and `pkgs.headplane-agent`.
+          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 {
+              acme_email = "/dev/null";
+              tls_cert_path = "/dev/null";
+              tls_key_path = "/dev/null";
+              policy.path = "/dev/null";
+              oidc.client_secret_path = "/dev/null";
+            };
+
+            headscaleConfig = format.generate "headscale.yml" settings;
+          in {
+            services.headplane = {
+              enable = true;
+              agent = {
+                # As an example only.
+                # Headplane Agent hasn't yet been ready at the moment of writing the doc.
+                enable = true;
+                settings = {
+                  HEADPLANE_AGENT_DEBUG = true;
+                  HEADPLANE_AGENT_HOSTNAME = "localhost";
+                  HEADPLANE_AGENT_TS_SERVER = "https://example.com";
+                  HEADPLANE_AGENT_TS_AUTHKEY = "xxxxxxxxxxxxxx";
+                  HEADPLANE_AGENT_HP_SERVER = "https://example.com/admin/dns";
+                  HEADPLANE_AGENT_HP_AUTHKEY = "xxxxxxxxxxxxxx";
+                };
+              };
+              settings = {
+                server = {
+                  host = "127.0.0.1";
+                  port = 3000;
+                  cookie_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
+                  cookie_secure = true;
+                };
+                headscale = {
+                  url = "https://example.com";
+                  config_path = "${headscaleConfig}";
+                  config_strict = true;
+                };
+                integration.proc.enabled = true;
+                oidc = {
+                  issuer = "https://oidc.example.com";
+                  client_id = "headplane";
+                  client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
+                  disable_api_key_login = true;
+                  # Might needed when integrating with Authelia.
+                  token_endpoint_auth_method = "client_secret_basic";
+                  headscale_api_key = "xxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
+                  redirect_uri = "https://oidc.example.com/admin/oidc/callback";
+                };
+              };
+            };
+          }
+        }
+      ];
+    };
+  };
+}
+```
--- a/flake.lock
+++ b/flake.lock
@ -0,0 +1,82 @@
+{
+  "nodes": {
+    "devshell": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1741473158,
+        "narHash": "sha256-kWNaq6wQUbUMlPgw8Y+9/9wP0F8SHkjy24/mN3UAppg=",
+        "owner": "numtide",
+        "repo": "devshell",
+        "rev": "7c9e793ebe66bcba8292989a68c0419b737a22a0",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "devshell",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1741646908,
+        "narHash": "sha256-55a1x5k+oFY2QCFjj7Mn5nPa8Do0shVl0m280mOAW/Q=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "ab0c5b18dab5e4b5d06ed679f8fd7cdc9970c4be",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devshell": "devshell",
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
--- a/flake.nix
+++ b/flake.nix
@ -0,0 +1,69 @@
+rec {
+  description = "headplane";
+
+  inputs = {
+    devshell = {
+      inputs.nixpkgs.follows = "nixpkgs";
+      url = "github:numtide/devshell";
+    };
+    flake-utils.url = "github:numtide/flake-utils";
+    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
+  };
+
+  outputs = {
+    devshell,
+    flake-utils,
+    nixpkgs,
+    ...
+  }:
+    flake-utils.lib.eachSystem [
+      "aarch64-darwin"
+      "x86_64-darwin"
+      "x86_64-linux"
+    ]
+    (system: let
+      pkgs = import nixpkgs {
+        inherit system;
+        overlays = [devshell.overlays.default];
+      };
+    in rec {
+      formatter = pkgs.alejandra;
+      packages = {
+        headplane = pkgs.callPackage ./nix/package.nix {};
+        headplane-agent = pkgs.callPackage ./nix/agent.nix {};
+      };
+      checks.default = pkgs.symlinkJoin {
+        name = "headplane-with-agent";
+        paths = [packages.headplane packages.headplane-agent];
+      };
+      devShells.default = pkgs.devshell.mkShell rec {
+        name = description;
+        motd = let
+          providedPackages = pkgs.lib.concatStringsSep "\n" (
+            pkgs.lib.map
+            (pkg: "\t* ${pkgs.lib.getName pkg}")
+            (pkgs.lib.reverseList packages)
+          );
+        in ''
+          Entered '${description}' development environment.
+
+          Provided packages:
+          ${providedPackages}
+        '';
+        packages = [
+          pkgs.go
+          pkgs.nodejs-slim_22
+          pkgs.pnpm_10
+          pkgs.typescript-language-server
+        ];
+        env = [];
+      };
+    })
+    // {
+      overlays.default = final: prev: {
+        headplane = final.callPackage ./nix/package.nix {};
+        headplane-agent = final.callPackage ./nix/agent.nix {};
+      };
+      nixosModules.headplane = import ./nix/module.nix;
+    };
+}
--- a/nix/agent.nix
+++ b/nix/agent.nix
@ -0,0 +1,9 @@
+{buildGoModule}:
+buildGoModule {
+  pname = "hp_agent";
+  version = (builtins.fromJSON (builtins.readFile ../package.json)).version;
+  src = ../.;
+  vendorHash = "sha256-G0kahv3mPTL/mxU2U+0IytJaFVPXMbMBktbLMfM0BO8=";
+  ldflags = ["-s" "-w"];
+  env.CGO_ENABLED = 0;
+}
--- a/nix/module.nix
+++ b/nix/module.nix
@ -0,0 +1,112 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}: let
+  inherit
+    (lib)
+    attrsToList
+    listToAttrs
+    map
+    mkEnableOption
+    mkIf
+    mkOption
+    mkPackageOption
+    typeOf
+    types
+    ;
+  cfg = config.services.headplane;
+  settingsFormat = pkgs.formats.yaml {};
+  settingsFile = settingsFormat.generate "headplane-config.yaml" cfg.settings;
+  agentEnv = listToAttrs (map (n: {
+    name = n.name;
+    value =
+      if ((typeOf n.value) == "bool")
+      then
+        (
+          if (n.value)
+          then "true"
+          else "false"
+        )
+      else n.value;
+  }) (attrsToList cfg.agent.settings));
+in {
+  options.services.headplane = {
+    enable = mkEnableOption "headplane";
+    package = mkPackageOption pkgs "headplane" {};
+
+    settings = mkOption {
+      type = types.submodule {
+        freeformType = settingsFormat.type;
+      };
+      default = {};
+      description = "Headplane config, generates a YAML config. See: https://github.com/tale/headplane/blob/main/config.example.yaml.";
+    };
+
+    agent = mkOption {
+      type = types.submodule {
+        options = {
+          enable = mkEnableOption "headplane-agent";
+          package = mkPackageOption pkgs "headplane-agent" {};
+          settings = mkOption {
+            type = types.attrsOf [types.str types.bool];
+            description = "Headplane agent env vars config. See: https://github.com/tale/headplane/blob/main/docs/Headplane-Agent.md";
+            default = {};
+          };
+        };
+      };
+    };
+  };
+
+  config = mkIf cfg.enable {
+    environment = {
+      systemPackages = [cfg.package];
+      etc."headplane/config.yaml".source = "${settingsFile}";
+    };
+
+    systemd.services.headplane-agent =
+      mkIf cfg.agent.enable
+      {
+        description = "Headplane side-running agent";
+
+        wantedBy = ["multi-user.target"];
+        after = ["headplane.service"];
+        requires = ["headplane.service"];
+
+        environment = agentEnv;
+
+        serviceConfig = {
+          User = config.services.headscale.user;
+          Group = config.services.headscale.group;
+
+          ExecStart = "${pkgs.headplane-agent}/bin/hp_agent";
+          Restart = "always";
+          RestartSec = 5;
+
+          # TODO: Harden `systemd` security according to the "The Principle of Least Power".
+          # See: `$ systemd-analyze security headplane-agent`.
+        };
+      };
+
+    systemd.services.headplane = {
+      description = "Headscale Web UI";
+
+      wantedBy = ["multi-user.target"];
+      after = ["headscale.service"];
+      requires = ["headscale.service"];
+
+      serviceConfig = {
+        User = config.services.headscale.user;
+        Group = config.services.headscale.group;
+
+        ExecStart = "${pkgs.headplane}/bin/headplane";
+        Restart = "always";
+        RestartSec = 5;
+
+        # TODO: Harden `systemd` security according to the "The Principle of Least Power".
+        # See: `$ systemd-analyze security headplane`.
+      };
+    };
+  };
+}
--- a/nix/package.nix
+++ b/nix/package.nix
@ -0,0 +1,48 @@
+{
+  git,
+  lib,
+  makeWrapper,
+  nodejs_22,
+  pnpm_10,
+  stdenv,
+  ...
+}:
+stdenv.mkDerivation (finalAttrs: {
+  pname = "headplane";
+  version = (builtins.fromJSON (builtins.readFile ../package.json)).version;
+  src = ../.;
+
+  nativeBuildInputs = [
+    makeWrapper
+    nodejs_22
+    pnpm_10.configHook
+    git
+  ];
+
+  dontCheckForBrokenSymlinks = true;
+
+  pnpmDeps = pnpm_10.fetchDeps {
+    inherit (finalAttrs) pname version src;
+    hash = "sha256-j+3fcxukK19fXVIlVe+tXenYf28MylHy+/qHy7FpvL0=";
+  };
+
+  buildPhase = ''
+    runHook preBuild
+    pnpm build
+    pnpm prune --prod
+    runHook postBuild
+  '';
+
+  installPhase = ''
+    runHook preInstall
+    mkdir -p $out/{bin,share/headplane}
+    cp -r {build,node_modules} $out/share/headplane/
+    sed -i "s;$PWD;../..;" $out/share/headplane/build/headplane/server.js
+    makeWrapper ${lib.getExe nodejs_22} $out/bin/headplane \
+        --chdir $out/share/headplane \
+        --set BUILD_PATH $out/share/headplane/build \
+        --set NODE_ENV production \
+        --add-flags $out/share/headplane/build/headplane/server.js
+    runHook postInstall
+  '';
+})