feat(deployment): add configurable NixOS deployment modes

AGENTS.md

@@ -86,19 +86,27 @@ just up-nix                 # update nixpkgs-related inputs
 ### Local deploy commands
 
 ```bash
-just local                  # deploy config for current hostname
+just local                  # Linux: switch config for current hostname
-just local debug            # same with verbose/debug mode
+just local boot             # Linux: set the next boot config without switching
-just niri                   # deploy "<hostname>-niri" on Linux
+just local switch debug     # Linux: switch with detailed output
-just niri debug             # debug mode
+just local boot debug       # Linux: boot mode with detailed output
+just niri                   # Linux: switch "<hostname>-niri"
+just niri boot              # Linux: set "<hostname>-niri" for the next boot
+just niri switch debug      # Linux: switch niri config with detailed output
+just local debug            # macOS: switch with detailed output
 ```
 
 ### Remote deploy commands (colmena)
 
 ```bash
-just col <tag>              # deploy nodes matching tag
+just col <tag>              # switch nodes matching tag
-just lab                    # deploy all kubevirt nodes
+just col <tag> boot         # set matching nodes' next boot configuration
-just k3s-prod               # deploy k3s production nodes
+just lab                    # switch all kubevirt nodes
-just k3s-test               # deploy k3s test nodes
+just lab boot               # set all kubevirt nodes for the next boot
+just k3s-prod               # switch k3s production nodes
+just k3s-prod boot          # set k3s production nodes for the next boot
+just k3s-test               # switch k3s test nodes
+just k3s-test boot          # set k3s test nodes for the next boot
 ```
 
 ### Useful direct commands

Justfile

@@ -122,18 +122,18 @@ override-pkgs hash:
 # Deploy the nixosConfiguration by hostname match
 [linux]
 [group('homelab')]
-local mode="default":
+local mode="switch" verbosity="normal":
   #!/usr/bin/env nu
   use {{utils_nu}} *;
-  nixos-switch (hostname) {{mode}}
+  nixos-switch (hostname) {{mode}} {{verbosity}}
 
 # Deploy the niri nixosConfiguration by hostname match
 [linux]
 [group('desktop')]
-niri mode="default":
+niri mode="switch" verbosity="normal":
   #!/usr/bin/env nu
   use {{utils_nu}} *;
-  nixos-switch $"(hostname)-niri" {{mode}}
+  nixos-switch $"(hostname)-niri" {{mode}} {{verbosity}}
 
 ############################################################################
 #
@@ -162,11 +162,11 @@ darwin-rollback:
 # Deploy the darwinConfiguration by hostname match
 [macos]
 [group('desktop')]
-local mode="default": 
+local verbosity="normal":
   #!/usr/bin/env nu
   use {{utils_nu}} *;
-  darwin-build (hostname) {{mode}};
+  darwin-build (hostname) {{verbosity}};
-  darwin-switch (hostname) {{mode}}
+  darwin-switch (hostname) {{verbosity}}
 
 
 # Reset launchpad to force it to reindex Applications
@@ -185,37 +185,37 @@ reset-launchpad:
 # Remote deployment via colmena
 [linux]
 [group('homelab')]
-col tag:
+col tag mode="switch":
-  colmena apply --on '@{{tag}}' --verbose --show-trace
+  colmena apply {{mode}} --on '@{{tag}}' --verbose --show-trace
 
 # Build and upload a vm image
 [linux]
 [group('homelab')]
-upload-vm name mode="default":
+upload-vm name verbosity="normal":
   #!/usr/bin/env nu
   use {{utils_nu}} *;
-  upload-vm {{name}} {{mode}}
+  upload-vm {{name}} {{verbosity}}
 
 # Deploy all the KubeVirt nodes(Physical machines running KubeVirt)
 [linux]
 [group('homelab')]
-lab:
+lab mode="switch":
-  colmena apply --on '@virt-*' --verbose --show-trace
+  colmena apply {{mode}} --on '@virt-*' --verbose --show-trace
 
 [linux]
 [group('homelab')]
-shoryu:
+shoryu mode="switch":
-  colmena apply --on '@kubevirt-shoryu' --verbose --show-trace
+  colmena apply {{mode}} --on '@kubevirt-shoryu' --verbose --show-trace
 
 [linux]
 [group('homelab')]
