Notes from a NixOS install

[tecosaur]

As I mentioned in the other issue I just opened, I've managed to get this working on my NixOS server (in case it's of interest: https://code.tecosaur.net/tec/golgi/commit/53f3218c28168c7f619a1fd8de2093fe823d2f83)

Packaging was rather straightforward, except for these two hacks I seemed to need to do:

• sed -i 's;/build/source/node_modules/react-router/dist/development/index.mjs;react-router;' $out/share/headplane/build/headplane/server.js because the build path was hardcoded into some of the bundled code
• sed -i 's;define_process_env_default.PORT;process.env.PORT;' $out/share/headplane/build/headplane/server.js because the PORT envvar wasn't being loaded correctly

To work around the read-only config file issue mentioned in #48, I run cp ${headscale-config-copy} /tmp/headscale.yaml; chmod u+w /tmp/headscale.yaml' as a ExecStartPre step in the service. I figure it will just get overwritten every time the service is started, but that's fine as a stop-gap.

I thought I'd mention this here in case there's anything that can be done to remove the need for the packaging hacks I mention, and in case it helps anyone else :)

[StealthBadger747]

Thanks for sharing! Probably saved me from a long debugging session.

On 3.6 I was getting away with my-headplane-3.6.nix
In 3.9 I had to introduce a new patchPhase, but I forgot to commit that to git... But now thanks to your config you actually taught me a couple things as well like lib.getExe and I liked your /share/headplane. And now my config is this: my-headplane-4.1.nix

[StealthBadger747]

Also @tecosaur regarding that issue you mentioned (48) I'm not clear as to what the issue is there, but if you are talking about sharing the generated yaml that headscale generates, to headplane I solved it like this:

Note specifically this part

let
  ....
  settingsFormat = pkgs.formats.yaml {};
  headscaleConfig = settingsFormat.generate "headscale-settings.yaml" config.services.headscale.settings;
