eliott/worldmonitor
1
0
Fork 0
mirror of https://github.com/koala73/worldmonitor.git synced 2026-04-26 01:24:59 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
d1e084061ddb469f0e64a7554ded4cf25f2fa92e
worldmonitor/docs/relay-parameters.mdx
Elie Habib 09a582e089 fix(docs): correct numerical inaccuracies, add missing features and variants (#1472) 
* fix(docs): correct variant count from 4 to 5

Updated overview.mdx and architecture.mdx to reflect all 5 platform
variants (World Monitor, Tech Monitor, Happy Monitor, Finance Monitor,
Commodity Monitor). Previously only 2 were listed in the table and
the text said "four".

* fix(docs): correct all numerical inaccuracies across documentation

Updated counts verified against actual codebase:
- AI datacenters: 111 → 313
- Undersea cables: 55 → 86
- Map layers: 45 → 49
- News sources: 80+ → 344
- Service domains: 22 → 24
- CII countries: 20 → 24
- Military bases: 210/220+ → 226
- Strategic ports: 61/83 → 62
- Airports: 30/107 → 111
- Chokepoints: 6/8 → 9
- Signal entities: 100+/600+ → 66
- Variant count: four → five (added Commodity Monitor)

* docs(overview): add Happy, Finance, and Commodity Monitor sections

Added detailed documentation sections for the three previously
undocumented platform variants, including layers, panels, and
news categories for each.

* docs(features): document 13 previously undocumented features

Added: trade routes, FIRMS fire detection, webcam surveillance,
country brief, aviation intelligence panel, climate anomalies,
displacement tracking, Gulf economies, WTO trade policy, central
banks & BIS, market watchlist, NOTAM closure detection, and
offline ML capabilities.

* docs: standardize terminology, add cross-references, fix stale refs

Phase 4: Renamed "News Importance Scoring" to "Headline Scoring",
"Signal Correlation" to "Cross-Stream Correlation". Added cross-refs
between CII/convergence, CORS/API-key, maritime/finance chokepoints.
Deduplicated Population Exposure content. Clarified hotspot vs focal
point distinction.

Phase 5: Rewrote daily_stock_analysis as historical context. Added
legacy note for api/*.js files. Added OREF 24h rolling history boost
and GPS jamming classification thresholds to algorithms.mdx. Fixed
orbital-surveillance tier table contradictions.

Phase 6: Fixed orphaned markdown separator in orbital-surveillance.

* fix(docs): catch remaining stale numbers in secondary doc files

Fixed stale counts in data-sources.mdx, strategic-risk.mdx,
documentation.mdx, ai-intelligence.mdx, PRESS_KIT.md, and
roadmap-pro.md that were missed in the initial pass.

* fix(docs): address review findings from fresh-eyes pass

- desktop-app.mdx: "four variants" → "five", "22 services" → "24"
- infrastructure-cascade.mdx: chokepoints 8 → 9, node total 279 → 350
- data-sources.mdx: chokepoints 8 → 9
- overview.mdx: remove duplicated intro sentence
- getting-started.mdx: fix stale file tree comments (AI clusters, airports, entities)
2026-03-12 07:48:47 +04:00

169 lines
7.5 KiB
Plaintext
Raw Blame History

---
title: "Relay Parameters (Railway + Vercel)"
description: "This document covers all environment variables used by the AIS/OpenSky relay path."
---
This document covers all environment variables used by the AIS/OpenSky relay path:
- Railway relay process: `scripts/ais-relay.cjs`
- Vercel relay proxy endpoints (legacy): `api/opensky.js`, `api/ais-snapshot.js`, `api/polymarket.js`, `api/rss-proxy.js`
<Note>
The `api/*.js` edge function endpoints listed above are legacy patterns being phased out in favor of the sebuf proto-first approach. See [Adding Endpoints](/adding-endpoints) for the current recommended pattern.
</Note>
- Server relay callers: `server/worldmonitor/*` handlers
- Optional browser local fallback callers in `src/services/*`
## 1) Minimum Production Setup
Set these before enabling strict relay auth.
### Railway (relay)
| Variable | Required | Example | Notes |
| --- | --- | --- | --- |
| `AISSTREAM_API_KEY` | Yes | `ais_...` | Required for AIS upstream WebSocket feed. |
| `RELAY_SHARED_SECRET` | Yes | `wm_relay_prod_...` | Must exactly match Vercel value. |
| `RELAY_AUTH_HEADER` | Recommended | `x-relay-key` | Must match Vercel if changed from default. |
### Vercel (proxy + server functions)
| Variable | Required | Example | Notes |
| --- | --- | --- | --- |
| `WS_RELAY_URL` | Yes | `https://<railway-app>.up.railway.app` | HTTPS relay base URL used by server-side proxy calls. |
| `RELAY_SHARED_SECRET` | Yes | `wm_relay_prod_...` | Must exactly match Railway value. |
| `RELAY_AUTH_HEADER` | Recommended | `x-relay-key` | Header name used to forward relay secret. |
## 2) Full Parameter Reference
## Core Relay/Auth
| Variable | Set On | Default | Required | Purpose |
| --- | --- | --- | --- | --- |
| `AISSTREAM_API_KEY` | Railway | none | Yes | Auth for AIS upstream stream source. |
| `VITE_AISSTREAM_API_KEY` | Local dev only | none | No | Local fallback if `AISSTREAM_API_KEY` is missing. Not recommended for production. |
| `PORT` | Railway/local | `3004` | No | HTTP server listen port for relay process. |
| `WS_RELAY_URL` | Vercel + server handlers | none | Yes (for relay-backed features) | Base URL used by Vercel/server to reach Railway relay. |
| `VITE_WS_RELAY_URL` | Browser (local dev) | none | No | Localhost fallback path for direct browser calls in development only. |
| `RELAY_SHARED_SECRET` | Railway + Vercel | empty | Yes in production | Shared secret for non-public relay routes. |
| `RELAY_AUTH_HEADER` | Railway + Vercel | `x-relay-key` | No (but recommended explicit) | Header name carrying relay secret. |
| `ALLOW_UNAUTHENTICATED_RELAY` | Railway | `false` | No | Emergency override. If `true`, production can start without secret. Keep `false`. |
| `ALLOW_VERCEL_PREVIEW_ORIGINS` | Railway | `false` | No | If `true`, allows `*.vercel.app` origins in relay CORS checks. |
## Relay-Adjacent Feature Flags
| Variable | Set On | Default | Required | Purpose |
| --- | --- | --- | --- | --- |
| `VITE_ENABLE_AIS` | Browser/client build env | enabled (unless `false`) | No | Client-side feature gate for AIS UI/polling. |
| `LOCAL_API_MODE` | Local/server runtime | none | No | If contains `sidecar`, some server handlers bypass relay and call OpenSky directly. |
| `WINGBITS_API_KEY` | Vercel/server | none | No | Military enrichment/fallback source used by server handlers; not required for relay core. |
## OpenSky Upstream Auth
| Variable | Set On | Default | Required | Purpose |
| --- | --- | --- | --- | --- |
| `OPENSKY_CLIENT_ID` | Railway | none | No (recommended) | OAuth client ID for higher OpenSky reliability/rate limits. |
| `OPENSKY_CLIENT_SECRET` | Railway | none | No (recommended) | OAuth client secret paired with client ID. |
## OpenSky Cache/Cardinality Controls
| Variable | Set On | Default | Required | Purpose |
| --- | --- | --- | --- | --- |
| `OPENSKY_CACHE_MAX_ENTRIES` | Railway | `128` | No | Max positive cache keys retained in memory. |
| `OPENSKY_NEGATIVE_CACHE_MAX_ENTRIES` | Railway | `256` | No | Max negative cache keys (`429/5xx`) retained in memory. |
| `OPENSKY_BBOX_QUANT_STEP` | Railway | `0.01` | No | Coordinate quantization step for bbox cache key reuse. `0` disables quantization. |
## AIS Pipeline Tuning
| Variable | Set On | Default | Required | Purpose |
| --- | --- | --- | --- | --- |
| `AIS_SNAPSHOT_INTERVAL_MS` | Railway | `5000` (min `2000`) | No | Interval for rebuilding snapshot payloads. |
| `AIS_UPSTREAM_QUEUE_HIGH_WATER` | Railway | `4000` (min `500`) | No | Pause upstream socket when queue reaches this. |
| `AIS_UPSTREAM_QUEUE_LOW_WATER` | Railway | `1000` (clamped below HIGH_WATER) | No | Resume upstream socket when queue drops below this. |
| `AIS_UPSTREAM_QUEUE_HARD_CAP` | Railway | `8000` (must be `> HIGH_WATER`) | No | Max queue size before dropping incoming upstream messages. |
| `AIS_UPSTREAM_DRAIN_BATCH` | Railway | `250` (min `1`) | No | Max messages drained per cycle. |
| `AIS_UPSTREAM_DRAIN_BUDGET_MS` | Railway | `20` (min `2`) | No | Max CPU time budget per drain cycle. |
## Rate Limit / Logging / Metrics
| Variable | Set On | Default | Required | Purpose |
| --- | --- | --- | --- | --- |
| `RELAY_RATE_LIMIT_WINDOW_MS` | Railway | `60000` | No | Global rate-limit window. |
| `RELAY_RATE_LIMIT_MAX` | Railway | `1200` | No | Default max requests per IP per window. |
| `RELAY_OPENSKY_RATE_LIMIT_MAX` | Railway | `600` | No | OpenSky route max requests per IP per window. |
| `RELAY_RSS_RATE_LIMIT_MAX` | Railway | `300` | No | RSS route max requests per IP per window. |
| `RELAY_LOG_THROTTLE_MS` | Railway | `10000` | No | Minimum interval between repeated log events per key. |
| `RELAY_METRICS_WINDOW_SECONDS` | Railway | `60` (min `10`) | No | Rolling window used by `/metrics`. |
## Platform-Managed Variables (Do Not Manually Set)
These are used only for production detection and are usually injected by platform/runtime.
| Variable | Who sets it | Purpose |
| --- | --- | --- |
| `NODE_ENV` | Runtime/platform | Used to detect production mode. |
| `RAILWAY_ENVIRONMENT` | Railway | Used to detect production relay environment. |
| `RAILWAY_PROJECT_ID` | Railway | Used to detect production relay environment. |
| `RAILWAY_STATIC_URL` | Railway | Used to detect production relay environment. |
## 3) Recommended Starting Values (High Traffic Baseline)
These are safe starting points for a busy relay:
```bash
# Auth + routing
RELAY_SHARED_SECRET=<strong-random-secret>
RELAY_AUTH_HEADER=x-relay-key
WS_RELAY_URL=https://<your-railway-relay>.up.railway.app
ALLOW_UNAUTHENTICATED_RELAY=false
# OpenSky cache/cardinality
OPENSKY_CACHE_MAX_ENTRIES=256
OPENSKY_NEGATIVE_CACHE_MAX_ENTRIES=512
OPENSKY_BBOX_QUANT_STEP=0.01
# AIS pipeline
AIS_SNAPSHOT_INTERVAL_MS=3000
AIS_UPSTREAM_QUEUE_HIGH_WATER=5000
AIS_UPSTREAM_QUEUE_LOW_WATER=1500
AIS_UPSTREAM_QUEUE_HARD_CAP=10000
AIS_UPSTREAM_DRAIN_BATCH=300
AIS_UPSTREAM_DRAIN_BUDGET_MS=20
# Rate limits + metrics
RELAY_RATE_LIMIT_WINDOW_MS=60000
RELAY_RATE_LIMIT_MAX=1200
RELAY_OPENSKY_RATE_LIMIT_MAX=600
RELAY_RSS_RATE_LIMIT_MAX=300
RELAY_LOG_THROTTLE_MS=10000
RELAY_METRICS_WINDOW_SECONDS=60
```
## 4) How to Verify Configuration
Health:
```bash
curl -sS https://<relay>/health
```
Metrics (requires relay auth):
```bash
curl -sS https://<relay>/metrics \
-H "x-relay-key: $RELAY_SHARED_SECRET"
```
or:
```bash
curl -sS https://<relay>/metrics \
-H "Authorization: Bearer $RELAY_SHARED_SECRET"
```
Expected checks:
- `auth.sharedSecretEnabled` is `true` in `/health`.
- `/metrics.opensky.hitRatio` is stable and high under load.
- `/metrics.ais.dropsPerSec` stays at `0` in normal operation.
- `/metrics.ais.queueMax` is comfortably below `AIS_UPSTREAM_QUEUE_HARD_CAP`.
Reference in New Issue View Git Blame Copy Permalink