From 03a7e513847ff6abe2fe322ccf5f6c0dde82d406 Mon Sep 17 00:00:00 2001 From: Igor Ramazanov Date: Tue, 18 Mar 2025 05:31:37 +0100 Subject: [PATCH] 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 --- .envrc | 1 + .github/workflows/nix-update-lock.yaml | 20 ++++ .github/workflows/nix.yaml | 24 +++++ docs/Nix.md | 127 +++++++++++++++++++++++++ flake.lock | 82 ++++++++++++++++ flake.nix | 69 ++++++++++++++ nix/agent.nix | 9 ++ nix/module.nix | 112 ++++++++++++++++++++++ nix/package.nix | 48 ++++++++++ 9 files changed, 492 insertions(+) create mode 100644 .envrc create mode 100644 .github/workflows/nix-update-lock.yaml create mode 100644 .github/workflows/nix.yaml create mode 100644 docs/Nix.md create mode 100644 flake.lock create mode 100644 flake.nix create mode 100644 nix/agent.nix create mode 100644 nix/module.nix create mode 100644 nix/package.nix diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..c4b17d7 --- /dev/null +++ b/.envrc @@ -0,0 +1 @@ +use_flake diff --git a/.github/workflows/nix-update-lock.yaml b/.github/workflows/nix-update-lock.yaml new file mode 100644 index 0000000..43ec980 --- /dev/null +++ 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 diff --git a/.github/workflows/nix.yaml b/.github/workflows/nix.yaml new file mode 100644 index 0000000..243c7ba --- /dev/null +++ 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 diff --git a/docs/Nix.md b/docs/Nix.md new file mode 100644 index 0000000..12f3c18 --- /dev/null +++ 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"; + }; + }; + }; + } + } + ]; + }; + }; +} +``` diff --git a/flake.lock b/flake.lock new file mode 100644 index 0000000..c381c7f --- /dev/null +++ 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 +} diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..9229532 --- /dev/null +++ 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; + }; +} diff --git a/nix/agent.nix b/nix/agent.nix new file mode 100644 index 0000000..884944d --- /dev/null +++ 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; +} diff --git a/nix/module.nix b/nix/module.nix new file mode 100644 index 0000000..99476ab --- /dev/null +++ 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`. + }; + }; + }; +} diff --git a/nix/package.nix b/nix/package.nix new file mode 100644 index 0000000..9e7f57f --- /dev/null +++ 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 + ''; +})