explorer-monorepo/RUNBOOK.md

Explorer + Snap VMID 5000 Runbook

Short runbook for building, deploying, and verifying the explorer and Chain 138 Snap site on VMID 5000.

Prerequisites

• Access to Proxmox host that runs VMID 5000 (e.g. pct or SSH to PROXMOX_HOST_R630_02).
• Explorer repo: explorer-monorepo. Snap repo: metamask-integration/chain138-snap.

1. Build Snap companion site (pathPrefix /snap)

From chain138-snap repo root:

GATSBY_PATH_PREFIX=/snap GATSBY_BUILD_SHA=$(git rev-parse --short HEAD) pnpm --filter site run build

Optional: GATSBY_SNAP_API_BASE_URL=https://your-api.com for production market/bridge/swap.

Output: packages/site/public/ and static/version.json.

2. Deploy Snap site to VMID 5000

From chain138-snap:

./scripts/deploy-snap-site-to-vmid5000.sh --build
# Or: ./scripts/deploy-snap-site-to-vmid5000.sh  (existing build)

Deploys to /var/www/html/snap/ and saves a rollback tarball.

3. Nginx on VMID 5000

From Proxmox host (one command): bash scripts/apply-nginx-snap-vmid5000.sh (from explorer-monorepo). Or run inside VMID 5000: bash scripts/fix-nginx-serve-custom-frontend.sh. Configures /snap, /snap/, /api/, explorer root. Then: nginx -t && systemctl reload nginx.

4. Verification

• Snap only: cd metamask-integration/chain138-snap && ./scripts/verify-snap-site-vmid5000.sh [BASE_URL]
• Full (explorer + API + Snap): cd explorer-monorepo && ./scripts/verify-vmid5000-all.sh [BASE_URL]

BASE_URL defaults to https://explorer.d-bis.org. After applying the nginx fix, /snap and /snap/ should return 200 with content.

5. Rollback Snap site

Inside VM: tar -xf /var/www/html/snap-rollback.tar -C /var/www/html/snap && chown -R www-data:www-data /var/www/html/snap

From host: use /tmp/snap-site-last.tar and pct push + pct exec to extract into /var/www/html/snap.

6. Health / version

• Snap version: https://explorer.d-bis.org/snap/version.json
• Explorer health: https://explorer.d-bis.org/health

7. Troubleshooting

• 502 on /api/: Blockscout not on port 4000. See docs/EXPLORER_API_ACCESS.md and scripts/fix-502-blockscout.sh.
• Snap 404/blank: Nginx needs location /snap/ and location = /snap; re-run fix-nginx-serve-custom-frontend.sh and redeploy Snap site.
• Market/Bridge/Swap not loading: Set GATSBY_SNAP_API_BASE_URL, rebuild, redeploy.

Monitoring (optional): Run verify-vmid5000-all.sh on a schedule (e.g. cron) or after deploys; alert if the script exits non-zero. Use /snap/version.json and /health for load balancer or uptime checks.

See docs/EXPLORER_API_ACCESS.md and metamask-integration/chain138-snap/DEPLOY_VMID5000.md.