feat(nixos): add SteamCMD server support

configs/nixos/hosts/pikachu/default.nix

@@ -66,6 +66,45 @@
 
   registry.address.pikachu.self = "10.23.10.102";
 
+  modules.services.steamcmd = {
+    enable = true;
+    dataDir = "/pikachu/data/steamcmd";
+    apps.valheim = {
+      enable = true;
+      appId = 896660;
+      installDir = "/pikachu/data/servers/valheim/main";
+      workingDirectory = "/pikachu/data/servers/valheim/main";
+      dataDirs = [ "/pikachu/media/games/servers/valheim/main" ];
+      packages = [ pkgs.steam-run ];
+      environment = {
+        SteamAppId = "892970";
+        SERVER_PASSWORD = "foobarbaz";
+      };
+      command = [
+        "${pkgs.bash}/bin/bash"
+        "-c"
+        ''
+          ${pkgs.coreutils}/bin/install -d -m 0770 /pikachu/media/games/servers/valheim/main
+          export LD_LIBRARY_PATH="$PWD/linux64:$LD_LIBRARY_PATH"
+          exec steam-run ./valheim_server.x86_64 \
+            -nographics \
+            -batchmode \
+            -name main \
+            -port 2456 \
+            -world main \
+            -savedir /pikachu/media/games/servers/valheim/main \
+            -password "$SERVER_PASSWORD" \
+            -public 0
+        ''
+      ];
+      udpPorts = [
+        2456
+        2457
+        2458
+      ];
+    };
+  };
+
   guests.actualbudget = {
     enable = true;
     vlan = 20;

configs/nixos/modules/services/steamcmd.nix

@@ -0,0 +1,325 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  cfg = config.modules.services.steamcmd;
+
+  appType = lib.types.submodule (
+    { config, name, ... }:
+    {
+      options = {
+        enable = lib.mkEnableOption "this SteamCMD app service";
+
+        appId = lib.mkOption {
+          type = lib.types.ints.positive;
+          example = 896660;
+          description = "Steam app ID for the dedicated server.";
+        };
+
+        installDir = lib.mkOption {
+          type = lib.types.str;
+          example = "/data/servers/valheim/main";
+          description = "Directory where SteamCMD installs the server files.";
+        };
+
+        workingDirectory = lib.mkOption {
+          type = lib.types.nullOr lib.types.str;
+          default = null;
+          example = "/data/servers/valheim/main";
+          description = "Directory where the game service starts.";
+        };
+
+        command = lib.mkOption {
+          type = lib.types.listOf lib.types.str;
+          example = [
+            "/data/servers/valheim/main/valheim_server.x86_64"
+            "-name"
+            "main"
+          ];
+          description = "Command that starts the game server.";
+        };
+
+        user = lib.mkOption {
+          type = lib.types.str;
+          default = cfg.user;
+          defaultText = lib.literalExpression "config.modules.services.steamcmd.user";
+          description = "User account that runs the game service.";
+        };
+
+        group = lib.mkOption {
+          type = lib.types.str;
+          default = cfg.group;
+          defaultText = lib.literalExpression "config.modules.services.steamcmd.group";
+          description = "Group account that owns writable server files.";
+        };
+
+        environment = lib.mkOption {
+          type = lib.types.attrsOf lib.types.str;
+          default = { };
+          description = "Environment variables for the game service.";
+        };
+
+        environmentFiles = lib.mkOption {
+          type = lib.types.listOf lib.types.path;
+          default = [ ];
+          description = "Environment files loaded by the game service.";
+        };
+
+        dataDirs = lib.mkOption {
+          type = lib.types.listOf lib.types.str;
+          default = [ ];
+          example = [ "/media/games/servers/valheim/main" ];
+          description = "Additional writable directories created before the game service starts.";
+        };
+
+        updateOnStart = lib.mkOption {
+          type = lib.types.bool;
+          default = true;
+          description = "Runs SteamCMD before each game service start.";
+        };
+
+        validateUpdate = lib.mkOption {
+          type = lib.types.bool;
+          default = true;
+          description = "Passes validate to SteamCMD app_update.";
+        };
+
+        packages = lib.mkOption {
+          type = lib.types.listOf lib.types.package;
+          default = [ ];
+          description = "Packages added to the game service path.";
+        };
+
+        tcpPorts = lib.mkOption {
+          type = lib.types.listOf lib.types.port;
+          default = [ ];
+          description = "TCP ports opened for the game service.";
+        };
+
+        udpPorts = lib.mkOption {
+          type = lib.types.listOf lib.types.port;
+          default = [ ];
+          description = "UDP ports opened for the game service.";
+        };
+
+        restart = {
+          enable = lib.mkOption {
+            type = lib.types.bool;
+            default = true;
+            description = "Enables the scheduled restart timer.";
+          };
+
+          onCalendar = lib.mkOption {
+            type = lib.types.str;
+            default = "daily";
+            example = "*-*-* 05:00:00";
+            description = "Calendar expression for the restart timer.";
+          };
+
+          randomizedDelaySec = lib.mkOption {
+            type = lib.types.str;
+            default = "15m";
+            description = "Maximum randomized delay for the restart timer.";
+          };
+
+          command = lib.mkOption {
+            type = lib.types.nullOr lib.types.str;
+            default = null;
+            example = "systemctl restart valheim.service";
+            description = "Command run by the restart timer.";
+          };
+        };
+      };
+
+      config = {
+        workingDirectory = lib.mkDefault config.installDir;
+      };
+    }
+  );
+
+  enabledApps = lib.filterAttrs (_: app: app.enable) cfg.apps;
+
+  prepareScript = name: app:
+    pkgs.writeShellScript "steamcmd-${name}-prepare" ''
+      set -eu
+
+      ${pkgs.coreutils}/bin/install -d \
+        -o ${lib.escapeShellArg cfg.user} \
+        -g ${lib.escapeShellArg cfg.group} \
+        -m 0770 \
+        ${lib.escapeShellArg cfg.dataDir}
+
+      ${pkgs.coreutils}/bin/install -d \
+        -o ${lib.escapeShellArg app.user} \
+        -g ${lib.escapeShellArg app.group} \
+        -m 0770 \
+        ${lib.escapeShellArg app.installDir} \
+        ${lib.escapeShellArgs app.dataDirs}
+    '';
+
+  updateScript = name: app:
+    pkgs.writeShellScript "steamcmd-${name}-update" ''
+      set -eu
+
+      export HOME=${lib.escapeShellArg cfg.dataDir}
+      exec ${lib.getExe cfg.package} \
+        +force_install_dir ${lib.escapeShellArg app.installDir} \
+        +login anonymous \
+        +app_update ${toString app.appId} ${lib.optionalString app.validateUpdate "validate"} \
+        +quit
+    '';
+
+  startScript = name: app:
+    pkgs.writeShellScript "steamcmd-${name}-start" ''
+      set -eu
+
+      cd ${lib.escapeShellArg app.workingDirectory}
+      exec ${lib.escapeShellArgs app.command}
+    '';
+
+  restartCommand = name: app:
+    if app.restart.command != null then
+      app.restart.command
+    else
+      "systemctl restart ${lib.escapeShellArg name}.service";
+in
+{
+  options.modules.services.steamcmd = {
+    enable = lib.mkEnableOption "SteamCMD service management";
+
+    package = lib.mkPackageOption pkgs "steamcmd" { };
+
+    user = lib.mkOption {
+      type = lib.types.str;
+      default = "steamcmd";
+      description = "User account that runs SteamCMD.";
+    };
+
+    group = lib.mkOption {
+      type = lib.types.str;
+      default = "steamcmd";
+      description = "Group account that owns SteamCMD files.";
+    };
+
+    dataDir = lib.mkOption {
+      type = lib.types.str;
+      default = "/data/steamcmd";
+      description = "Directory where SteamCMD stores metadata and cache files.";
+    };
+
+    apps = lib.mkOption {
+      type = lib.types.attrsOf appType;
+      default = { };
+      description = "SteamCMD-managed game services keyed by service name.";
+    };
+  };
+
+  config = lib.mkMerge [
+    {
+      registry."stable-uid".${config.networking.hostName}.steamcmd = 20003;
+    }
+
+    (lib.mkIf cfg.enable {
+      assertions = [
+        {
+          assertion = enabledApps != { };
+          message = "modules.services.steamcmd.apps must contain at least one enabled app.";
+        }
+      ];
+
+      users.groups.${cfg.group} = { };
+      users.users.${cfg.user} = {
+        isSystemUser = true;
+        uid = config.registry."stable-uid".${config.networking.hostName}.steamcmd;
+        group = cfg.group;
+        home = cfg.dataDir;
+      };
+
+      systemd.tmpfiles.rules =
+        [
+          "d ${cfg.dataDir} 0770 ${cfg.user} ${cfg.group} - -"
+          "z ${cfg.dataDir} 0770 ${cfg.user} ${cfg.group} - -"
+        ]
+        ++ lib.flatten (
+          lib.mapAttrsToList (_: app: [
+            "d ${app.installDir} 0770 ${cfg.user} ${cfg.group} - -"
+            "z ${app.installDir} 0770 ${cfg.user} ${cfg.group} - -"
+          ]) enabledApps
+        );
+
+      systemd.services = lib.mkMerge (
+        lib.mapAttrsToList (name: app: {
+          "steamcmd-${name}-update" = {
+            description = "Update ${name} with SteamCMD";
+            after = [ "network-online.target" ];
+            wants = [ "network-online.target" ];
+            serviceConfig = {
+              Type = "oneshot";
+              User = app.user;
+              Group = app.group;
+              WorkingDirectory = "-${cfg.dataDir}";
+              ExecStartPre = "+${prepareScript name app}";
+              ExecStart = updateScript name app;
+            };
+          };
+
+          ${name} = {
+            description = "${name} game server";
+            after = [
+              "network-online.target"
+              "steamcmd-${name}-update.service"
+            ];
+            wants = [ "network-online.target" ];
+            wantedBy = [ "multi-user.target" ];
+            path = app.packages;
+            environment = app.environment;
+            serviceConfig = {
+              Type = "simple";
+              User = app.user;
+              Group = app.group;
+              WorkingDirectory = "-${app.workingDirectory}";
+              EnvironmentFile = app.environmentFiles;
+              ExecStartPre = [
+                "+${prepareScript name app}"
+              ] ++ lib.optional app.updateOnStart (updateScript name app);
+              ExecStart = startScript name app;
+              Restart = "on-failure";
+            };
+          };
+
+          "steamcmd-${name}-restart" = lib.mkIf app.restart.enable {
+            description = "Restart ${name}";
+            serviceConfig = {
+              Type = "oneshot";
+              ExecStart = pkgs.writeShellScript "steamcmd-${name}-restart" ''
+                set -eu
+
+                exec ${restartCommand name app}
+              '';
+            };
+          };
+        }) enabledApps
+      );
+
+      systemd.timers = lib.mkMerge (
+        lib.mapAttrsToList (name: app: {
+          "steamcmd-${name}-restart" = lib.mkIf app.restart.enable {
+            description = "Restart ${name} on a schedule";
+            wantedBy = [ "timers.target" ];
+            timerConfig = {
+              OnCalendar = app.restart.onCalendar;
+              RandomizedDelaySec = app.restart.randomizedDelaySec;
+              Persistent = true;
+            };
+          };
+        }) enabledApps
+      );
+
+      networking.firewall.allowedTCPPorts = lib.flatten (lib.mapAttrsToList (_: app: app.tcpPorts) enabledApps);
+      networking.firewall.allowedUDPPorts = lib.flatten (lib.mapAttrsToList (_: app: app.udpPorts) enabledApps);
+    })
+  ];
+}

docs/00 INBOX/ai/steamcmd-server.md

@@ -0,0 +1,93 @@
+# Add a SteamCMD server
+
+## 1. Configure the generic SteamCMD module
+
+1. Create or update `configs/nixos/modules/services/steamcmd.nix`.
+2. Define `modules.services.steamcmd.enable`.
+3. Create the `steamcmd` service user.
+4. Configure the shared SteamCMD data directory.
+5. Add one option for each Steam app service.
+6. Run SteamCMD before each app service starts.
+7. Update the Steam app on each service restart.
+8. Add a restart timer with default settings.
+9. Add an option that overrides the restart command.
+10. Open declared in-machine firewall ports.
+
+## 2. Configure the game service module
+
+1. Create or update `configs/nixos/modules/services/<game>.nix`.
+2. Define `modules.services.<game>.enable`.
+3. Add the Steam app ID for the dedicated server.
+4. Add runtime packages that the server binary needs.
+5. Add `serverName` for the service identity.
+6. Use `serverName` as the default world or save name.
+7. Add a game-specific world or save option when the game supports it.
+8. Add guest-internal paths for server files and durable state.
+9. Add options for required ports.
+10. Add options for required secret files or values.
+11. Map the game options to `modules.services.steamcmd`.
+12. Configure the game service command.
+13. Pass secrets to the service without embedding secret values in Nix.
+14. Open the required in-machine firewall ports.
+
+## 3. Configure the guest module
+
+1. Create or update `configs/nixos/guests/<game>.nix`.
+2. Define `guests.<game>` options for host-level wiring.
+3. Add `serverName`.
+4. Pass `serverName` to `modules.services.<game>` inside `interior`.
+5. Add host path options for SteamCMD data, server files, and durable state.
+6. Use names such as `steamcmdPath`, `serverPath`, and `statePath`.
+7. Mount each host path into the guest.
+8. Mount sops-backed secret files read-only into the guest.
+9. Pass guest paths for secret files to `modules.services.<game>`.
+10. Set guest resource limits.
+11. Keep VLAN placement and address wiring in the guest or host configuration.
+
+## 4. Add host storage
+
+1. Choose a host path for SteamCMD data.
+2. Choose a host path for downloaded server files.
+3. Choose a host path for world data, saves, and generated config.
+4. Configure those paths through `guests.<game>`.
+
+## 5. Add secrets
+
+1. Add a sops secret for each durable server secret.
+2. Configure the guest option that names each sops secret.
+3. Do not put passwords or tokens in Nix strings.
+4. Do not pass passwords or tokens as process arguments.
+
+## 6. Configure networking
+
+1. Keep game port knowledge in `modules.services.<game>`.
+2. Open game ports from `modules.services.<game>`.
+3. Configure guest VLAN placement from the guest or host configuration.
+4. Add a DHCP reservation before you commit a stable guest address.
+5. Forward public ports to the guest address when the server needs public access.
+
+## 7. Enable the guest on the target host
+
+1. Set `guests.<game>.enable = true`.
+2. Set `guests.<game>.serverName` to the server identity.
+3. Set the host paths for SteamCMD data, server files, and durable state.
+4. Set the secret names for the server.
+5. Set the guest network options required by the host.
+
+## 8. Deploy the host
+
+1. Run `deploy-to <host>` from a clean checkout.
+2. Check `container@<game>.service` on the host.
+3. Enter the guest with `nixos-container root-login <game>`.
+4. Check the SteamCMD update service.
+5. Check the game service with `systemctl status <unit>`.
+6. Follow logs with `journalctl -u <unit> -f`.
+
+## 9. Validate the server
+
+1. Confirm the guest address with `machinectl status <game>`.
+2. Connect from the LAN before you add public forwarding.
+3. Restart the game service.
+4. Confirm that the restart updates the Steam app.
+5. Confirm that the restart timer uses the expected command.
+6. Confirm that durable state lands in the mounted state path.