add deploy/create/install apps, fix templates and docs

- Add apps: create (scaffold host from template), deploy (multi-host
  deployment with -n filter), install (NixOS installation from live ISO)
- Register all apps in flake.nix (create, deploy, install, rebuild)
- Add deploy.json config (cryodev-main, SSH port 2299)
- Fix generic-server template: was using Pi hardware/boot config,
  now correct x86_64 with systemd-boot, UEFI, ROOT/BOOT/SWAP labels
- Fix template networking.nix: use HOSTNAME placeholder instead of
  hardcoded cryodev-pi (both templates)
- Fix headplane upstream pnpm-deps hash mismatch via overlay
- Fix all docs: replace root@ with user@, --ssh-option with
  NIX_SSHOPTS, add deploy app references, update first-install guide
  to use create app and document service deactivation steps

AGENTS.md

@@ -43,13 +43,31 @@ nix develop
 ### Deployment
 
 ```bash
+# Deploy all hosts via deploy app (uses deploy.json)
+nix run .#deploy
+
 # Deploy to cryodev-main via deploy-rs
 nix run github:serokell/deploy-rs -- .#cryodev-main
 
 # Manual deployment via SSH
-nixos-rebuild switch --flake .#<hostname> \
+NIX_SSHOPTS="-p 2299" nixos-rebuild switch --flake .#<hostname> \
-  --target-host <user>@<ip> --use-remote-sudo \
+  --target-host <user>@<ip> --use-remote-sudo
-  --ssh-option="-p 2299"
+```
+
+### Apps
+
+```bash
+# Create a new host from template
+nix run .#create -- -t generic-server -n <hostname>
+
+# Install NixOS on a new machine (run from NixOS live ISO)
+nix run .#install -- -n <hostname> -r <REPO_URL>
+
+# Deploy to all configured hosts
+nix run .#deploy
+
+# Rebuild NixOS/Home Manager configuration
+nix run .#rebuild -- nixos
 ```
 
 ## Code Style & Conventions

apps/create/create.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+
+# Create a new host from a template
+
+FLAKE_DIR="."
+TEMPLATE=""
+HOSTNAME=""
+SYSTEM=""
+
+SEPARATOR="________________________________________"
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") -t TEMPLATE -n HOSTNAME [-s SYSTEM] [-f FLAKE_DIR]
+
+Options:
+  -t, --template TEMPLATE   Template to use (mandatory)
+  -n, --hostname HOSTNAME   Hostname for the new host (mandatory)
+  -s, --system SYSTEM       System architecture (default: derived from template)
+  -f, --flake FLAKE_DIR     Path to flake directory (default: .)
+  -h, --help                Show this help message
+
+Available templates:
+  generic-server    x86_64 server with SSH, Nginx, Headscale client
+  raspberry-pi      aarch64 Raspberry Pi 4 with Comin, Tailscale
+EOF
+}
+
+error() {
+  echo "Error: $1" >&2
+  exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -t|--template)  TEMPLATE="$2"; shift 2 ;;
+    -n|--hostname)  HOSTNAME="$2"; shift 2 ;;
+    -s|--system)    SYSTEM="$2"; shift 2 ;;
+    -f|--flake)     FLAKE_DIR="$2"; shift 2 ;;
+    -h|--help)      usage; exit 0 ;;
+    *)              error "Unknown option: $1" ;;
+  esac
+done
+
+# Validate
+[[ -z "$TEMPLATE" ]] && error "Template is required (-t)"
+[[ -z "$HOSTNAME" ]] && error "Hostname is required (-n)"
+
+TEMPLATE_DIR="$FLAKE_DIR/templates/$TEMPLATE"
+HOST_DIR="$FLAKE_DIR/hosts/$HOSTNAME"
+
+[[ ! -d "$TEMPLATE_DIR" ]] && error "Template '$TEMPLATE' not found in $TEMPLATE_DIR"
+[[ -d "$HOST_DIR" ]] && error "Host '$HOSTNAME' already exists in $HOST_DIR"
+
+# Derive system from template if not specified
+if [[ -z "$SYSTEM" ]]; then
+  case "$TEMPLATE" in
+    generic-server)  SYSTEM="x86_64-linux" ;;
+    raspberry-pi)    SYSTEM="aarch64-linux" ;;
+    *)               error "Cannot derive system for template '$TEMPLATE'. Use -s to specify." ;;
+  esac
+fi
+
+echo "$SEPARATOR"
+echo "Creating host '$HOSTNAME' from template '$TEMPLATE'"
+echo "  System:    $SYSTEM"
+echo "  Target:    $HOST_DIR"
+echo "$SEPARATOR"
+
+# Copy template
+cp -r "$TEMPLATE_DIR" "$HOST_DIR"
+
+# Remove template flake.nix (not needed in host dir)
+rm -f "$HOST_DIR/flake.nix"
+
+# Replace hostname in networking.nix
+sed -i "s/networking.hostName = \".*\"/networking.hostName = \"$HOSTNAME\"/" "$HOST_DIR/networking.nix"
+
+# Create empty secrets.yaml placeholder
+touch "$HOST_DIR/secrets.yaml"
+
+# Add to git
+git -C "$FLAKE_DIR" add "$HOST_DIR"
+
+echo "$SEPARATOR"
+echo "Host '$HOSTNAME' created successfully."
+echo ""
+echo "Next steps:"
+echo "  1. Add to flake.nix:"
+echo ""
+echo "     $HOSTNAME = mkNixosConfiguration \"$SYSTEM\" [ ./hosts/$HOSTNAME ];"
+echo ""
+echo "  2. Update hardware.nix and disks.sh for your hardware"
+echo "  3. Update .sops.yaml with creation rules for hosts/$HOSTNAME/secrets.yaml"
+echo "  4. Follow the first-install guide: docs/getting-started/first-install.md"

