diff --git a/.github/workflows/test-docs-scripts-node-management.yaml b/.github/workflows/test-docs-scripts-node-management.yaml new file mode 100644 index 000000000..cf8ad3147 --- /dev/null +++ b/.github/workflows/test-docs-scripts-node-management.yaml @@ -0,0 +1,102 @@ +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-management.yaml +on: + push: + branches: [main, develop] + pull_request: + +jobs: + test-build-info-scripts: + name: Test Build Info 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 Docker on macOS + if: runner.os == 'macOS' + run: | + brew install docker + brew install colima + colima delete + 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.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 118808c5a..941893066 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -60,6 +60,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ([#1513](https://github.com/o1-labs/mina-rust/pull/1513)) - **scan_state**: refactorize `transaction_logic.rs` in smaller modules ([#1515](https://github.com/o1-labs/mina-rust/pull/1515)) +- **Website/CI**: run most commands from the page node management in CI after + moving them into scripts imported on the page + ([#1511](https://github.com/o1-labs/mina-rust/pull/1511)) ## v0.17.0 diff --git a/website/docs/node-operators/example-output/build-info-example.txt b/website/docs/node-operators/example-output/build-info-example.txt new file mode 100644 index 000000000..933800295 --- /dev/null +++ b/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 diff --git a/website/docs/node-operators/node-management.md b/website/docs/node-operators/node-management.mdx similarity index 58% rename from website/docs/node-operators/node-management.md rename to website/docs/node-operators/node-management.mdx index 54f8319db..e6676fc2d 100644 --- a/website/docs/node-operators/node-management.md +++ b/website/docs/node-operators/node-management.mdx @@ -4,6 +4,21 @@ title: Node Management description: Essential commands and tools for managing your Mina Rust node --- +import CodeBlock from "@theme/CodeBlock"; +import BuildInfoDocker from "!!raw-loader!./scripts/build-info-docker.sh"; +import BuildInfoDockerVersion from "!!raw-loader!./scripts/build-info-docker-version.sh"; +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 This guide covers essential commands and tools for managing your Mina Rust node, @@ -18,40 +33,35 @@ ensure you're running the correct version and to help with troubleshooting. To check the build information of your Docker-based node: -```bash -# Get build information -docker run --rm o1labs/mina-rust:latest build-info -``` + + {BuildInfoDocker} + 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 -``` + + {BuildInfoExample} + For a specific version: -```bash -docker run --rm o1labs/mina-rust:v0.17.0 build-info -``` + + {BuildInfoDockerVersion} + ### Using Native Binary If you've built from source or are running the binary directly: -```bash -# Get build information -mina build-info + + {BuildInfoNative} + -# Or with the full path if not in PATH -./target/release/mina build-info -``` +Or with the full path if not in PATH: + + + {BuildInfoNativePath} + ### Understanding Build Information @@ -69,13 +79,17 @@ The build info provides critical details: Always verify your node version after installation or updates: -```bash -# For Docker users -docker run --rm o1labs/mina-rust:latest build-info | grep "Version\|branch" +For Docker users: -# For native binary users -mina build-info | grep "Version\|branch" -``` + + {VerifyBuildInfoDocker} + + +For native binary users: + + + {VerifyBuildInfoNative} + ## Monitoring Your Node @@ -155,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/ -``` + + {BackupConfiguration} + ### 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 -``` + + {ManageFilePermissions} + -:::tip +:::tip Best Practice -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. ::: @@ -211,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) + + + {CreateEmptyEnv} + + +Or create with custom settings: + + + {CreateEnvCustom} + **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 -``` + + {CreateEnvArchive} + Regular node docker-compose files have default values, but the archive node docker-compose file requires the `.env` file with PostgreSQL configuration. @@ -253,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 - ``` + + + {CheckSystemResources} + + 2. Review node logs for warnings 3. Consider adjusting Docker resource limits diff --git a/website/docs/node-operators/scripts/backup-configuration.sh b/website/docs/node-operators/scripts/backup-configuration.sh new file mode 100644 index 000000000..19712e177 --- /dev/null +++ b/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/ diff --git a/website/docs/node-operators/scripts/build-info-docker-version.sh b/website/docs/node-operators/scripts/build-info-docker-version.sh new file mode 100755 index 000000000..c6cddd290 --- /dev/null +++ b/website/docs/node-operators/scripts/build-info-docker-version.sh @@ -0,0 +1,2 @@ +#!/bin/bash +docker run --rm o1labs/mina-rust:v0.17.0 build-info diff --git a/website/docs/node-operators/scripts/build-info-docker.sh b/website/docs/node-operators/scripts/build-info-docker.sh new file mode 100755 index 000000000..c80a49f22 --- /dev/null +++ b/website/docs/node-operators/scripts/build-info-docker.sh @@ -0,0 +1,2 @@ +#!/bin/bash +docker run --rm o1labs/mina-rust:latest build-info diff --git a/website/docs/node-operators/scripts/build-info-native-path.sh b/website/docs/node-operators/scripts/build-info-native-path.sh new file mode 100755 index 000000000..c0d8d9e20 --- /dev/null +++ b/website/docs/node-operators/scripts/build-info-native-path.sh @@ -0,0 +1,2 @@ +#!/bin/bash +./target/release/mina build-info diff --git a/website/docs/node-operators/scripts/build-info-native.sh b/website/docs/node-operators/scripts/build-info-native.sh new file mode 100755 index 000000000..20936722d --- /dev/null +++ b/website/docs/node-operators/scripts/build-info-native.sh @@ -0,0 +1,2 @@ +#!/bin/bash +mina build-info diff --git a/website/docs/node-operators/scripts/check-build-info-format.sh b/website/docs/node-operators/scripts/check-build-info-format.sh new file mode 100644 index 000000000..9c0d7bf27 --- /dev/null +++ b/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" diff --git a/website/docs/node-operators/scripts/check-system-resources.sh b/website/docs/node-operators/scripts/check-system-resources.sh new file mode 100644 index 000000000..26ef207c6 --- /dev/null +++ b/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 diff --git a/website/docs/node-operators/scripts/create-empty-env.sh b/website/docs/node-operators/scripts/create-empty-env.sh new file mode 100644 index 000000000..7ae9caf30 --- /dev/null +++ b/website/docs/node-operators/scripts/create-empty-env.sh @@ -0,0 +1,2 @@ +#!/bin/bash +touch .env diff --git a/website/docs/node-operators/scripts/create-env-archive.sh b/website/docs/node-operators/scripts/create-env-archive.sh new file mode 100644 index 000000000..940295b10 --- /dev/null +++ b/website/docs/node-operators/scripts/create-env-archive.sh @@ -0,0 +1,7 @@ +#!/bin/bash +cat > .env << EOF +POSTGRES_PASSWORD=mina +PG_PORT=5432 +PG_DB=archive +MINA_RUST_TAG=latest +EOF diff --git a/website/docs/node-operators/scripts/create-env-custom.sh b/website/docs/node-operators/scripts/create-env-custom.sh new file mode 100644 index 000000000..3cadf1e6d --- /dev/null +++ b/website/docs/node-operators/scripts/create-env-custom.sh @@ -0,0 +1,9 @@ +#!/bin/bash +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 diff --git a/website/docs/node-operators/scripts/manage-file-permissions.sh b/website/docs/node-operators/scripts/manage-file-permissions.sh new file mode 100644 index 000000000..72e5758e1 --- /dev/null +++ b/website/docs/node-operators/scripts/manage-file-permissions.sh @@ -0,0 +1,9 @@ +#!/bin/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 diff --git a/website/docs/node-operators/scripts/verify-build-info-docker.sh b/website/docs/node-operators/scripts/verify-build-info-docker.sh new file mode 100755 index 000000000..0e5fa0e4b --- /dev/null +++ b/website/docs/node-operators/scripts/verify-build-info-docker.sh @@ -0,0 +1,2 @@ +#!/bin/bash +docker run --rm o1labs/mina-rust:latest build-info | grep "Version\|branch" diff --git a/website/docs/node-operators/scripts/verify-build-info-native.sh b/website/docs/node-operators/scripts/verify-build-info-native.sh new file mode 100755 index 000000000..699acaf50 --- /dev/null +++ b/website/docs/node-operators/scripts/verify-build-info-native.sh @@ -0,0 +1,2 @@ +#!/bin/bash +mina build-info | grep "Version\|branch"