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

doc/step-002-solana-rpc-install.txt

@@ -5,25 +5,29 @@ Stan startowy:
 - SSH po publicznym eth0 jest odciete (UFW deny na eth0:22), SSH dziala tylko po wg0.
 - RPC ma byc prywatny: porty 8899/8900 tylko po wg0, ale node ma miec publiczne porty klastra (UDP dynamic range) zeby syncowal.
 
-UWAGA o bind:
-- `agave-validator` praktycznie wymaga, zeby wszystkie sockety byly na tym samym IP.
-- Dlatego w tym kroku bindujemy usluge na 0.0.0.0 i zabezpieczamy dostep firewall-em:
-  - eth0: blokujemy TCP 8899/8900
-  - wg0: pozwalamy TCP 8899/8900
-  - eth0: pozwalamy UDP dynamic port range (np. 8000-8020) dla klastra
+UWAGA o prywatnosci:
+- RPC/WS bindujemy na wg0 (10.66.66.1), zeby NIE wystawic RPC na publicznym eth0 nawet gdy UFW jest wylaczone.
+- Dodatkowo i tak robimy UFW "deny" na eth0:8899/8900 (defense-in-depth).
 
 Parametry (dostosuj, przyklad mainnet):
 - PUBLIC_IFACE=eth0
 - WG_IFACE=wg0
 - WG_IP=10.66.66.1
 - ENDPOINT_RPC_PORT=8899
-- ENDPOINT_WS_PORT=8900
+- ENDPOINT_WS_PORT=8900 (WS = RPC_PORT+1)
 - DYNAMIC_PORT_RANGE="8000:8020"
 
+0) Storage (rekomendowane)
+Jesli masz osobny NVMe na dane (ledger/accounts), zrob najpierw:
+  doc/step-002a-storage-nvme0n1-xfs.txt
+albo (mpabi, 2x NVMe z juz istniejacym XFS):
+  doc/step-002a-storage-existing-solacct-solledg-xfs.txt
+
 1) Bazowe pakiety
   sudo apt-get update
   sudo apt-get install -y \
     chrony curl jq git \
+    ripgrep \
     smartmontools nvme-cli \
     build-essential pkg-config libssl-dev \
     clang llvm-dev libclang-dev \
@@ -38,6 +42,10 @@ Parametry (dostosuj, przyklad mainnet):
   sudo install -d -o solana -g solana -m 0750 \
     /var/lib/solana /var/lib/solana/ledger /var/lib/solana/accounts /var/log/solana
 
+  # Jesli ledger/accounts sa mountpointami (Step 002A), upewnij sie, ze root FS jest writable dla usera solana:
+  sudo chown solana:solana /var/lib/solana/ledger /var/lib/solana/accounts
+  sudo chmod 750 /var/lib/solana/ledger /var/lib/solana/accounts
+
 3) Sysctl + ulimit (baseline pod Agave)
   sudo tee /etc/sysctl.d/90-agave.conf >/dev/null <<'EOF'
 fs.file-max = 2000000
@@ -83,44 +91,19 @@ EOF
 5) Narzedzia Solana/Anza (dla `solana`): solana-keygen itd.
   sudo -u solana -H bash -lc 'sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"'
 