apps/create/default.nix

@@ -0,0 +1,20 @@
+{
+  writeShellApplication,
+  git,
+  gnused,
+  ...
+}:
+
+let
+  name = "create";
+  text = builtins.readFile ./${name}.sh;
+in
+writeShellApplication {
+  inherit name text;
+  meta.mainProgram = name;
+
+  runtimeInputs = [
+    git
+    gnused
+  ];
+}

apps/deploy/default.nix

@@ -0,0 +1,18 @@
+{
+  writeShellApplication,
+  jq,
+  ...
+}:
+
+let
+  name = "deploy";
+  text = builtins.readFile ./${name}.sh;
+in
+writeShellApplication {
+  inherit name text;
+  meta.mainProgram = name;
+
+  runtimeInputs = [
+    jq
+  ];
+}

apps/deploy/deploy.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+
+# defaults
+FLAKE_URI="."
+CONFIG_FILE="./deploy.json"
+ACTION="switch"
+USE_SUDO=true
+DO_BUILD=true
+FILTER_HOSTS=()
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [OPTIONS] [ACTION]
+
+Arguments:
+  ACTION                 switch | boot | test (Default: $ACTION)
+
+Options:
+  -n, --host NAME        Deploy only this host (can be repeated)
+  -f, --flake URI        URI of the flake (Default: $FLAKE_URI)
+  -c, --config FILE      Deployment config file (Default: $CONFIG_FILE)
+  --no-sudo              Do not pass sudo-related flags to nixos-rebuild.
+  --skip-build           Skip the explicit 'build' step before deployment.
+  -h, --help             Show this help.
+
+Examples:
+  $(basename "$0")                      Deploy all hosts
+  $(basename "$0") -n cryodev-main      Deploy only cryodev-main
+  $(basename "$0") -n host-a -n host-b  Deploy host-a and host-b
+EOF
+}
+
+_status() { echo -e "\033[0;34m> $1\033[0m"; }
+success() { echo -e "\033[0;32m$1\033[0m"; }
+error()   { echo -e "\033[0;31mError: $1\033[0m" >&2; exit 1; }
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    switch|boot|test)  ACTION="$1"; shift ;;
+    -n|--host)         FILTER_HOSTS+=("$2"); shift 2 ;;
+    -f|--flake)        FLAKE_URI="$2"; shift 2 ;;
+    -c|--config)       CONFIG_FILE="$2"; shift 2 ;;
+    --no-sudo)         USE_SUDO=false; shift ;;
+    --skip-build)      DO_BUILD=false; shift ;;
+    -h|--help)         usage; exit 0 ;;
+    *)                 error "Invalid argument '$1'" ;;
+  esac
+done
+
+command -v jq &> /dev/null || error "jq is not installed."
+[ -f "$CONFIG_FILE" ] || error "Config '$CONFIG_FILE' not found."
+
+BUILD_HOST=$(jq -r '.buildHost // "localhost"' "$CONFIG_FILE")
+[[ "$BUILD_HOST" =~ ^(127\.0\.0\.1|::1)$ ]] && BUILD_HOST="localhost"
+
+SSH_PORT=$(jq -r '.sshPort // "22"' "$CONFIG_FILE")
+export NIX_SSHOPTS="-p $SSH_PORT"
+
+mapfile -t ALL_ENTRIES < <(jq -r '.hosts[] | "\(.name) \(.address)"' "$CONFIG_FILE")
+[ ${#ALL_ENTRIES[@]} -eq 0 ] && error "No hosts defined in $CONFIG_FILE"
+
+# Filter hosts if -n was provided
+HOST_ENTRIES=()
+if [ ${#FILTER_HOSTS[@]} -gt 0 ]; then
+  for entry in "${ALL_ENTRIES[@]}"; do
+    read -r name _address <<< "$entry"
+    for filter in "${FILTER_HOSTS[@]}"; do
+      if [[ "$name" == "$filter" ]]; then
+        HOST_ENTRIES+=("$entry")
+        break
+      fi
+    done
+  done
+  # Check for unknown hosts
+  for filter in "${FILTER_HOSTS[@]}"; do
+    found=false
+    for entry in "${ALL_ENTRIES[@]}"; do
+      read -r name _ <<< "$entry"
+      [[ "$name" == "$filter" ]] && found=true && break
+    done
+    [[ "$found" == false ]] && error "Host '$filter' not found in $CONFIG_FILE"
+  done
+  [ ${#HOST_ENTRIES[@]} -eq 0 ] && error "No matching hosts found"
+else
+  HOST_ENTRIES=("${ALL_ENTRIES[@]}")
+fi
+
+echo "Action:      $ACTION"
+echo "Flake:       $FLAKE_URI"
+echo "Builder:     $BUILD_HOST"
+echo "SSH Port:    $SSH_PORT"
+echo "Hosts:       $(printf '%s ' "${HOST_ENTRIES[@]}" | sed 's/ [^ ]*//g; s/  */, /g')"
+
+if [ "$DO_BUILD" = true ]; then
+  _status "Building configurations..."
+  for entry in "${HOST_ENTRIES[@]}"; do
+    read -r name address <<< "$entry"
+    echo "------------------------------------------------"
+    echo "Building host '$name':"
+
+    CMD=("nixos-rebuild" "build" "--flake" "${FLAKE_URI}#${name}")
+    [[ "$BUILD_HOST" != "localhost" ]] && CMD+=("--build-host" "$BUILD_HOST")
+
+    "${CMD[@]}" || error "Build failed for $name"
+    success "Build for host '$name' successful."
+  done
+fi
+
+_status "Deploying to targets..."
+for entry in "${HOST_ENTRIES[@]}"; do
+  read -r name address <<< "$entry"
+  echo "------------------------------------------------"
+  echo "Deploying to host '$name' ($address):"
+
+  CMD=("nixos-rebuild" "$ACTION" "--flake" "${FLAKE_URI}#${name}" "--target-host" "$address")
+  [[ "$BUILD_HOST" != "localhost" ]] && CMD+=("--build-host" "$BUILD_HOST")
+  [[ "$USE_SUDO" = true ]] && CMD+=("--use-remote-sudo")
+
+  "${CMD[@]}" || error "Activation failed for $name"
+  success "Host '$name' updated."
+done
+
+success "Deployment complete."

deploy.json

@@ -0,0 +1,10 @@
+{
+  "sshPort": "2299",
+  "buildHost": "localhost",
+  "hosts": [
+    {
+      "name": "cryodev-main",
+      "address": "steffen@cryodev.xyz"
+    }
+  ]
+}

docs/deployment/cd.md

@@ -152,9 +152,8 @@ For hosts not using automated deployment:
 nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel
 
 # Deploy with nixos-rebuild
-nixos-rebuild switch --flake .#<hostname> \
+NIX_SSHOPTS="-p 2299" nixos-rebuild switch --flake .#<hostname> \
-  --target-host <user>@<hostname> --use-remote-sudo \
+  --target-host <user>@<hostname> --use-remote-sudo
-  --ssh-option="-p 2299"
 
 # Or using deploy-rs
 nix run github:serokell/deploy-rs -- .#<hostname>

docs/getting-started/first-install.md

@@ -22,26 +22,21 @@ Bei der Erstinstallation gibt es ein Henne-Ei-Problem:
 
 ## Schritt 1: Host-Konfiguration vorbereiten
 
-> Falls der Host bereits in `hosts/` und `flake.nix` existiert, ueberspringe 1.1-1.3.
+> Falls der Host bereits in `hosts/` und `flake.nix` existiert, ueberspringe 1.1-1.2.
 
-### 1.1 Template kopieren
+### 1.1 Host aus Template erstellen
 
 ```bash
-cp -r templates/generic-server hosts/<hostname>
+nix run .#create -- -t generic-server -n <hostname>
 ```
 
-### 1.2 Hostname setzen
+Das Script:
+- Kopiert das Template nach `hosts/<hostname>/`
+- Setzt den Hostname in `networking.nix`
+- Erstellt eine leere `secrets.yaml`
+- Fuegt die Dateien zu Git hinzu
 
-`hosts/<hostname>/networking.nix`:
+### 1.2 In flake.nix registrieren
-
-```nix
-{
-  networking.hostName = "<hostname>";
-  networking.domain = "cryodev.xyz";
-}
-```
-
-### 1.3 In flake.nix registrieren
 
 ```nix
 nixosConfigurations = {
@@ -49,6 +44,8 @@ nixosConfigurations = {
 };
 ```
 
+Ausserdem `hardware.nix` und `disks.sh` fuer die Zielhardware anpassen.
+
 ### 1.4 Services temporaer deaktivieren
 
 Alle Services, die SOPS-Secrets referenzieren, muessen fuer die Erstinstallation deaktiviert werden. Andernfalls schlaegt die Installation fehl, weil die Secrets noch nicht entschluesselt werden koennen.
@@ -252,9 +249,14 @@ Ebenso in `hosts/<hostname>/services/sops.nix` die Secrets-Definitionen wieder e
 ### 3.5 Deployen
 
 ```bash
-nixos-rebuild switch --flake .#<hostname> \
+nix run .#deploy -- -n <hostname>
-  --target-host <user>@<IP> --use-remote-sudo \
+```
-  --ssh-option="-p 2299"
+
+Dies nutzt die Konfiguration aus `deploy.json`. Alternativ manuell:
+
+```bash
+NIX_SSHOPTS="-p 2299" nixos-rebuild switch --flake .#<hostname> \
+  --target-host <user>@<IP> --use-remote-sudo
 ```
 
 ## Schritt 4: Platzhalter-Secrets ersetzen
@@ -291,9 +293,7 @@ Nachdem der Server mit Headscale und Forgejo laeuft, die Platzhalter durch echte
 5. **Erneut deployen**:
 
    ```bash
-   nixos-rebuild switch --flake .#<hostname> \
+   nix run .#deploy -- -n <hostname>
-     --target-host <user>@<IP> --use-remote-sudo \
-     --ssh-option="-p 2299"
    ```
 
 ## Naechste Schritte

docs/getting-started/new-client.md

@@ -244,9 +244,8 @@ Da Comin auf dem Pi läuft, wird er die neue Konfiguration automatisch pullen.
 Alternativ manuell:
 
 ```bash
-nixos-rebuild switch --flake .#neuer-pi \
+NIX_SSHOPTS="-p 2299" nixos-rebuild switch --flake .#neuer-pi \
-  --target-host <user>@<IP> --use-remote-sudo \
+  --target-host <user>@<IP> --use-remote-sudo
-  --ssh-option="-p 2299"
 ```
 
 ---

docs/getting-started/reinstall.md

@@ -142,9 +142,8 @@ sops updatekeys hosts/<hostname>/secrets.yaml
 Dann Konfiguration neu deployen:
 
 ```bash
-nixos-rebuild switch --flake .#<hostname> \
+NIX_SSHOPTS="-p 2299" nixos-rebuild switch --flake .#<hostname> \
-  --target-host <user>@<IP> --use-remote-sudo \
+  --target-host <user>@<IP> --use-remote-sudo
-  --ssh-option="-p 2299"
 ```
 
 ## Häufige Probleme

flake.nix

@@ -77,6 +77,8 @@
           };
         in
         {
+          create = mkApp "create";
+          deploy = mkApp "deploy";
           install = mkApp "install";
           rebuild = mkApp "rebuild";
         }

modules/nixos/headplane/default.nix

@@ -31,6 +31,14 @@ in
   config = mkIf cfg.enable {
     nixpkgs.overlays = [
       inputs.headplane.overlays.default
+      # Fix upstream pnpm-deps hash mismatch (https://github.com/tale/headplane)
+      (final: prev: {
+        headplane = prev.headplane.overrideAttrs (old: {
+          pnpmDeps = old.pnpmDeps.overrideAttrs {
+            outputHash = "sha256-lk/ezsrW6JHh5nXPSstqHUbaMTeOARBGZcBSoG1S5ns=";
+          };
+        });
+      })
     ];
 
     services.headplane = {

templates/generic-server/boot.nix

@@ -1,8 +1,7 @@
 {
-  boot = {
+  boot.loader.systemd-boot = {
-    loader = {
+    enable = true;
-      grub.enable = false;
+    configurationLimit = 10;
-      generic-extlinux-compatible.enable = true;
-    };
   };
+  boot.loader.efi.canTouchEfiVariables = true;
 }

templates/generic-server/hardware.nix

@@ -1,23 +1,44 @@
-{ pkgs, lib, ... }:
+{
+  config,
+  lib,
+  pkgs,
+  modulesPath,
+  ...
+}:
 
 {
-  boot = {
+  imports = [
-    kernelPackages = pkgs.linuxKernel.packages.linux_rpi4;
+    (modulesPath + "/installer/scan/not-detected.nix")
-    initrd.availableKernelModules = [
+  ];
-      "xhci_pci"
+
-      "usbhid"
+  boot.initrd.availableKernelModules = [
-      "usb_storage"
+    "ahci"
+    "nvme"
+    "sd_mod"
+    "usb_storage"
+    "xhci_pci"
+  ];
+  boot.initrd.kernelModules = [ ];
+  boot.kernelModules = [ ];
+  boot.extraModulePackages = [ ];
+
+  fileSystems."/" = {
+    device = "/dev/disk/by-label/ROOT";
+    fsType = "ext4";
+  };
+
+  fileSystems."/boot" = {
+    device = "/dev/disk/by-label/BOOT";
+    fsType = "vfat";
+    options = [
+      "fmask=0022"
+      "dmask=0022"
     ];
   };
 
-  fileSystems = {
+  swapDevices = [ { device = "/dev/disk/by-label/SWAP"; } ];
-    "/" = {
-      device = "/dev/disk/by-label/NIXOS_SD";
-      fsType = "ext4";
-      options = [ "noatime" ];
-    };
-  };
 
-  nixpkgs.hostPlatform = lib.mkDefault "aarch64-linux";
+  networking.useDHCP = lib.mkDefault true;
-  hardware.enableRedistributableFirmware = true;
+
+  nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
 }

templates/generic-server/networking.nix

@@ -1,4 +1,4 @@
 {
-  networking.hostName = "cryodev-pi";
+  networking.hostName = "HOSTNAME";
   networking.domain = "cryodev.xyz";
 }

templates/raspberry-pi/networking.nix

@@ -1,4 +1,4 @@
 {
-  networking.hostName = "cryodev-pi";
+  networking.hostName = "HOSTNAME";
   networking.domain = "cryodev.xyz";
 }