explorer-monorepo/docs/DEPLOYMENT.md

# Deployment Guide

## Production Deployment

### Prerequisites

- SSH access to production server (192.168.11.140)
- Password for root user
- `sshpass` installed (or use SSH keys)

### Quick Deploy

For the current frontend, use the Next standalone deploy path:

```bash
# From explorer-monorepo root
./scripts/deploy-next-frontend-to-vmid5000.sh
```

This builds `frontend/`, uploads the standalone bundle, installs the
`solacescanscout-frontend.service` unit, and starts the frontend on
`127.0.0.1:3000` inside VMID 5000.

Nginx should keep the existing explorer API routes and proxy `/` plus `/_next/`
to the frontend service. Use
[nginx-next-frontend-proxy.conf](/home/intlc/projects/proxmox/explorer-monorepo/deployment/common/nginx-next-frontend-proxy.conf)
inside the explorer server block after `/api`, `/api/config/*`, `/explorer-api/*`,
`/token-aggregation/api/v1/*`, `/snap/`, and `/health`.

### Legacy Static Deploy

The historical static SPA deploy path is deprecated. The old scripts
`./scripts/deploy.sh` and `./scripts/deploy-frontend-to-vmid5000.sh` now fail
fast with a deprecation message and intentionally point operators back to the
canonical Next.js deploy path.

### Manual Deploy

```bash
# Canonical Next deployment:
./scripts/deploy-next-frontend-to-vmid5000.sh

# Compatibility assets only:
# frontend/public/index.html
# frontend/public/explorer-spa.js
```

### Environment Variables

The canonical Next deployment script uses its own VM/host defaults and deploy
workflow. Prefer reviewing `scripts/deploy-next-frontend-to-vmid5000.sh`
directly instead of relying on the older static script env contract below.

Historical static-script environment variables:

- `IP`: Production server IP (required; no default)
- `DOMAIN`: Domain name (required; no default)
- `SSH_PASSWORD`: SSH password (required; no default; previous
  hardcoded default has been removed — see
  [SECURITY.md](SECURITY.md))

These applied to the deprecated static deploy script and are no longer the
recommended operator interface.

## Mission-control and Track 4 runtime wiring

If you are deploying the Go explorer API with the mission-control additions enabled, set these backend env vars as well:

- `RPC_URL` - Chain 138 RPC for Track 1 and mission-control status/SSE data
- `TOKEN_AGGREGATION_BASE_URL` - used by `GET /api/v1/mission-control/liquidity/token/{address}/pools`
- `BLOCKSCOUT_INTERNAL_URL` - used by `GET /api/v1/mission-control/bridge/trace`
- `EXPLORER_PUBLIC_BASE` - public base URL returned in bridge trace links
- `CCIP_RELAY_HEALTH_URL` - optional relay probe URL, for example `http://192.168.11.11:9860/healthz`
- `CCIP_RELAY_HEALTH_URLS` - optional comma-separated named relay probes, for example `mainnet=http://192.168.11.11:9860/healthz,bsc=http://192.168.11.11:9861/healthz,avax=http://192.168.11.11:9862/healthz`
- `MISSION_CONTROL_CCIP_JSON` - optional JSON-file fallback for relay health snapshots
- `OPERATOR_SCRIPTS_ROOT` - root directory for Track 4 script execution
- `OPERATOR_SCRIPT_ALLOWLIST` - comma-separated allowlist for `POST /api/v1/track4/operator/run-script`
- `OPERATOR_SCRIPT_TIMEOUT_SEC` - optional per-script timeout in seconds

For nginx, include [nginx-mission-control-sse.conf](/home/intlc/projects/proxmox/explorer-monorepo/deployment/common/nginx-mission-control-sse.conf) inside the same server block that proxies `/explorer-api/`, and update the `proxy_pass` target if your Go API is not listening on `127.0.0.1:8080`.

### Quick verification

```bash
curl -N https://explorer.d-bis.org/explorer-api/v1/mission-control/stream
curl "https://explorer.d-bis.org/explorer-api/v1/mission-control/bridge/trace?tx=0x..."
curl "https://explorer.d-bis.org/explorer-api/v1/mission-control/liquidity/token/0x93E66202A11B1772E55407B32B44e5Cd8eda7f22/pools"
# Optional relay probe from the explorer host:
curl http://192.168.11.11:9860/healthz
```

## Rollback

If deployment fails, rollback to previous version:

```bash
ssh root@192.168.11.140
ls -1dt /opt/solacescanscout/frontend/releases/* | head
```

For the Next standalone path, restart the previous release by repointing
`/opt/solacescanscout/frontend/current` to the prior release and restarting
`solacescanscout-frontend`.

## Testing

After deployment, test the explorer:

```bash
./scripts/test.sh
```

Or manually:

```bash
curl -k -I https://explorer.d-bis.org/
```