-  ACTIVE_RELEASE_BIN_DIR="/var/lib/solana/.local/share/solana/install/active_release/bin"
-  test -d "$ACTIVE_RELEASE_BIN_DIR" || { echo "Missing: $ACTIVE_RELEASE_BIN_DIR" >&2; exit 1; }
-  for bin in "$ACTIVE_RELEASE_BIN_DIR"/*; do
-    sudo ln -sfn "$bin" "/opt/solana/bin/$(basename "$bin")"
-  done
-  test -x /opt/solana/bin/solana-keygen
+  # Weryfikacja, ze installer utworzyl active_release/bin (bez exit, zeby nie ubijac pane/tmux):
+  sudo -u solana -H bash -lc 'ls -ld ~/.local/share/solana/install/active_release/bin && ls -1 ~/.local/share/solana/install/active_release/bin | head'
+
+  # Kopiuj binarki do /opt/solana/bin (zamiast symlinkow - mniej problemow z uprawnieniami)
+  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-keygen --version
 
 6) Build `agave-validator` ze zrodel i instalacja do /opt/solana/bin
-  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")'
-    if [ ! -d '${AGAVE_SRC_DIR}/.git' ]; then
-      git clone --depth 1 --branch '${AGAVE_VERSION_TAG}' https://github.com/anza-xyz/agave.git '${AGAVE_SRC_DIR}'
-    else
-      cd '${AGAVE_SRC_DIR}'
-      git fetch --tags --prune
-      git checkout '${AGAVE_VERSION_TAG}'
-    fi
-
-    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
-
-  test -x /opt/solana/bin/agave-validator
+  # Najnowszy stable release dla mainnet wybieraj z GitHub Releases (tag v3.0.x).
+  # Krok po kroku (w tym automatyczny wybor tagu):
+  doc/step-002f-agave-build-from-source-latest.txt
 
 7) Identity (tylko raz) + backup poza hostem
   if [ ! -f /var/lib/solana/identity.json ]; then
@@ -146,14 +129,21 @@ Testnet:
     https://api.testnet.solana.com | jq -r .result)"
   echo "$GENESIS_HASH"
 
-9) Systemd unit: /etc/systemd/system/solana-rpc.service
-Minimalny unit (RPC node, non-voting). Bind na 0.0.0.0 + firewall robi prywatnosc RPC.
+9) Systemd unit: /etc/systemd/system/agave-validator.service
+Minimalny unit (RPC node, non-voting). RPC/WS bind na wg0 (10.66.66.1).
+Jesli widzisz w logach:
+  "error: The subcommand '\\' wasn't recognized"
+to zrob:
+  doc/step-002b-agave-validator-systemd.txt
 
-  sudo tee /etc/systemd/system/solana-rpc.service >/dev/null <<'EOF'
+Jesli chcesz najpierw odpalic recznie z CLI (test) przed systemd:
+  doc/step-002e-agave-validator-run-cli.txt
+
+  sudo tee /etc/systemd/system/agave-validator.service >/dev/null <<'EOF'
 [Unit]
-Description=Solana RPC node (Agave)
-After=network-online.target
-Wants=network-online.target
+Description=Agave validator (mainnet, RPC-only, non-voting)
+After=network-online.target wg-quick@wg0.service
+Wants=network-online.target wg-quick@wg0.service
 
 [Service]
 Type=simple
@@ -168,16 +158,18 @@ TimeoutStopSec=120
 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 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 \
-  --log /var/log/solana/validator.log
+  --limit-ledger-size 50000000
 NoNewPrivileges=true
 PrivateTmp=true
 ProtectSystem=full
@@ -188,20 +180,20 @@ WantedBy=multi-user.target
 EOF
 
   sudo systemctl daemon-reload
-  sudo systemctl enable --now solana-rpc
+  sudo systemctl enable --now agave-validator
 
 Jesli chcesz dodac genesis hash:
 - dopisz w ExecStart linie:
   --expected-genesis-hash <GENESIS_HASH>
 
 10) Weryfikacja
-  systemctl is-active solana-rpc
-  journalctl -u solana-rpc -n 200 --no-pager
+  systemctl is-active agave-validator
+  journalctl -u agave-validator -n 200 --no-pager
 
-  # z samego hosta:
+  # z samego hosta (getHealth moze zwracac blad dopoki node nie dogoni klastra):
   curl -sS -H 'content-type: application/json' \
-    --data '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' \
-    http://127.0.0.1:8899 | jq .
+    --data '{"jsonrpc":"2.0","id":1,"method":"getVersion"}' \
+    http://10.66.66.1:8899 | jq .
 
   # z laptopa/VPS po WG:
   curl -sS -H 'content-type: application/json' \
@@ -211,5 +203,12 @@ Jesli chcesz dodac genesis hash:
 Jesli cos nie dziala:
 - `sudo wg show` (czy WG jest OK)
 - `sudo ufw status verbose` (czy RPC nie jest blokowane po wg0)
-- `journalctl -u solana-rpc -n 200 --no-pager` (logi Agave)
+- `journalctl -u agave-validator -n 200 --no-pager` (logi Agave)
 
+Typowe fixy:
+- "error: The subcommand '\\' wasn't recognized":
+  doc/step-002b-agave-validator-systemd.txt
+- "failed to open genesis" / brak `genesis.tar.bz2`:
+  doc/step-002c-genesis-download-mainnet.txt
+- "did you forget to provide a snapshot" (mainnet bez snapshot nie ruszy):
+  doc/step-002d-snapshot-download-mainnet.txt