-shushou:
+shushou mode="switch":
-  colmena apply --on '@kubevirt-shushou' --verbose --show-trace
+  colmena apply {{mode}} --on '@kubevirt-shushou' --verbose --show-trace
 
 [linux]
 [group('homelab')]
-youko:
+youko mode="switch":
-  colmena apply --on '@kubevirt-youko' --verbose --show-trace
+  colmena apply {{mode}} --on '@kubevirt-youko' --verbose --show-trace
 
 ############################################################################
 #
@@ -226,27 +226,27 @@ youko:
 # Build and upload a vm image
 [linux]
 [group('homelab')]
-upload-idols mode="default":
+upload-idols verbosity="normal":
   #!/usr/bin/env nu
   use {{utils_nu}} *; 
-  upload-vm aquamarine {{mode}}
+  upload-vm aquamarine {{verbosity}}
-  upload-vm ruby {{mode}}
+  upload-vm ruby {{verbosity}}
-  upload-vm kana {{mode}}
+  upload-vm kana {{verbosity}}
 
 [linux]
 [group('homelab')]
-aqua:
+aqua mode="switch":
-  colmena apply --on '@aqua' --verbose --show-trace
+  colmena apply {{mode}} --on '@aqua' --verbose --show-trace
 
 [linux]
 [group('homelab')]
-ruby:
+ruby mode="switch":
-  colmena apply --on '@ruby' --verbose --show-trace
+  colmena apply {{mode}} --on '@ruby' --verbose --show-trace
 
 [linux]
 [group('homelab')]
-kana:
+kana mode="switch":
-  colmena apply --on '@kana' --verbose --show-trace
+  colmena apply {{mode}} --on '@kana' --verbose --show-trace
 
 ############################################################################
 #
@@ -257,34 +257,34 @@ kana:
 # Build and upload a vm image
 [linux]
 [group('homelab')]
-upload-k3s-prod mode="default":
+upload-k3s-prod verbosity="normal":
   #!/usr/bin/env nu
   use {{utils_nu}} *; 
-  upload-vm k3s-prod-1-master-1 {{mode}}; 
+  upload-vm k3s-prod-1-master-1 {{verbosity}};
-  upload-vm k3s-prod-1-master-2 {{mode}}; 
+  upload-vm k3s-prod-1-master-2 {{verbosity}};
-  upload-vm k3s-prod-1-master-3 {{mode}}; 
+  upload-vm k3s-prod-1-master-3 {{verbosity}};
-  upload-vm k3s-prod-1-worker-1 {{mode}}; 
+  upload-vm k3s-prod-1-worker-1 {{verbosity}};
-  upload-vm k3s-prod-1-worker-2 {{mode}}; 
+  upload-vm k3s-prod-1-worker-2 {{verbosity}};
-  upload-vm k3s-prod-1-worker-3 {{mode}};
+  upload-vm k3s-prod-1-worker-3 {{verbosity}};
 
 [linux]
 [group('homelab')]
-upload-k3s-test mode="default":
+upload-k3s-test verbosity="normal":
   #!/usr/bin/env nu
   use {{utils_nu}} *; 
-  upload-vm k3s-test-1-master-1 {{mode}}; 
+  upload-vm k3s-test-1-master-1 {{verbosity}};
-  upload-vm k3s-test-1-master-2 {{mode}}; 
+  upload-vm k3s-test-1-master-2 {{verbosity}};
-  upload-vm k3s-test-1-master-3 {{mode}};
+  upload-vm k3s-test-1-master-3 {{verbosity}};
 
 [linux]
 [group('homelab')]
-k3s-prod:
+k3s-prod mode="switch":
-  colmena apply --on '@k3s-prod-*' --verbose --show-trace
+  colmena apply {{mode}} --on '@k3s-prod-*' --verbose --show-trace
 
 [linux]
 [group('homelab')]
-k3s-test:
+k3s-test mode="switch":
-  colmena apply --on '@k3s-test-*' --verbose --show-trace
+  colmena apply {{mode}} --on '@k3s-test-*' --verbose --show-trace
 
 # =================================================
 #

README.md

@@ -118,11 +118,22 @@ For NixOS:
 # deploy one of the configuration based on the hostname
 sudo nixos-rebuild switch --flake .#ai-niri
 
