Package the panel as a Nix flake with a NixOS module

The panel now lives in its own repository instead of the nixos config.
The flake provides:

- packages.<system>.default: panelctl plus a panel-api wrapper, with the
  frontend under share/panel and runtime tools appended to PATH
- nixosModules.default: services.reudy-panel (service, directories,
  shared routes group, Caddy vhost with optional Authelia forward_auth,
  routes import and reload path unit, Forgejo integration)
- overlays.default, and checks that build the package and evaluate a
  host using the module

panelctl takes the routes file owner from PANEL_USER/PANEL_GROUP
instead of hardcoding reudy:panelroutes (defaults unchanged).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UbWSNkXxZhYf7eqHTyx3Bf

.gitignore

@@ -0,0 +1,2 @@
+result
+result-*

README.md

@@ -2,6 +2,51 @@
 
 Minimal container management panel for rootless Podman + Caddy.
 
+## Installing on NixOS
+
+This repository is a flake that provides the panel as a package
+(`packages.<system>.default`) and a NixOS module (`nixosModules.default`).
+Add it to your system flake:
+
+```nix
+{
+  inputs.panel = {
+    url = "git+https://git.reudy.net/reudy-net/panel";
+    inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = { nixpkgs, panel, ... }: {
+    nixosConfigurations.vps = nixpkgs.lib.nixosSystem {
+      modules = [
+        panel.nixosModules.default
+        {
+          services.reudy-panel = {
+            enable = true;
+            domain = "panel.example.com";     # Caddy virtual host
+            autheliaAddress = "127.0.0.1:9091"; # forward_auth in front of it
+          };
+        }
+      ];
+    };
+  };
+}
+```
+
+The module sets up the `panel-api` service, the directories below, the
+`panelroutes` group shared with Caddy, the Caddy import of the generated routes
+and a path unit that reloads Caddy when they change. With Forgejo enabled on
+the same host, its URLs are passed to the panel automatically
+(`services.reudy-panel.forgejo.enable`). See `nix/module.nix` for all options.
+
+To deploy a new panel version, bump the input and rebuild:
+
+```bash
+nix flake update panel
+sudo nixos-rebuild switch --flake .#vps
+```
+
+Checks (package build and a module evaluation) run with `nix flake check`.
+
 ## Base directory
 
 `/var/lib/containers`

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1782847189,
+        "narHash": "sha256-twXPFqFsrrY5r28Zh7Homgcp2gUMBgQ6WDS98Q/3xFI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "b6018f87da91d19d0ab4cf979885689b469cdd41",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,58 @@
+{
+  description = "Small web panel for deploying Podman compose apps behind Caddy";
+
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+
+  outputs =
+    { self, nixpkgs }:
+    let
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+      ];
+      forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f nixpkgs.legacyPackages.${system});
+    in
+    {
+      packages = forAllSystems (pkgs: rec {
+        reudy-panel = pkgs.callPackage ./nix/package.nix { };
+        default = reudy-panel;
+      });
+
+      overlays.default = final: _prev: {
+        reudy-panel = final.callPackage ./nix/package.nix { };
+      };
+
+      nixosModules = rec {
+        reudy-panel = ./nix/module.nix;
+        default = reudy-panel;
+      };
+
+      checks = forAllSystems (pkgs: {
+        package = self.packages.${pkgs.stdenv.hostPlatform.system}.default;
+
+        # Evaluates a small host using the module, so option or wiring mistakes
+        # fail here rather than on the server.
+        module =
+          (nixpkgs.lib.nixosSystem {
+            system = pkgs.stdenv.hostPlatform.system;
+            modules = [
+              self.nixosModules.default
+              {
+                boot.isContainer = true;
+                system.stateVersion = "25.11";
+                users.users.reudy.isNormalUser = true;
+                services.caddy.enable = true;
+                services.forgejo.enable = true;
+                services.reudy-panel = {
+                  enable = true;
+                  domain = "panel.example.com";
+                  autheliaAddress = "127.0.0.1:9091";
+                };
+              }
+            ];
+          }).config.system.build.toplevel;
+      });
+
+      formatter = forAllSystems (pkgs: pkgs.nixfmt-rfc-style);
+    };
+}

nix/module.nix

