Pterodactyl Panel flake #

A NixOS module that deploys Pterodactyl Panel v1.14.1 (built from the upstream panel.tar.gz release via php.buildComposerProject2, pinned to nixos-26.05), with MariaDB and Redis run as local NixOS services. It does not run its own web server -- it exposes a php-fpm unix socket and (optionally) wires a virtual host into an existing services.caddy on the same host.

Usage #

Add this repo as a flake input and import the module:

{
  inputs.pterodactyl-panel.url = "git+https://git.gractwo.pl/gractwo/pterodactyl.git";

  outputs = { self, nixpkgs, pterodactyl-panel, ... }: {
    nixosConfigurations.myserver = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        pterodactyl-panel.nixosModules.default
        {
          services.caddy.enable = true; # if not already enabled elsewhere

          services.pterodactyl-panel = {
            enable = true;
            domain = "panel.example.com";
            # environmentFile = "/run/secrets/pterodactyl-panel.env";
          };
        }
      ];
    };
  };
}

nixos-rebuild switch will then:

• create a pterodactyl-panel system user/group,
• enable MariaDB with a panel database and a pterodactyl-panel user authenticated via unix_socket (no password to manage),
• enable a dedicated Redis instance on a unix socket,
• build the panel and lay it out under /var/lib/pterodactyl-panel (code symlinked read-only from the Nix store; .env, storage/ and bootstrap/cache/ are real, writable files/dirs),
• run migrations/seeders, cache config/routes/views, and generate APP_KEY on first boot,
• run the php-fpm pool, queue worker (pterodactyl-panel-queue.service) and scheduler (pterodactyl-panel-scheduler.timer, every minute), and
• add services.caddy.virtualHosts."panel.example.com" proxying to the php-fpm pool via php_fastcgi (set services.pterodactyl-panel.caddy.enable = false to wire your own vhost instead).

After the first deploy, create an admin user manually:

sudo -u pterodactyl-panel php /var/lib/pterodactyl-panel/artisan p:user:make

Secrets #

services.pterodactyl-panel.environmentFile points at a file (outside the Nix store -- e.g. agenix/sops-nix output, or a manually deployed root-only file) with extra KEY=VALUE lines appended to .env the first time it's generated: mail credentials, HASHIDS_SALT, S3 config, etc. Since DB_* and REDIS_* use unix-socket/peer auth there's no database password to manage.

.env is only written once (on first activation, when it doesn't exist yet); later changes to domain or other options require editing /var/lib/pterodactyl-panel/.env by hand and restarting the panel services.

Known gap: vendorHash #

pkgs/pterodactyl-panel.nix pins a vendorHash for the composer dependencies. It was computed by locally running the same composer install sequence nixpkgs' buildComposerProject2 uses and hashing the result -- not verified with an actual sandboxed Linux build (no Linux builder was available in the environment this flake was authored in). Run nix build .#pterodactyl-panel on the target NixOS host/CI first; if the FOD hash mismatches, Nix will print the correct sha256-... value to paste in.

Updating #

Bump version and sha256 (via nix-prefetch-url) in pkgs/pterodactyl-panel.nix for a new panel release, then rebuild once with a dummy vendorHash to get the real one from the mismatch error.