docs(solana-rpc): expand agave and geyser runbook

2026-03-12 23:26:17 +01:00
parent 7c63114526
commit ade8579bae
11 changed files with 923 additions and 120 deletions
--- a/doc/step-002-plan-solana-rpc-mainnet-private.txt
+++ b/doc/step-002-plan-solana-rpc-mainnet-private.txt
@@ -1,10 +1,11 @@
-Step 002: Plan wdrozenia Solana RPC (Agave mainnet, non-voting, private RPC + Yellowstone gRPC + monitoring + NOC tmux)
+Step 002: Plan wdrozenia Solana RPC (Agave mainnet, non-voting, private RPC + Geyser->Postgres + monitoring + NOC tmux)

 Zalozenia (default):
 - WG iface: wg0, WG subnet: 10.66.66.0/24, WG IP baremetala: 10.66.66.1
 - Public iface: eth0, public IP: 149.50.116.219
- RPC: 8899 (HTTP), WS: 8900
- Yellowstone gRPC: 10000 (tylko po WG)
+- RPC: 8899 (HTTP), WS: 8900 (WS = RPC_PORT+1)
+- Postgres (lokalnie): 5432 (DB: geyser, user: geyser)
+- (Optional) Yellowstone gRPC: 10000 (tylko po WG)
 - Prometheus: 9090, Grafana: 3000, node_exporter: 9100 (tylko po WG)
 - Dynamic port range (cluster): 8000-8020/udp (public eth0)
 - User: solana
@@ -28,6 +29,7 @@ Zalozenia (default):
    sysstat iotop \
    ethtool nstat \
    chrony curl jq git ca-certificates \
+    ripgrep \
    smartmontools nvme-cli \
    build-essential pkg-config libssl-dev \
    clang llvm-dev libclang-dev \
@@ -46,6 +48,15 @@ Zalozenia (default):
  #   sudo chown solana:solana /var/lib/solana/identity.json
  #   sudo chmod 600 /var/lib/solana/identity.json

+2A) Storage (rekomendowane)
+  # Variant A: jesli /dev/nvme0n1 jest wolny i chcesz go podzielic 50/50:
+  #   doc/step-002a-storage-nvme0n1-xfs.txt
+  #
+  # Variant B (mpabi): masz juz 2x NVMe z XFS:
+  #   - SOLACCT na accounts (nvme0n1p1)
+  #   - SOLLEDG na ledger (nvme1n1p1)
+  #   doc/step-002a-storage-existing-solacct-solledg-xfs.txt
+
 3) Firewall/WG binding (private-only)
  # UFW: deny everything inbound by default
  sudo ufw default deny incoming
@@ -102,39 +113,16 @@ EOF
  sudo -u solana -H bash -lc 'sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"'

  # Copy binaries to /opt/solana/bin (avoid symlink permission gotchas)