@@ -0,0 +1,178 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+
+let
+  cfg = config.services.reudy-panel;
+  forgejoServer = config.services.forgejo.settings.server;
+  routesFile = "${cfg.baseDir}/routes/routes.caddy";
+in
+{
+  options.services.reudy-panel = {
+    enable = lib.mkEnableOption "the panel for deploying Podman compose apps behind Caddy";
+
+    package = lib.mkOption {
+      type = lib.types.package;
+      default = pkgs.callPackage ./package.nix { };
+      defaultText = lib.literalExpression "pkgs.callPackage ./package.nix { }";
+      description = "The panel package to use.";
+    };
+
+    user = lib.mkOption {
+      type = lib.types.str;
+      default = "reudy";
+      description = ''
+        Existing user the panel runs as. Apps are deployed as rootless Podman
+        containers of this user, so it should have lingering enabled.
+      '';
+    };
+
+    group = lib.mkOption {
+      type = lib.types.str;
+      default = "panelroutes";
+      description = "Group shared by the panel and Caddy for the generated routes file.";
+    };
+
+    baseDir = lib.mkOption {
+      type = lib.types.path;
+      default = "/var/lib/containers";
+      description = "Where stacks, volumes, routes, state and backups are kept.";
+    };
+
+    listenAddress = lib.mkOption {
+      type = lib.types.str;
+      default = "127.0.0.1";
+      description = "Address the panel API listens on.";
+    };
+
+    port = lib.mkOption {
+      type = lib.types.port;
+      default = 9911;
+      description = "Port the panel API listens on.";
+    };
+
+    domain = lib.mkOption {
+      type = lib.types.nullOr lib.types.str;
+      default = null;
+      example = "panel.example.com";
+      description = "Serve the panel on this domain through Caddy. Null disables the virtual host.";
+    };
+
+    autheliaAddress = lib.mkOption {
+      type = lib.types.nullOr lib.types.str;
+      default = null;
+      example = "127.0.0.1:9091";
+      description = ''
+        Authelia instance that protects the panel's virtual host with
+        forward_auth. The panel has no login of its own, so leave this null
+        only if something else guards it.
+      '';
+    };
+
+    forgejo.enable = lib.mkOption {
+      type = lib.types.bool;
+      default = config.services.forgejo.enable;
+      defaultText = lib.literalExpression "config.services.forgejo.enable";
+      description = ''
+        Point the panel at the local Forgejo instance (repo picker, private
+        clones, commit links). URLs are taken from services.forgejo.settings.
+      '';
+    };
+
+    environment = lib.mkOption {
+      type = lib.types.attrsOf lib.types.str;
+      default = { };
+      description = "Extra environment variables for the panel API service.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    environment.systemPackages = [ cfg.package ];
+
+    users.groups.${cfg.group} = { };
+    users.users.${cfg.user}.extraGroups = [ cfg.group ];
+    users.users.caddy.extraGroups = lib.mkIf config.services.caddy.enable [ cfg.group ];
+
+    systemd.tmpfiles.rules =
+      map (dir: "d ${cfg.baseDir}${dir} 0750 ${cfg.user} ${cfg.group} -") [
+        ""
+        "/stacks"
+        "/volumes"
+        "/routes"
+        "/state"
+        "/state/apps"
+        "/backups"
+      ]
+      ++ [ "f ${routesFile} 0640 ${cfg.user} ${cfg.group} -" ];
+
+    systemd.services.panel-api = {
+      description = "Panel API";
+      after = [ "network.target" ];
+      wantedBy = [ "multi-user.target" ];
+
+      serviceConfig = {
+        Type = "simple";
+        User = cfg.user;
+        Group = cfg.group;
+        Restart = "always";
+        RestartSec = 3;
+        WorkingDirectory = cfg.baseDir;
+        ExecStart = lib.getExe cfg.package;
+      };
+
+      environment = {
+        PANEL_API_BIND = cfg.listenAddress;
+        PANEL_API_PORT = toString cfg.port;
+        PANEL_BASE_DIR = toString cfg.baseDir;
+        PANEL_USER = cfg.user;
+        PANEL_GROUP = cfg.group;
+        PANELCTL_PATH = lib.getExe' cfg.package "panelctl";
+      }
+      // lib.optionalAttrs cfg.forgejo.enable {
+        # The API is reached on localhost; clones use the public URLs.
+        PANEL_FORGEJO_URL = lib.removeSuffix "/" forgejoServer.ROOT_URL;
+        PANEL_FORGEJO_API_URL = "http://${forgejoServer.HTTP_ADDR}:${toString forgejoServer.HTTP_PORT}";
+        PANEL_FORGEJO_SSH_URL = "ssh://${
+          forgejoServer.BUILTIN_SSH_SERVER_USER or config.services.forgejo.user
+        }@${forgejoServer.DOMAIN}:${toString forgejoServer.SSH_PORT}";
+      }
+      // cfg.environment;
+    };
+
+    services.caddy = lib.mkIf config.services.caddy.enable {
+      # App routes generated by panelctl.
+      extraConfig = ''
+        import ${routesFile}
+      '';
+
+      virtualHosts = lib.mkIf (cfg.domain != null) {
+        ${cfg.domain}.extraConfig =
+          lib.optionalString (cfg.autheliaAddress != null) ''
+            forward_auth ${cfg.autheliaAddress} {
+              uri /api/authz/forward-auth
+              copy_headers Remote-User Remote-Groups Remote-Email Remote-Name
+            }
+          ''
+          + ''
+            reverse_proxy ${cfg.listenAddress}:${toString cfg.port}
+          '';
+      };
+    };
+
+    # Reload Caddy whenever panelctl rewrites the routes file.
+    systemd.paths.caddy-routes-reload = lib.mkIf config.services.caddy.enable {
+      wantedBy = [ "multi-user.target" ];
+      pathConfig.PathChanged = routesFile;
+    };
+
+    systemd.services.caddy-routes-reload = lib.mkIf config.services.caddy.enable {
+      serviceConfig = {
+        Type = "oneshot";
+        ExecStart = "${config.systemd.package}/bin/systemctl reload caddy.service";
+      };
+    };
+  };
+}

