Website/node-management: move example outputs to files and verify in CI

Move build-info example output and management script examples into
separate files that are imported by the documentation. Add CI
verification to ensure scripts work correctly and output matches
documented examples.

Changes:
- Move build-info example output to build-info-example.txt
- Create check-build-info-format.sh to verify output format
- Combine backup scripts into backup-configuration.sh
- Create manage-file-permissions.sh (combined from 3 separate scripts)
- Create check-system-resources.sh
- Create .env file creation scripts (empty, custom, archive variants)
- Add test-management-scripts job to CI workflow
- Add gh act run command comment to workflow
- Update documentation to use CodeBlock imports for all scripts

All scripts are tested in CI on ubuntu-22.04, ubuntu-24.04, and
macos-latest to ensure they execute correctly.

Author: dannywillems

.github/workflows/test-docs-scripts-node-operators.yaml

@@ -2,6 +2,7 @@ name: Test Documentation Scripts - Node Operators
 
 # Test node-operators documentation scripts to ensure they work correctly
 # These scripts demonstrate node management commands for users
+# Run locally: gh act -W .github/workflows/test-docs-scripts-node-operators.yaml
 on:
   push:
     branches: [main, develop]
@@ -19,18 +20,82 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v5
 
-      - name: Make scripts executable
+      - name: Install Docker on macOS
+        if: runner.os == 'macOS'
         run: |