-  sudo bash -lc '
-  set -e
-  SRC="/var/lib/solana/.local/share/solana/install/active_release/bin"
-  DST="/opt/solana/bin"
-  for f in "$SRC"/*; do
-    [ -f "$f" ] || continue
-    install -m 0755 "$f" "$DST/$(basename "$f")"
-  done
-  '
+  sudo cp -a /var/lib/solana/.local/share/solana/install/active_release/bin/. /opt/solana/bin/
+  sudo find /opt/solana/bin -maxdepth 1 -type f -exec chmod 0755 {} \;

  /opt/solana/bin/solana --version || true
  /opt/solana/bin/solana-keygen --version

  # Build agave-validator (pin tag + toolchain)
-  AGAVE_VERSION_TAG="v2.3.13"
-  AGAVE_RUST_TOOLCHAIN="1.86.0"
-  AGAVE_SRC_DIR="/var/lib/solana/src/agave"
-
-  sudo -u solana -H bash -lc "curl -sSfL https://sh.rustup.rs | sh -s -- -y --default-toolchain '${AGAVE_RUST_TOOLCHAIN}'"
-  sudo -u solana -H bash -lc "
-    set -euo pipefail
-    export PATH=/var/lib/solana/.cargo/bin:\$PATH
-    rustup toolchain install '${AGAVE_RUST_TOOLCHAIN}'
-    mkdir -p '$(dirname \"$AGAVE_SRC_DIR\")'
-    rm -rf '${AGAVE_SRC_DIR}'
-    git clone --depth 1 --branch '${AGAVE_VERSION_TAG}' https://github.com/anza-xyz/agave.git '${AGAVE_SRC_DIR}'
-    cd '${AGAVE_SRC_DIR}'
-    cargo +${AGAVE_RUST_TOOLCHAIN} build --release -p agave-validator
-  "
-
-  sudo install -o root -g root -m 0755 \
-    "${AGAVE_SRC_DIR}/target/release/agave-validator" \
-    /opt/solana/bin/agave-validator
+  # Uwaga: dla nowszych stable release'ow binarka moze nie byc publikowana,
+  # wiec build ze zrodel jest wymagany.
+  #   doc/step-002f-agave-build-from-source-latest.txt

  # Identity (create once)
  if [ ! -f /var/lib/solana/identity.json ]; then
@@ -148,15 +136,20 @@ EOF
    --data '{"jsonrpc":"2.0","id":1,"method":"getGenesisHash"}' \
    https://api.mainnet-beta.solana.com | jq -r .result)"
  echo "$GENESIS_HASH"
+  # Oczekiwane (mainnet): 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d

  # systemd unit (bind RPC to WG/localhost only)
-  # NOTE: agave-validator expects sockets on the same IP in many setups.
-  # We keep bind 0.0.0.0 but rely on UFW to ensure private-only access to RPC/WS.
-  sudo tee /etc/systemd/system/agave-validator.service >/dev/null <<EOF
+  # UWAGA: w unit file NIE uzywaj `\\` na koncu linii w ExecStart.
+  # Jesli wpiszesz `\\`, agave-validator dostanie literalny argument `\` i padnie z:
+  #   "error: The subcommand '\\' wasn't recognized"
+  #
+  # Najprosciej: ExecStart w 1 linii, bez "kontynuacji" backslashami.
+  # Ale: zeby uniknac problemow z wklejaniem/lamaniem linii, ponizej jest bezpieczna wersja wielolinijkowa.
+  sudo tee /etc/systemd/system/agave-validator.service >/dev/null <<'EOF'
 [Unit]
 Description=Agave validator (mainnet, RPC-only, non-voting)
-After=network-online.target
-Wants=network-online.target
+After=network-online.target wg-quick@wg0.service
+Wants=network-online.target wg-quick@wg0.service

 [Service]
 Type=simple
@@ -168,22 +161,21 @@ LimitNOFILE=1048576
 Restart=always
 RestartSec=5
 TimeoutStopSec=120
-ExecStart=/opt/solana/bin/agave-validator \\
-  --identity /var/lib/solana/identity.json \\
-  --no-voting \\
-  --ledger /var/lib/solana/ledger \\
-  --accounts /var/lib/solana/accounts \\
-  --log /var/log/solana/validator.log \\
-  --bind-address 0.0.0.0 \\
-  --rpc-bind-address 0.0.0.0 \\
-  --rpc-port 8899 \\
-  --rpc-pubsub-bind-address 0.0.0.0 \\
-  --rpc-pubsub-port 8900 \\
-  --dynamic-port-range 8000-8020 \\
-  --entrypoint entrypoint.mainnet-beta.solana.com:8001 \\
-  --expected-genesis-hash ${GENESIS_HASH} \\
-  --full-rpc-api \\
-  --limit-ledger-size
+ExecStart=/opt/solana/bin/agave-validator \
+  --identity /var/lib/solana/identity.json \
+  --no-voting \
+  --private-rpc \
+  --ledger /var/lib/solana/ledger \
+  --accounts /var/lib/solana/accounts \
+  --log /var/log/solana/validator.log \
+  --bind-address 0.0.0.0 \
+  --rpc-bind-address 10.66.66.1 \
+  --rpc-port 8899 \
+  --dynamic-port-range 8000-8020 \
+  --entrypoint entrypoint.mainnet-beta.solana.com:8001 \
+  --expected-genesis-hash 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d \
+  --full-rpc-api \
+  --limit-ledger-size 50000000
 NoNewPrivileges=true
 PrivateTmp=true
 ProtectSystem=full
@@ -199,15 +191,24 @@ EOF
  systemctl is-active agave-validator
  journalctl -u agave-validator -n 80 --no-pager

-5) Yellowstone gRPC (plugin) (placeholder)
-  # TODO (next step): install/build yellowstone geyser plugin matching Agave 3.0.15,
-  # put plugin .so under /opt/solana/plugins/, write /etc/solana/yellowstone-geyser.json,
-  # and add to ExecStart:
-  #   --geyser-plugin-config /etc/solana/yellowstone-geyser.json
+  # Jesli padnie na genesis (brak genesis.tar.bz2):
+  #   doc/step-002c-genesis-download-mainnet.txt
  #
-  # Verification (after enable):
-  #   journalctl -u agave-validator | rg -i 'geyser|yellowstone|plugin'
-  #   ss -lntp | rg ':10000\\b'
+  # Jesli padnie na snapshot (mainnet wymaga snapshot):
+  #   doc/step-002d-snapshot-download-mainnet.txt
+  #
+  # Jesli chcesz najpierw odpalic validator z CLI (test), zanim przepniesz na systemd:
+  #   doc/step-002e-agave-validator-run-cli.txt
+
+5) Geyser plugin -> Postgres
+  # Krok po kroku:
+  #   doc/step-003-geyser-plugin-postgres.txt
+  #
+  # W skrocie:
+  # - budujesz plugin .so i wrzucasz do /opt/solana/plugins/
+  # - tworzysz /etc/solana/geyser-postgres.json
+  # - dopisujesz do ExecStart:
+  #     --geyser-plugin-config /etc/solana/geyser-postgres.json

 6) Drift DLOB (2 markets) (on VPS, not baremetal) (placeholder)
  # VPS env:
@@ -258,4 +259,3 @@ EOF
  curl -sS -H 'content-type: application/json' \
    --data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}' \
    http://10.66.66.1:8899 | jq .
-