feat: add config file support to configure docker images

.gitignore

@@ -4,6 +4,9 @@ data
 *.old
 .DS_Store
 
+# User configuration files
+user-config.yml
+
 # Generated genesis files (created by generate-genesis.sh)
 config.yaml
 validators.yaml

README.md

@@ -413,6 +413,41 @@ node_docker="--platform linux/amd64 qdrvm/qlean-mini:dd67521 \
 node_setup="docker"
 ```
 
+### User Configuration Overrides (`user-config.yml`)
+
+You can override the Docker image or run mode (docker/binary) for individual nodes without modifying any tracked files. This is useful for testing custom builds or switching a node to binary mode for local debugging.
+
+**Setup:**
+```sh
+# Copy the example file
+cp user-config.yml.example user-config.yml
+
+# Edit to override specific nodes
+```
+
+**Format** — specify only the nodes you want to override:
+```yaml
+zeam_0:
+  run_mode: docker
+  docker_image: blockblaz/zeam:custom-tag
+
+ream_0:
+  run_mode: binary
+```
+
+**Fields:**
+| Field | Description |
+|-------|-------------|
+| `run_mode` | `"docker"` or `"binary"` — overrides the default set in the client-cmd script |
+| `docker_image` | Docker image to use (only applies when `run_mode` is `docker`) |
+
+**How it works:**
+- `user-config.yml` is auto-detected from the project root during `spin-node.sh` execution
+- Overrides are applied per-node after sourcing the client-cmd script, right before spinning the node
+- If `run_mode` is set to `binary`, `docker_image` is ignored
+- Nodes not listed in the file use their defaults from `client-cmds/<client>-cmd.sh`
+- The file is gitignored so your local overrides won't affect others
+
 ## Key Management
 
 ### Key Lifetime

spin-node.sh

@@ -342,6 +342,34 @@ for item in "${spin_nodes[@]}"; do
   echo "$sourceCmd"
   eval $sourceCmd
 
+  # Apply user-config.yml overrides (run_mode, docker_image) if file exists
+  user_config="$scriptDir/user-config.yml"
+  if [ -f "$user_config" ]; then
+    # Override run_mode if specified for this node (check first since it affects docker_image)
+    user_run_mode=$(yq eval ".$item.run_mode // \"\"" "$user_config" 2>/dev/null)
+    if [ -n "$user_run_mode" ] && [ "$user_run_mode" != "null" ]; then
+      if [ "$user_run_mode" == "docker" ] || [ "$user_run_mode" == "binary" ]; then
+        node_setup="$user_run_mode"
+        echo "  user-config.yml: overriding run_mode for $item: $user_run_mode"
+      else
+        echo "  user-config.yml: ignoring unknown run_mode '$user_run_mode' for $item (expected: docker or binary)"
+      fi
+    fi
+
+    # Override docker image if specified for this node (only applies in docker mode)
+    if [ "$node_setup" == "docker" ]; then
+      user_docker_image=$(yq eval ".$item.docker_image // \"\"" "$user_config" 2>/dev/null)
+      if [ -n "$user_docker_image" ] && [ "$user_docker_image" != "null" ]; then
+        # Replace the image in node_docker string (first word matching image:tag pattern)
+        original_image=$(echo "$node_docker" | grep -oE '[a-zA-Z0-9._/-]+:[a-zA-Z0-9._-]+' | head -1)
+        if [ -n "$original_image" ]; then
+          node_docker="${node_docker/$original_image/$user_docker_image}"
+          echo "  user-config.yml: overriding docker_image for $item: $user_docker_image"
+        fi
+      fi
+    fi
+  fi
+
   # spin nodes
   if [ "$node_setup" == "binary" ]
   then

user-config.yml.example

@@ -0,0 +1,14 @@
+# User configuration overrides (auto-detected from project root)
+# Copy this file to user-config.yml and customize.
+# Only specify nodes you want to override — others use defaults from client-cmd scripts.
+#
+# Fields:
+#   run_mode: "docker" or "binary" (default: whatever client-cmd.sh sets)
+#   docker_image: Override the Docker image for this node
+
+# zeam_0:
+#   run_mode: docker
+#   docker_image: blockblaz/zeam:custom-tag
+#
+# ream_0:
+#   run_mode: binary