nix/package.nix

@@ -0,0 +1,85 @@
+{
+  lib,
+  stdenvNoCC,
+  makeWrapper,
+  bash,
+  python3,
+  podman,
+  podman-compose,
+  curl,
+  coreutils,
+  gnugrep,
+  gnused,
+  gawk,
+  findutils,
+  zip,
+  unzip,
+  git,
+  util-linux,
+  openssh,
+}:
+
+let
+  # Tools panelctl shells out to. They are appended to PATH, so the host's own
+  # versions (e.g. the system podman) still take precedence when present.
+  runtimeDeps = [
+    podman
+    podman-compose
+    curl
+    coreutils
+    gnugrep
+    gnused
+    gawk
+    findutils
+    zip
+    unzip
+    git
+    util-linux # flock, used to serialise routes file writes
+    openssh # cloning repositories over ssh with the panel's deploy key
+  ];
+in
+stdenvNoCC.mkDerivation {
+  pname = "reudy-panel";
+  version = "0.1.0";
+
+  src = lib.fileset.toSource {
+    root = ../.;
+    fileset = lib.fileset.unions [
+      ../panel-api.py
+      ../panelctl.sh
+      ../frontend
+    ];
+  };
+
+  nativeBuildInputs = [ makeWrapper ];
+  buildInputs = [ bash ];
+
+  dontConfigure = true;
+  dontBuild = true;
+
+  installPhase = ''
+    runHook preInstall
+
+    install -Dm644 panel-api.py $out/share/panel/panel-api.py
+    cp -r frontend $out/share/panel/frontend
+
+    install -Dm755 panelctl.sh $out/bin/panelctl
+    patchShebangs --host $out/bin/panelctl
+    wrapProgram $out/bin/panelctl \
+      --suffix PATH : ${lib.makeBinPath runtimeDeps}
+
+    makeWrapper ${python3.interpreter} $out/bin/panel-api \
+      --add-flags $out/share/panel/panel-api.py \
+      --suffix PATH : ${lib.makeBinPath runtimeDeps} \
+      --set-default PANELCTL_PATH $out/bin/panelctl \
+      --set-default PANEL_FRONTEND_DIR $out/share/panel/frontend
+
+    runHook postInstall
+  '';
+
+  meta = {
+    description = "Small web panel for deploying Podman compose apps behind Caddy";
+    mainProgram = "panel-api";
+    platforms = lib.platforms.linux;
+  };
+}

panel-api.py

@@ -26,7 +26,7 @@ FRONTEND_DIR = os.environ.get(
     os.path.join(os.path.dirname(os.path.abspath(__file__)), "frontend"),
 )
 
-# Optional Forgejo instance (set from panel.nix). The API URL may be an internal
+# Optional Forgejo instance (set by the NixOS module). The API URL may be an internal
 # address; the public URL is what repositories are cloned from and linked to.
 FORGEJO_URL = os.environ.get("PANEL_FORGEJO_URL", "").rstrip("/")
 FORGEJO_API_URL = (os.environ.get("PANEL_FORGEJO_API_URL", "") or FORGEJO_URL).rstrip("/")

panelctl.sh

@@ -9,6 +9,9 @@ STATE_DIR="${BASE_DIR}/state"
 APPS_DIR="${STATE_DIR}/apps"
 ENV_DIR="${STATE_DIR}/env"
 BACKUPS_DIR="${BASE_DIR}/backups"
+# Owner of generated files that Caddy has to read (via the shared group).
+PANEL_USER="${PANEL_USER:-reudy}"
+PANEL_GROUP="${PANEL_GROUP:-panelroutes}"
 
 # Set by load_app: compose file arguments, and the app's environment variables
 # as KEY=VALUE words (passed to compose via env(1), never sourced).
@@ -466,7 +469,7 @@ cmd_render_route() {
     printf "# route:%s:end\n" "${name}"
   } >>"${tmp}"
 
-  install -m 0664 -o reudy -g panelroutes "${tmp}" "${route_file}"
+  install -m 0664 -o "${PANEL_USER}" -g "${PANEL_GROUP}" "${tmp}" "${route_file}"
   rm -f "${tmp}"
   routes_unlock
   log info "rendered route ${route_file}"
@@ -585,7 +588,7 @@ cmd_remove() {
     local tmp
     tmp="$(mktemp)"
     sed "/^# route:${name}:start$/,/^# route:${name}:end$/d" "${route_file}" >"${tmp}" || true
-    install -m 0664 -o reudy -g panelroutes "${tmp}" "${route_file}"
+    install -m 0664 -o "${PANEL_USER}" -g "${PANEL_GROUP}" "${tmp}" "${route_file}"
     rm -f "${tmp}"
     routes_unlock
   fi