in {
  environment.etc."headscale/config.yaml".source = 
    lib.mkForce (settingsFormat.generate "headscale-config.yaml" config.services.headscale.settings);

This is a more fleshed out config, but still severely trimmed down.

{ config, pkgs, pkgs-unstable, lib, ... }:
let
  # .....
  headscale_fqdn = "${headscale_host}.${headscale_tld}";
  headplane_port = "3000";
  headplanePkg = pkgs.callPackage ../packages/headplane.nix {};

  settingsFormat = pkgs.formats.yaml {};
  headscaleConfig = settingsFormat.generate "headscale-settings.yaml" config.services.headscale.settings;
in {
  environment.etc."headscale/config.yaml".source = 
    lib.mkForce (settingsFormat.generate "headscale-config.yaml" config.services.headscale.settings);

  services = {
    headscale = {
      enable = true;
      address = "127.0.0.1";
      port = 8080;
      package = pkgs-unstable.headscale;
      settings = {
        server_url = "https://${headscale_fqdn}";
        dns.base_domain = "internal-${headscale_fqdn}";
        oidc = {
          # .....
        };
      };
    };
  };

  systemd.services.headplane = {
    description = "Headplane Service";
    after = [ "network.target" ];
    wantedBy = [ "multi-user.target" ];
    serviceConfig = {
      ExecStart = "${headplanePkg}/bin/headplane";
      WorkingDirectory = "${headplanePkg}";
      Restart = "always";
      User = "headplane";
      Group = "headplane";
      EnvironmentFile = config.sops.secrets.headplane.path;
      Environment = [
        "HOST=127.0.0.1"
        "PORT=${headplane_port}"
        "HEADSCALE_INTEGRATION=proc"
        "HEADSCALE_URL=https://${headscale_fqdn}"
        "DEBUG=true"
        "HEADSCALE_CONFIG_UNSTRICT=true"
      ];
    };
  };
}

Hope that helps!

[tecosaur]

Thanks for sharing, seems like a pretty similar solution, just writing the copy somewhere else.

Along the lines of #48, it would be good if headplane might recognise read-only Configs and make the settings web page present itself as read-only to reflect that.

[tale]

Still WIP, I have a very big update coming out as Headplane 0.5 and that's planned with it.

[StealthBadger747]

@tale that's awesome! Thanks.

As a side note. If I made a PR with a Nix CI pipeline to test new builds would you be interested in adopting it? It seems we have a small community of people who want to use your project on Nix.

[tale]

@StealthBadger747 @tecosaur I believe Headplane should already support read-only config files, do you have debug logs that could indicate what is happening on startup. Also is the DNS/Settings tabs just completely hidden?

[igor-ramazanov]

Has anyone a successfull build for 0.5.0?

Using https://code.tecosaur.net/tec/golgi/commit/53f3218c28168c7f619a1fd8de2093fe823d2f83 from the above (after pinning node_22 and pnpm_10) fails with a bunch of errors like:

...
> ERROR: noBrokenSymlinks: the symlink /nix/store/40zhs0dq4b6nh1r4mlzfimj73yxsn4vp-headplane-0.5.0/share/headplane/node_modules/.pnpm/node_modules/prettier points to a missing target: /nix/store/40zhs0dq4b6nh1r4mlzfimj73yxsn4vp-headplane-0.5.0/share/headplane/node_modules/.pnpm/prettier@2.8.8/node_modules/prettier
...

Apparently, there some issues with fetching the deps.
I'm using fetchDeps:

...
  pnpmDeps = pnpm_10.fetchDeps {
    inherit (finalAttrs) pname version src;
    hash = "sha256-j+3fcxukK19fXVIlVe+tXenYf28MylHy+/qHy7FpvL0=";
  };
...

Related: NixOS/nixpkgs#380391.

[tale]

Please update, 0.5 just had some seriously weird issues. However, it is no longer env file based.

[tale]

FWIW I want to add an examples/ folder in the docs and I would absolutely love adding Nix examples there. Would anyone here be open to this and possibly contributing some instructions. I'm willing to work on this too so that the code and deployment is suited for Nix too.

[igor-ramazanov]

@tale I think it works, I just have broken Authelia for different reasons, so haven't verified it yet.

But, adding the dontCheckForBrokenSymlinks = true; made the build passing for me.

The full code:

{
  fetchFromGitHub,
  git,
  lib,
  makeWrapper,
  nodejs_22,
  pnpm_10,
  stdenv,
  ...
}:
# Source: <https://gist.github.com/feathecutie/8ebc00237bcdefd517e6b65f5ea5e0dc>.
stdenv.mkDerivation (finalAttrs: {
  pname = "headplane";
  version = "0.5.0";

  src = fetchFromGitHub {
    owner = "tale";
    repo = finalAttrs.pname;
    tag = finalAttrs.version;
    hash = "sha256-62zcORuugRREyrv6xLA6w57CJ9fufUiL2iOG98KxCTI=";
    leaveDotGit = true;
  };

  nativeBuildInputs = [
    makeWrapper
    nodejs_22
    pnpm_10.configHook
    git
  ];

  # To prevent `noBrokenSymlinks` errors in nix.
  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;/build/source/node_modules/react-router/dist/development/index.mjs;react-router;' $out/share/headplane/build/headplane/server.js
    sed -i 's;define_process_env_default.PORT;process.env.PORT;' $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
  '';
})

[tecosaur]

Instead of dontCheckForBrokenSymlinks = true; you can add find node_modules -xtype l -delete to the buildPhase. See: pnpm/pnpm#3645.

[StealthBadger747]

@tale I can contribute NixOS examples.

[igor-ramazanov]

I've added a draft WIP PR: #132.

Still has a number of issues, feel free to grab/push from/to the branch.

[igor-ramazanov]

I'm working on upstreaming it to the nixpkgs.

Will link a PR here, so you could participate as well.

Once upstreamed, it wouldn't be strictly necessary to keep the nix code in this repo.

[igor-ramazanov]

NixOS/nixpkgs#398667

[StealthBadger747]

@tecosaur we finally got the nixpkgs PR merged!

I've been spreading this around.

Nix will be removed from this repo soon as @tale never really wanted to maintain a nixpkg in the first place. I recently had NixOS/nixpkgs#398667 merged to upstream nixpkgs. I'm currently working on a followup PR for v0.6.2 and I'm also contemplating hosting a flake repository to maintain the beta versions of headplane there.

[igor-ramazanov]

I think it makes to wait until 26.05 NixOS' release before removing it from the repo to cover up people who don't use unstable channels

[tale]

Good catch, I also spoke to @StealthBadger747 and I want to probably maintain an overlay or package that supports the nightly/unstable versions of Headplane but try and reduce the maintenance burden as much as possible. For stable versions of Headplane I'd point people towards nixpkgs though as this isn't really maintenance burden I want to take on.

[igor-ramazanov]

Yeah, makes sense. There are ways to reduce the burden, e.g. by removing config typing in nix and using just raw untyped attribute sets, so there's no need to update the nix code whenever config schema changes. The autogenerated web nix documentation will be lost, but, perhaps, it's ok, since there's already config.example.yaml and it's nightly.

As for nixpkgs, there's https://search.nixos.org/options?channel=unstable&query=services.headplane. where everything is documented through types and outside of this repo's scope.

Maybe something else? Also thought about removing the service module altogether to keep only packaging, but maybe better to keep it?

[tale]

I liked the idea of packaging only and then simply overriding `services.headplane.package` and `services.headplane.agent.package`, but I’m actually not 100% sure if the headplane service is composable enough to allow changes to the configuration that haven’t been cut as a release yet. It would probably need like a `services.headplane.settings.extra_yaml` which seems wrong/terrible?

…

On May 3, 2026, at 2:19 PM, Igor Ramazanov ***@***.***> wrote: Yeah, makes sense. There are ways to reduce the burden, e.g. by removing config typing in nix and using just raw untyped attribute sets, so there's no need to update the nix code whenever config schema changes. The autogenerated web nix documentation will be lost, but, perhaps, it's ok, since there's already config.example.yaml and it's nightly. As for nixpkgs, there's https://search.nixos.org/options?channel=unstable&query=services.headplane. where everything is documented through types and outside of this repo's scope. Maybe something else? Also thought about removing the service module altogether to keep only packaging, but maybe better to keep it? — Reply to this email directly, view it on GitHub <#138 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AK77AWGSO7EHOA4SXGJKFT34Y6ES7AVCNFSM6AAAAACYNCS2FWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTMNZZG42TKNI>. You are receiving this because you were mentioned.

[igor-ramazanov]

That's a really neat idea!

Yeah, definitely - the possibility of flexible untyped configuration in the nixpkgs' module should be explored.

The problem definition is that it requires bypassing existing and reasonable deprecations/warnings/assertions - they should continue working for stable releases.