-          chmod +x website/docs/node-operators/scripts/*.sh
+          brew install docker
+          brew install colima
+          colima start
 
       - name: Test build-info-docker script
         run: |
           bash website/docs/node-operators/scripts/build-info-docker.sh
 
       - name: Test build-info-docker-version script
         run: |
-          bash website/docs/node-operators/scripts/build-info-docker-version.sh
+          bash website/docs/node-operators/scripts/build-info-docker.sh
 
       - name: Test verify-build-info-docker script
         run: |
           bash website/docs/node-operators/scripts/verify-build-info-docker.sh
+
+      - name: Check build-info output format matches example
+        run: |
+          bash website/docs/node-operators/scripts/check-build-info-format.sh
+
+  test-management-scripts:
+    name: Test Management Scripts (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-22.04, ubuntu-24.04, macos-latest]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Install timeout on macOS
+        if: runner.os == 'macOS'
+        run: |
+          brew install coreutils
+          sudo ln -s /opt/homebrew/bin/gtimeout /usr/local/bin/timeout || sudo ln -s /usr/local/bin/gtimeout /usr/local/bin/timeout
+
+      - name: Create test environment
+        run: |
+          mkdir -p mina-workdir/producer-key
+          echo "test-key" > mina-workdir/producer-key/test.key
+          mkdir -p ~/mina-backup
+
+      - name: Test backup-configuration script
+        run: |
+          bash website/docs/node-operators/scripts/backup-configuration.sh
+          test -f ~/mina-backup/producer-key/test.key
+          test -f mina-backup-$(date +%Y%m%d).tar.gz
+
+      - name: Test manage-file-permissions script
+        run: |
+          bash website/docs/node-operators/scripts/manage-file-permissions.sh
+
+      - name: Test check-system-resources script
+        run: |
+          timeout 5 bash website/docs/node-operators/scripts/check-system-resources.sh || true
+
+      - name: Test create-empty-env script
+        run: |
+          cd $(mktemp -d)
+          bash $GITHUB_WORKSPACE/website/docs/node-operators/scripts/create-empty-env.sh
+          test -f .env
+
+      - name: Test create-env-custom script
+        run: |
+          cd $(mktemp -d)
+          bash $GITHUB_WORKSPACE/website/docs/node-operators/scripts/create-env-custom.sh
+          test -f .env
+          grep -q "MINA_RUST_TAG=latest" .env
+
+      - name: Test create-env-archive script
+        run: |
+          cd $(mktemp -d)
+          bash $GITHUB_WORKSPACE/website/docs/node-operators/scripts/create-env-archive.sh
+          test -f .env
+          grep -q "POSTGRES_PASSWORD=mina" .env

website/docs/node-operators/example-output/build-info-example.txt

@@ -0,0 +1,7 @@
+Version:       0341fff
+Build time:    2025-09-10T18:11:40.953050700Z
+Commit SHA:    0341fffedba4900371504ad4b30853674960a209
+Commit time:   2025-09-10T19:30:31.000000000+02:00
+Commit branch: release/v0.17.0
+Rustc channel: stable
+Rustc version: 1.84.1

website/docs/node-operators/node-management.mdx

@@ -11,6 +11,13 @@ import BuildInfoNative from "!!raw-loader!./scripts/build-info-native.sh";
 import BuildInfoNativePath from "!!raw-loader!./scripts/build-info-native-path.sh";
 import VerifyBuildInfoDocker from "!!raw-loader!./scripts/verify-build-info-docker.sh";
 import VerifyBuildInfoNative from "!!raw-loader!./scripts/verify-build-info-native.sh";
+import BuildInfoExample from "!!raw-loader!./example-output/build-info-example.txt";
+import BackupConfiguration from "!!raw-loader!./scripts/backup-configuration.sh";
+import ManageFilePermissions from "!!raw-loader!./scripts/manage-file-permissions.sh";
+import CheckSystemResources from "!!raw-loader!./scripts/check-system-resources.sh";
+import CreateEmptyEnv from "!!raw-loader!./scripts/create-empty-env.sh";
+import CreateEnvCustom from "!!raw-loader!./scripts/create-env-custom.sh";
+import CreateEnvArchive from "!!raw-loader!./scripts/create-env-archive.sh";
 
 # Node Management
 
@@ -32,15 +39,9 @@ To check the build information of your Docker-based node:
 
 Example output:
 
-```
-Version:       0341fff
-Build time:    2025-09-10T18:11:40.953050700Z
-Commit SHA:    0341fffedba4900371504ad4b30853674960a209
-Commit time:   2025-09-10T19:30:31.000000000+02:00
-Commit branch: release/v0.17.0
-Rustc channel: stable
-Rustc version: 1.84.1
-```
+<CodeBlock language="text" title="example-output/build-info-example.txt">
+  {BuildInfoExample}
+</CodeBlock>
 
 For a specific version:
 
@@ -168,36 +169,25 @@ docker compose up -d --force-recreate
 
 Always backup your keys and configuration:
 
-```bash
-# Backup producer key (if running block producer)
-cp -r mina-workdir/producer-key ~/mina-backup/
-
-# Backup entire working directory
-tar -czf mina-backup-$(date +%Y%m%d).tar.gz mina-workdir/
-```
+<CodeBlock language="bash" title="scripts/backup-configuration.sh">
+  {BackupConfiguration}
+</CodeBlock>
 
 ### Managing File Permissions
 
 Docker containers often run as root, creating files owned by root on your host:
 
-```bash
-# Check file ownership
-ls -la mina-workdir/
-
-# Fix ownership for all files in mina-workdir
-sudo chown -R $(id -u):$(id -g) mina-workdir/
-
-# Set appropriate permissions for the producer key
-chmod 600 mina-workdir/producer-key
-```
+<CodeBlock language="bash" title="scripts/manage-file-permissions.sh">
+  {ManageFilePermissions}
+</CodeBlock>
 
 <!-- prettier-ignore-start -->
 
 :::tip Best Practice
 
-Always fix file ownership after Docker operations to ensure your
-local user can properly access, backup, and manage the files. This is especially
-important for sensitive files like producer keys.
+Always fix file ownership after Docker operations to ensure your local user can
+properly access, backup, and manage the files. This is especially important for
+sensitive files like producer keys.
 
 :::
 
@@ -224,32 +214,23 @@ environment variables:
 
 **For regular node and block producer:**
 
-```bash
-# Quick fix: Create an empty .env file (has defaults)
-touch .env
-
-# Or create with custom settings
-cat > .env << EOF
-MINA_RUST_TAG=latest
-MINA_FRONTEND_TAG=latest
-MINA_LIBP2P_PORT=8302
-MINA_LIBP2P_EXTERNAL_IP=
-MINA_PRIVKEY_PASS=
-COINBASE_RECEIVER=
-EOF
-```
+Quick fix: Create an empty .env file (has defaults)
+
+<CodeBlock language="bash" title="scripts/create-empty-env.sh">
+  {CreateEmptyEnv}
+</CodeBlock>
+
+Or create with custom settings:
+
+<CodeBlock language="bash" title="scripts/create-env-custom.sh">
+  {CreateEnvCustom}
+</CodeBlock>
 
 **For archive node (required):**
 
-```bash
-# Archive node requires specific database settings
-cat > .env << EOF
-POSTGRES_PASSWORD=mina
-PG_PORT=5432
-PG_DB=archive
-MINA_RUST_TAG=latest
-EOF
-```
+<CodeBlock language="bash" title="scripts/create-env-archive.sh">
+  {CreateEnvArchive}
+</CodeBlock>
 
 Regular node docker-compose files have default values, but the archive node
 docker-compose file requires the `.env` file with PostgreSQL configuration.
@@ -266,11 +247,11 @@ docker-compose file requires the `.env` file with PostgreSQL configuration.
 ### Performance Issues
 
 1. Check system resources:
-   ```bash
-   free -h
-   df -h
-   docker stats
-   ```
+
+   <CodeBlock language="bash" title="scripts/check-system-resources.sh">
+     {CheckSystemResources}
+   </CodeBlock>
+
 2. Review node logs for warnings
 3. Consider adjusting Docker resource limits
 

website/docs/node-operators/scripts/backup-configuration.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# Backup producer key (if running block producer)
+cp -r mina-workdir/producer-key ~/mina-backup/
+
+# Backup entire working directory
+tar -czf "mina-backup-$(date +%Y%m%d).tar.gz" mina-workdir/

website/docs/node-operators/scripts/build-info-docker-version.sh

@@ -1 +1,2 @@
+#!/bin/bash
 docker run --rm o1labs/mina-rust:v0.17.0 build-info

website/docs/node-operators/scripts/build-info-docker.sh

@@ -1 +1,2 @@
+#!/bin/bash
 docker run --rm o1labs/mina-rust:latest build-info

website/docs/node-operators/scripts/build-info-native-path.sh

@@ -1 +1,2 @@
+#!/bin/bash
 ./target/release/mina build-info

website/docs/node-operators/scripts/build-info-native.sh

@@ -1 +1,2 @@
+#!/bin/bash
 mina build-info

website/docs/node-operators/scripts/check-build-info-format.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Verify that build-info output format matches the documented example
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXAMPLE_FILE="$SCRIPT_DIR/../example-output/build-info-example.txt"
+
+# Get actual build-info output
+echo "Getting build-info output..."
+ACTUAL_OUTPUT=$(docker run --rm o1labs/mina-rust:latest build-info)
+
+# Extract field names from example file (everything before the colon)
+echo "Checking that all expected fields are present..."
+EXPECTED_FIELDS=(
+  "Version"
+  "Build time"
+  "Commit SHA"
+  "Commit time"
+  "Commit branch"
+  "Rustc channel"
+  "Rustc version"
+)
+
+# Check that each expected field exists in the actual output
+MISSING_FIELDS=()
+for field in "${EXPECTED_FIELDS[@]}"; do
+  if ! echo "$ACTUAL_OUTPUT" | grep -q "^${field}:"; then
+    MISSING_FIELDS+=("$field")
+  fi
+done
+
+if [ ${#MISSING_FIELDS[@]} -gt 0 ]; then
+  echo "ERROR: Missing fields in build-info output:"
+  printf '  - %s\n' "${MISSING_FIELDS[@]}"
+  echo ""
+  echo "Expected fields:"
+  printf '  - %s\n' "${EXPECTED_FIELDS[@]}"
+  echo ""
+  echo "Actual output:"
+  echo "$ACTUAL_OUTPUT"
+  exit 1
+fi
+
+# Verify field order matches the example
+echo "Checking that field order matches the example..."
+EXAMPLE_ORDER=$(grep -o '^[^:]*:' "$EXAMPLE_FILE")
+ACTUAL_ORDER=$(echo "$ACTUAL_OUTPUT" | grep -o '^[^:]*:')
+
+if [ "$EXAMPLE_ORDER" != "$ACTUAL_ORDER" ]; then
+  echo "ERROR: Field order doesn't match the example"
+  echo ""
+  echo "Expected order:"
+  echo "$EXAMPLE_ORDER"
+  echo ""
+  echo "Actual order:"
+  echo "$ACTUAL_ORDER"
+  exit 1
+fi
+
+echo "✓ Build-info format matches the documented example"
+echo ""
+echo "Actual output:"
+echo "$ACTUAL_OUTPUT"

website/docs/node-operators/scripts/check-system-resources.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+if command -v free &> /dev/null; then
+  free -h
+else
+  vm_stat | perl -ne '/page size of (\d+)/ and $size=$1; /Pages\s+([^:]+)[^\d]+(\d+)/ and printf("%-16s % 16.2f Mi\n", "$1:", $2 * $size / 1048576);'
+fi
+df -h
+docker stats