Skip to content

Commit 149bac7

Browse files
dannywillemsdannywillems
committed
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.
1 parent efe85a1 commit 149bac7

File tree

10 files changed

+196
-61
lines changed

10 files changed

+196
-61
lines changed

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

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ name: Test Documentation Scripts - Node Operators
22

33
# Test node-operators documentation scripts to ensure they work correctly
44
# These scripts demonstrate node management commands for users
5+
# Run locally: gh act -W .github/workflows/test-docs-scripts-node-operators.yaml
56
on:
67
push:
78
branches: [main, develop]
@@ -19,10 +20,6 @@ jobs:
1920
- name: Checkout repository
2021
uses: actions/checkout@v5
2122

22-
- name: Make scripts executable
23-
run: |
24-
chmod +x website/docs/node-operators/scripts/*.sh
25-
2623
- name: Test build-info-docker script
2724
run: |
2825
bash website/docs/node-operators/scripts/build-info-docker.sh
@@ -34,3 +31,58 @@ jobs:
3431
- name: Test verify-build-info-docker script
3532
run: |
3633
bash website/docs/node-operators/scripts/verify-build-info-docker.sh
34+
35+
- name: Check build-info output format matches example
36+
run: |
37+
bash website/docs/node-operators/scripts/check-build-info-format.sh
38+
39+
test-management-scripts:
40+
name: Test Management Scripts (${{ matrix.os }})
41+
runs-on: ${{ matrix.os }}
42+
strategy:
43+
matrix:
44+
os: [ubuntu-22.04, ubuntu-24.04, macos-latest]
45+
46+
steps:
47+
- name: Checkout repository
48+
uses: actions/checkout@v5
49+
50+
- name: Create test environment
51+
run: |
52+
mkdir -p mina-workdir/producer-key
53+
echo "test-key" > mina-workdir/producer-key/test.key
54+
mkdir -p ~/mina-backup
55+
56+
- name: Test backup-configuration script
57+
run: |
58+
bash website/docs/node-operators/scripts/backup-configuration.sh
59+
test -f ~/mina-backup/producer-key/test.key
60+
test -f mina-backup-$(date +%Y%m%d).tar.gz
61+
62+
- name: Test manage-file-permissions script
63+
run: |
64+
bash website/docs/node-operators/scripts/manage-file-permissions.sh
65+
66+
- name: Test check-system-resources script
67+
run: |
68+
timeout 5 bash website/docs/node-operators/scripts/check-system-resources.sh || true
69+
70+
- name: Test create-empty-env script
71+
run: |
72+
cd $(mktemp -d)
73+
bash $GITHUB_WORKSPACE/website/docs/node-operators/scripts/create-empty-env.sh
74+
test -f .env
75+
76+
- name: Test create-env-custom script
77+
run: |
78+
cd $(mktemp -d)
79+
bash $GITHUB_WORKSPACE/website/docs/node-operators/scripts/create-env-custom.sh
80+
test -f .env
81+
grep -q "MINA_RUST_TAG=latest" .env
82+
83+
- name: Test create-env-archive script
84+
run: |
85+
cd $(mktemp -d)
86+
bash $GITHUB_WORKSPACE/website/docs/node-operators/scripts/create-env-archive.sh
87+
test -f .env
88+
grep -q "POSTGRES_PASSWORD=mina" .env

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Version: 0341fff
2+
Build time: 2025-09-10T18:11:40.953050700Z
3+
Commit SHA: 0341fffedba4900371504ad4b30853674960a209
4+
Commit time: 2025-09-10T19:30:31.000000000+02:00
5+
Commit branch: release/v0.17.0
6+
Rustc channel: stable
7+
Rustc version: 1.84.1

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

Lines changed: 38 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,13 @@ import BuildInfoNative from "!!raw-loader!./scripts/build-info-native.sh";
1111
import BuildInfoNativePath from "!!raw-loader!./scripts/build-info-native-path.sh";
1212
import VerifyBuildInfoDocker from "!!raw-loader!./scripts/verify-build-info-docker.sh";
1313
import VerifyBuildInfoNative from "!!raw-loader!./scripts/verify-build-info-native.sh";
14+
import BuildInfoExample from "!!raw-loader!./example-output/build-info-example.txt";
15+
import BackupConfiguration from "!!raw-loader!./scripts/backup-configuration.sh";
16+
import ManageFilePermissions from "!!raw-loader!./scripts/manage-file-permissions.sh";
17+
import CheckSystemResources from "!!raw-loader!./scripts/check-system-resources.sh";
18+
import CreateEmptyEnv from "!!raw-loader!./scripts/create-empty-env.sh";
19+
import CreateEnvCustom from "!!raw-loader!./scripts/create-env-custom.sh";
20+
import CreateEnvArchive from "!!raw-loader!./scripts/create-env-archive.sh";
1421

1522
# Node Management
1623

@@ -32,15 +39,9 @@ To check the build information of your Docker-based node:
3239

3340
Example output:
3441

35-
```
36-
Version: 0341fff
37-
Build time: 2025-09-10T18:11:40.953050700Z
38-
Commit SHA: 0341fffedba4900371504ad4b30853674960a209
39-
Commit time: 2025-09-10T19:30:31.000000000+02:00
40-
Commit branch: release/v0.17.0
41-
Rustc channel: stable
42-
Rustc version: 1.84.1
43-
```
42+
<CodeBlock language="text" title="example-output/build-info-example.txt">
43+
{BuildInfoExample}
44+
</CodeBlock>
4445

4546
For a specific version:
4647

@@ -168,36 +169,25 @@ docker compose up -d --force-recreate
168169

169170
Always backup your keys and configuration:
170171

171-
```bash
172-
# Backup producer key (if running block producer)
173-
cp -r mina-workdir/producer-key ~/mina-backup/
174-
175-
# Backup entire working directory
176-
tar -czf mina-backup-$(date +%Y%m%d).tar.gz mina-workdir/
177-
```
172+
<CodeBlock language="bash" title="scripts/backup-configuration.sh">
173+
{BackupConfiguration}
174+
</CodeBlock>
178175

179176
### Managing File Permissions
180177

181178
Docker containers often run as root, creating files owned by root on your host:
182179

183-
```bash
184-
# Check file ownership
185-
ls -la mina-workdir/
186-
187-
# Fix ownership for all files in mina-workdir
188-
sudo chown -R $(id -u):$(id -g) mina-workdir/
189-
190-
# Set appropriate permissions for the producer key
191-
chmod 600 mina-workdir/producer-key
192-
```
180+
<CodeBlock language="bash" title="scripts/manage-file-permissions.sh">
181+
{ManageFilePermissions}
182+
</CodeBlock>
193183

194184
<!-- prettier-ignore-start -->
195185

196186
:::tip Best Practice
197187

198-
Always fix file ownership after Docker operations to ensure your
199-
local user can properly access, backup, and manage the files. This is especially
200-
important for sensitive files like producer keys.
188+
Always fix file ownership after Docker operations to ensure your local user can
189+
properly access, backup, and manage the files. This is especially important for
190+
sensitive files like producer keys.
201191

202192
:::
203193

@@ -224,32 +214,23 @@ environment variables:
224214

225215
**For regular node and block producer:**
226216

227-
```bash
228-
# Quick fix: Create an empty .env file (has defaults)
229-
touch .env
230-
231-
# Or create with custom settings
232-
cat > .env << EOF
233-
MINA_RUST_TAG=latest
234-
MINA_FRONTEND_TAG=latest
235-
MINA_LIBP2P_PORT=8302
236-
MINA_LIBP2P_EXTERNAL_IP=
237-
MINA_PRIVKEY_PASS=
238-
COINBASE_RECEIVER=
239-
EOF
240-
```
217+
Quick fix: Create an empty .env file (has defaults)
218+
219+
<CodeBlock language="bash" title="scripts/create-empty-env.sh">
220+
{CreateEmptyEnv}
221+
</CodeBlock>
222+
223+
Or create with custom settings:
224+
225+
<CodeBlock language="bash" title="scripts/create-env-custom.sh">
226+
{CreateEnvCustom}
227+
</CodeBlock>
241228

242229
**For archive node (required):**
243230

244-
```bash
245-
# Archive node requires specific database settings
246-
cat > .env << EOF
247-
POSTGRES_PASSWORD=mina
248-
PG_PORT=5432
249-
PG_DB=archive
250-
MINA_RUST_TAG=latest
251-
EOF
252-
```
231+
<CodeBlock language="bash" title="scripts/create-env-archive.sh">
232+
{CreateEnvArchive}
233+
</CodeBlock>
253234

254235
Regular node docker-compose files have default values, but the archive node
255236
docker-compose file requires the `.env` file with PostgreSQL configuration.
@@ -266,11 +247,11 @@ docker-compose file requires the `.env` file with PostgreSQL configuration.
266247
### Performance Issues
267248

268249
1. Check system resources:
269-
```bash
270-
free -h
271-
df -h
272-
docker stats
273-
```
250+
251+
<CodeBlock language="bash" title="scripts/check-system-resources.sh">
252+
{CheckSystemResources}
253+
</CodeBlock>
254+
274255
2. Review node logs for warnings
275256
3. Consider adjusting Docker resource limits
276257

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Backup producer key (if running block producer)
2+
cp -r mina-workdir/producer-key ~/mina-backup/
3+
4+
# Backup entire working directory
5+
tar -czf mina-backup-$(date +%Y%m%d).tar.gz mina-workdir/

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

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
#!/bin/bash
2+
# Verify that build-info output format matches the documented example
3+
4+
set -euo pipefail
5+
6+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
7+
EXAMPLE_FILE="$SCRIPT_DIR/../example-output/build-info-example.txt"
8+
9+
# Get actual build-info output
10+
echo "Getting build-info output..."
11+
ACTUAL_OUTPUT=$(docker run --rm o1labs/mina-rust:latest build-info)
12+
13+
# Extract field names from example file (everything before the colon)
14+
echo "Checking that all expected fields are present..."
15+
EXPECTED_FIELDS=(
16+
"Version"
17+
"Build time"
18+
"Commit SHA"
19+
"Commit time"
20+
"Commit branch"
21+
"Rustc channel"
22+
"Rustc version"
23+
)
24+
25+
# Check that each expected field exists in the actual output
26+
MISSING_FIELDS=()
27+
for field in "${EXPECTED_FIELDS[@]}"; do
28+
if ! echo "$ACTUAL_OUTPUT" | grep -q "^${field}:"; then
29+
MISSING_FIELDS+=("$field")
30+
fi
31+
done
32+
33+
if [ ${#MISSING_FIELDS[@]} -gt 0 ]; then
34+
echo "ERROR: Missing fields in build-info output:"
35+
printf ' - %s\n' "${MISSING_FIELDS[@]}"
36+
echo ""
37+
echo "Expected fields:"
38+
printf ' - %s\n' "${EXPECTED_FIELDS[@]}"
39+
echo ""
40+
echo "Actual output:"
41+
echo "$ACTUAL_OUTPUT"
42+
exit 1
43+
fi
44+
45+
# Verify field order matches the example
46+
echo "Checking that field order matches the example..."
47+
EXAMPLE_ORDER=$(grep -o '^[^:]*:' "$EXAMPLE_FILE")
48+
ACTUAL_ORDER=$(echo "$ACTUAL_OUTPUT" | grep -o '^[^:]*:')
49+
50+
if [ "$EXAMPLE_ORDER" != "$ACTUAL_ORDER" ]; then
51+
echo "ERROR: Field order doesn't match the example"
52+
echo ""
53+
echo "Expected order:"
54+
echo "$EXAMPLE_ORDER"
55+
echo ""
56+
echo "Actual order:"
57+
echo "$ACTUAL_ORDER"
58+
exit 1
59+
fi
60+
61+
echo "✓ Build-info format matches the documented example"
62+
echo ""
63+
echo "Actual output:"
64+
echo "$ACTUAL_OUTPUT"

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
free -h
2+
df -h
3+
docker stats

‎website/docs/node-operators/scripts/create-empty-env.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
touch .env

‎website/docs/node-operators/scripts/create-env-archive.sh‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
cat > .env << EOF
2+
POSTGRES_PASSWORD=mina
3+
PG_PORT=5432
4+
PG_DB=archive
5+
MINA_RUST_TAG=latest
6+
EOF

‎website/docs/node-operators/scripts/create-env-custom.sh‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
cat > .env << EOF
2+
MINA_RUST_TAG=latest
3+
MINA_FRONTEND_TAG=latest
4+
MINA_LIBP2P_PORT=8302
5+
MINA_LIBP2P_EXTERNAL_IP=
6+
MINA_PRIVKEY_PASS=
7+
COINBASE_RECEIVER=
8+
EOF

‎website/docs/node-operators/scripts/manage-file-permissions.sh‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Check file ownership
2+
ls -la mina-workdir/
3+
4+
# Fix ownership for all files in mina-workdir
5+
sudo chown -R $(id -u):$(id -g) mina-workdir/
6+
7+
# Set appropriate permissions for the producer key
8+
chmod 600 mina-workdir/producer-key

0 commit comments

Comments
 (0)