+# Deploy the nixosConfiguration matching the hostname immediately
+just local
+
+# Set it as the next boot configuration without switching immediately
+just local boot
+
+# Deploy with detailed output; use `boot debug` to combine both options
+just local switch debug
+
 # Deploy the niri nixosConfiguration by hostname match
 just niri
 
-# or we can deploy with details
+# The niri recipe accepts the same mode and verbosity arguments
-just niri debug
+just niri boot
+just niri switch debug
+just niri boot debug
 ```
 
 For macOS:
@@ -138,7 +149,7 @@ nix-shell -p just nushell
 # Deploy the darwinConfiguration by hostname match
 just local
 
-# deploy with details
+# Deploy with details (macOS has no switch/boot mode argument)
 just local debug
 ```
 

Virtual-Machine.md

@@ -20,6 +20,9 @@ commands:
 just col aquamarine
 just col kubevirt-shoryu
 just col k3s-test-1-master-1
+
+# Set a configuration for the next boot instead of switching immediately
+just col aquamarine boot
 ```
 
 If you're not familiar with remote deployment, please read this tutorial first:

utils.nu

@@ -7,17 +7,23 @@ def repeat-str [s: string, n: int] {
 export def nixos-switch [
     name: string
     mode: string
+    verbosity: string
 ] {
-    print $"nixos-switch '($name)' in '($mode)' mode..."
+    if $mode not-in ["switch" "boot"] {
+        error make { msg: $"unsupported deployment mode '($mode)'; expected switch or boot" }
+    }
+    if $verbosity not-in ["normal" "debug"] {
+        error make { msg: $"unsupported verbosity '($verbosity)'; expected normal or debug" }
+    }
+
+    print $"nixos-switch '($name)' in '($mode)' mode with '($verbosity)' verbosity..."
     print (repeat-str "=" 50)
-    if "debug" == $mode {
+    if $verbosity == "debug" {
         # show details via nix-output-monitor
         nom build $".#nixosConfigurations.($name).config.system.build.toplevel" --accept-flake-config --show-trace --verbose
-        nixos-rebuild switch --sudo --flake $".#($name)" --accept-flake-config --show-trace --verbose
+        nixos-rebuild $mode --sudo --flake $".#($name)" --accept-flake-config --show-trace --verbose
-    } else if "boot" == $mode {
-        nixos-rebuild boot --sudo --flake $".#($name)" --accept-flake-config
     } else {
-        nixos-rebuild switch --sudo --flake $".#($name)" --accept-flake-config
+        nixos-rebuild $mode --sudo --flake $".#($name)" --accept-flake-config
     }
 }
 
@@ -38,12 +44,12 @@ export def make-editable [
 
 export def darwin-build [
     name: string
-    mode: string
+    verbosity: string
 ] {
-    print $"darwin-build '($name)' in '($mode)' mode..."
+    print $"darwin-build '($name)' with '($verbosity)' verbosity..."
     print (repeat-str "=" 50)
     let target = $".#darwinConfigurations.($name).system"
-    if "debug" == $mode {
+    if "debug" == $verbosity {
         nom build $target --extra-experimental-features "nix-command flakes"  --show-trace --verbose
     } else {
         nix build $target --extra-experimental-features "nix-command flakes"
@@ -52,11 +58,11 @@ export def darwin-build [
 
 export def darwin-switch [
     name: string
-    mode: string
+    verbosity: string
 ] {
-    print $"darwin-switch '($name)' in '($mode)' mode..."
+    print $"darwin-switch '($name)' with '($verbosity)' verbosity..."
     print (repeat-str "=" 50)
-    if "debug" == $mode {
+    if "debug" == $verbosity {
         sudo -E ./result/sw/bin/darwin-rebuild switch --flake $".#($name)" --show-trace --verbose
     } else {
         sudo -E ./result/sw/bin/darwin-rebuild switch --flake $".#($name)"
@@ -72,12 +78,12 @@ export def darwin-rollback [] {
 # Build and upload a VM image
 export def upload-vm [
     name: string
-    mode: string
+    verbosity: string
 ] {
-    print $"upload-vm '($name)' in '($mode)' mode..."
+    print $"upload-vm '($name)' with '($verbosity)' verbosity..."
     print (repeat-str "=" 50)
     let target = $".#($name)"
-    if "debug" == $mode {
+    if "debug" == $verbosity {
         nom build $target --show-trace --verbose
     } else {
         nix build $target