meshcore-analyzer/config.example.json

{
  "port": 3000,
  "apiKey": "your-secret-api-key-here",
  "nodeBlacklist": [],
  "_comment_nodeBlacklist": "Public keys of nodes to hide from all API responses. Use for trolls, offensive names, or nodes reporting false data that operators refuse to fix.",
  "observerIATAWhitelist": [],
  "_comment_observerIATAWhitelist": "Global IATA region whitelist. When non-empty, only observers whose IATA code (from MQTT topic) matches are processed. Case-insensitive. Empty = allow all. Unlike per-source iataFilter, this applies across all MQTT sources.",
  "retention": {
    "nodeDays": 7,
    "observerDays": 14,
    "packetDays": 30,
    "_comment": "nodeDays: nodes not seen in N days moved to inactive_nodes (default 7). observerDays: observers not sending data in N days are removed (-1 = keep forever, default 14). packetDays: transmissions older than N days are deleted (0 = disabled). NOTE (#1283): all four retention fields are consumed by the INGESTOR process. The server is read-only and never prunes."
  },
  "db": {
    "vacuumOnStartup": false,
    "incrementalVacuumPages": 1024,
    "load": {
      "chunkSize": 10000,
      "_comment": "chunkSize: rows fetched per chunk by PacketStore.LoadChunked during startup (#1009). Default 10000. Lower values surface the early-HTTP-readiness signal sooner (the listener binds after the first chunk) at the cost of more SQL round-trips. Higher values reduce per-chunk overhead but delay first-chunk readiness. The X-CoreScope-Load-Status response header reports loading|ready and progress=<rows> until the load completes."
    },
    "_comment": "vacuumOnStartup: run one-time full VACUUM to enable incremental auto-vacuum on existing DBs. Executed by the INGESTOR at startup, BEFORE the MQTT subscriber starts (#1283), so there is no contention with concurrent writes. Blocks ingestor startup for minutes on large DBs; requires 2x DB file size in free disk space. incrementalVacuumPages: free pages returned to OS after each retention reaper cycle (default 1024). See #919. load.chunkSize: see nested _comment (#1009).",
    "_comment_slowWriterMs": "#1340 — SQLite writer-lock log threshold (default 500). Any wrapped writer call (tagged neighbor_builder, mqtt_handler, prune_packets, prune_observers, prune_metrics, vacuum) whose hold_ms exceeds this emits a single [db-slow-writer] log line. Configured per-process via the CORESCOPE_DB_SLOW_WRITER_MS environment variable on the INGESTOR (e.g. CORESCOPE_DB_SLOW_WRITER_MS=200 for tighter alerting). Per-component wait_ms / hold_ms / contention_total histograms are surfaced via /api/perf/write-sources under .writer_perf regardless of this threshold."
  },
  "listLimits": {
    "packetsMax": 10000,
    "nodesMax": 2000,
    "analyticsMax": 200,
    "channelMessagesMax": 500,
    "bulkHealthMax": 200,
    "_comment": "Maximum row counts returned by list API endpoints. These enforce a DoS-bounded ceiling for both UI and external requests. Operators with small/embedded deployments can tighten these; operators running large regional meshes can raise them. bulkHealthMax is intentionally separate from nodesMax: /api/nodes/bulk-health is per-row much heavier than /api/nodes (it joins per-node observer health + recent-packet stats) so its ceiling stays low (default 200) even if nodesMax is raised."
  },
  "_comment_ingestorStats": "Ingestor publishes a 1-Hz stats snapshot consumed by the server's /api/perf/io and /api/perf/write-sources endpoints (#1120). Path is configured via the CORESCOPE_INGESTOR_STATS environment variable on the INGESTOR process. Default: /tmp/corescope-ingestor-stats.json. The writer uses O_NOFOLLOW + 0o600, so a pre-planted symlink in /tmp cannot be used to clobber an arbitrary file. SECURITY: in shared-tmp environments (multi-tenant hosts), point CORESCOPE_INGESTOR_STATS at a private directory like /var/lib/corescope/ingestor-stats.json that only the corescope user can write to.",
  "corsAllowedOrigins": [],
  "_comment_corsAllowedOrigins": "Cross-origin allowlist for embed scenarios (#1369). Exact-match origins, e.g. [\"https://blog.example.com\", \"https://embed.example.com\"]. When empty (default), no Access-Control-* headers are sent and browsers enforce same-origin. When non-empty, only the listed origins receive CORS headers, and Access-Control-Allow-Methods is limited to GET, HEAD, OPTIONS (the cross-domain surface is read-only — same-origin admin writes are unaffected). Use [\"*\"] to allow any origin (NOT recommended for write-capable deployments). Operators can override per-deployment with the CORS_ALLOWED_ORIGINS environment variable (comma-separated). No credentialed CORS is enabled. To embed the map or channels pages cross-domain, add the embedding origin here and use the URL pattern '/#/map?embed=1' or '/#/channels?embed=1' — embed mode hides the top-nav, bottom-nav, and side drawer for full-bleed iframe rendering.",
  "https": {
    "cert": "/path/to/cert.pem",
    "key": "/path/to/key.pem",
    "_comment": "TLS cert/key paths for direct HTTPS. Most deployments use Caddy (included in Docker) for auto-TLS instead."
  },
  "branding": {
    "siteName": "CoreScope",
    "tagline": "Real-time MeshCore LoRa mesh network analyzer",
    "logoUrl": null,
    "faviconUrl": null,
    "homeUrl": null,
    "_comment": "Customize site name, tagline, logo, and favicon. logoUrl/faviconUrl can be absolute URLs or relative paths. homeUrl (#1518) overrides the navbar logo link target — set to an absolute http(s):// URL for operators embedding CoreScope inside a larger site, or a '#'-prefixed app route (e.g. '#/home') to keep it in-app. Validator rejects javascript:, data:, vbscript:, file:, about:, protocol-relative '//', and bare paths to block XSS. Cross-origin URLs open in the SAME tab (no target=_blank); wrap with your own anchor if you need new-tab behavior. The mobile bottom-nav 🏠 button is intentionally NOT overridden — it stays in-app to preserve SPA back-stack on phones."
  },
  "theme": {
    "accent": "#4a9eff",
    "accentHover": "#6db3ff",
    "navBg": "#0f0f23",
    "navBg2": "#1a1a2e",
    "navActiveBg": "rgba(74,158,255,0.15)",
    "statusGreen": "#45644c",
    "statusYellow": "#b08b2d",
    "statusRed": "#b54a4a",
    "_comment": "CSS color overrides. Use the in-app Theme Customizer for live preview, then export values here. navActiveBg (#1509) controls the background of the currently-active top-nav link (the 'pill'); accepts any CSS color, typically a translucent rgba() so the nav gradient shows through."
  },
  "nodeColors": {
    "repeater": "#dc2626",
    "companion": "#2563eb",
    "room": "#16a34a",
    "sensor": "#d97706",
    "observer": "#8b5cf6",
    "_comment": "Marker/badge colors per node role. Used on map, nodes list, and live feed."
  },
  "markerStroke": {
    "color": "#fff",
    "width": 2,
    "opacity": 1,
    "_comment": "#1488/#1506 — outline around each map marker (live + map pages). Defaults restored to v3.7.2 visual (solid white, 2px). 'color' accepts any CSS color (hex, rgb, rgba); use rgba() or drop 'opacity' below ~0.5 to soften the outline when hundreds of nodes feel overwhelming. 'width' is the SVG stroke width (0 hides the outline entirely). Operators can override per-browser via the in-app Theme Customizer (Colors tab → Marker Stroke)."
  },
  "map": {
    "tiles": {
      "darkDefault": "carto-dark",
      "lightDefault": "carto-light",
      "providers": {
        "_comment_carto": "Carto is the default free-tier provider. Optional: specify 'domain' for Carto enterprise (e.g. 'mycompany' for 'https://{s}.mycompany.cartocdn.com').",
        "carto": {
          "enabled": true,
          "domain": ""
        },
        "_comment_osm": "OSM providers: 'mapbox', 'thunderforest', 'maptiler'. WARNING: Tokens are sent to the browser. Apply origin/referrer restrictions in your provider dashboard.",
        "osm": {
          "enabled": false,
          "provider": "",
          "token": ""
        },
        "_comment_stamen": "Stamen (hosted by Stadia). WARNING: Tokens are sent to the browser. Apply origin/referrer restrictions.",
        "stamen": {
          "enabled": false,
          "token": ""
        }
      }
    }
  },
  "home": {
    "heroTitle": "CoreScope",
    "heroSubtitle": "Find your nodes to start monitoring them.",
    "steps": [
      {
        "emoji": "\ud83d\udce1",
        "title": "Connect",
        "description": "Link your node to the mesh"
      },
      {
        "emoji": "\ud83d\udd0d",
        "title": "Monitor",
        "description": "Watch packets flow in real-time"
      },
      {
        "emoji": "\ud83d\udcca",
        "title": "Analyze",
        "description": "Understand your network's health"
      }
    ],
    "checklist": [
      {
        "question": "How do I add my node?",
        "answer": "Search for your node name or paste your public key."
      },
      {
        "question": "What regions are covered?",
        "answer": "Check the map page to see active observers and nodes."
      }
    ],
    "footerLinks": [
      {
        "label": "\ud83d\udce6 Packets",
        "url": "#/packets"
      },
      {
        "label": "\ud83d\uddfa\ufe0f Network Map",
        "url": "#/map"
      },
      {
        "label": "\ud83d\udd34 Live",
        "url": "#/live"
      },
      {
        "label": "\ud83d\udce1 All Nodes",
        "url": "#/nodes"
      },
      {
        "label": "\ud83d\udcac Channels",
        "url": "#/channels"
      }
    ],
    "_comment": "Customize the landing page hero, onboarding steps, FAQ, and footer links."
  },
  "mqtt": {
    "broker": "mqtt://localhost:1883",
    "topic": "meshcore/+/+/packets",
    "_comment": "Legacy single-broker config. Prefer mqttSources[] for multiple brokers."
  },
  "mqttSources": [
    {
      "name": "local",
      "broker": "mqtt://localhost:1883",
      "topics": [
        "meshcore/+/+/packets",
        "meshcore/#"
      ]
    },
    {
      "name": "lincomatic",
      "broker": "mqtts://mqtt.lincomatic.com:8883",
      "username": "your-username",
      "password": "your-password",
      "rejectUnauthorized": false,
      "topics": [
        "meshcore/SJC/#",
        "meshcore/SFO/#",
        "meshcore/OAK/#",
        "meshcore/MRY/#"
      ],
      "iataFilter": [
        "SJC",
        "SFO",
        "OAK",
        "MRY"
      ],
      "region": "SJC",
      "connectTimeoutSec": 45
    },
    {
      "_comment": "WebSocket MQTT broker (e.g. meshcore-mqtt-broker). Use ws:// for plain WebSocket or wss:// for TLS. Username/password supported.",
      "name": "wsmqtt",
      "broker": "wss://wsmqtt.example.com/mqtt",
      "username": "corescope",
      "password": "your-password",
      "topics": [
        "meshcore/#"
      ]
    }
  ],
  "channelKeys": {
    "Public": "8b3387e9c5cdea6ac9e5edbaa115cd72"
  },
  "hashChannels": [
    "#LongFast",
    "#test",
    "#sf",
    "#wardrive",
    "#yo",
    "#bot",
    "#queer",
    "#bookclub",
    "#shtf"
  ],
  "healthThresholds": {
    "infraDegradedHours": 24,
    "infraSilentHours": 72,
    "nodeDegradedHours": 1,
    "nodeSilentHours": 24,
    "relayActiveHours": 24,
    "observerOnlineMinutes": 60,
    "observerStaleMinutes": 1440,
    "_comment": "How long (hours) before nodes show as degraded/silent. 'infra' = repeaters & rooms, 'node' = companions & others. relayActiveHours: a repeater is shown as 'actively relaying' if its pubkey appeared as a path hop in a non-advert packet within this window (issue #662).",
    "_comment_observerThresholds": "Observer health classification. Online: last_seen < observerOnlineMinutes ago. Stale: between Online and observerStaleMinutes. Offline: beyond observerStaleMinutes. Defaults 60 / 1440 (1h / 24h) match the node thresholds for consistency and eliminate flap on low-traffic / CDN-fronted instances (#1552). Operators who want the old aggressive 10-min Online threshold can set observerOnlineMinutes: 10."
  },
  "defaultRegion": "SJC",
  "mapDefaults": {
    "center": [
      37.45,
      -122.0
    ],
    "zoom": 9
  },
  "geo_filter": {
    "polygon": [
      [37.80, -122.52],
      [37.80, -121.80],
      [37.20, -121.80],
      [37.20, -122.52]
    ],
    "bufferKm": 20,
    "_comment": "Optional. Restricts ingestion and API responses to nodes within the polygon + bufferKm. Polygon is an array of [lat, lon] pairs (minimum 3). Use the GeoFilter tab in the Customizer (requires apiKey) or the GeoFilter Builder (`/geofilter-builder.html`) to draw a polygon visually and export a config snippet. Remove this section to disable filtering. Nodes with no GPS fix are always allowed through."
  },
  "foreignAdverts": {
    "mode": "flag",
    "_comment": "Controls how the ingestor handles ADVERTs whose GPS is OUTSIDE the geo_filter polygon (#730). 'flag' (default): store the advert/node and tag it foreign_advert=1 so operators can see bridged/leaked nodes via the API ('foreign': true on /api/nodes). 'drop': legacy behavior — silently discard the advert (no log, no node row). Only applies when geo_filter is configured; otherwise has no effect."
  },
  "areas": {
    "_comment": "Optional. GPS-based display filter. Each entry defines a geographic area by polygon ([lat, lon] pairs) or bounding box (latMin/latMax/lonMin/lonMax). Packets and nodes are attributed to an area based on the transmitting node's own GPS coordinates — not the observer's location. Areas appear as a filter pill bar in the dashboard. Remove this section to disable the area filter UI.",
    "BAY": {
      "label": "Bay Area",
      "polygon": [
        [37.90, -122.55],
        [37.90, -121.75],
        [37.25, -121.75],
        [37.25, -122.55]
      ]
    },
    "SJC": {
      "label": "San Jose",
      "latMin": 37.20,
      "latMax": 37.45,
      "lonMin": -122.05,
      "lonMax": -121.75
    }
  },
  "regions": {
    "SJC": "San Jose, US",
    "SFO": "San Francisco, US",
    "OAK": "Oakland, US",
    "MRY": "Monterey, US"
  },
  "cacheTTL": {
    "stats": 10,
    "nodeDetail": 300,
    "nodeHealth": 300,
    "nodeList": 90,
    "bulkHealth": 600,
    "networkStatus": 600,
    "observers": 300,
    "channels": 15,
    "channelMessages": 10,
    "analyticsRF": 1800,
    "_comment_analyticsRF": "TTL (seconds) for the shared analytics result cache. Backs /api/analytics/rf, /api/analytics/topology, /api/analytics/distance, /api/analytics/hash-sizes, /api/analytics/channels, /api/analytics/subpaths. Default 60s if unset (#1239) — distance analytics is viewed live during active analysis, so the default smooths cold-miss churn without freezing data. Lower with care; sub-15s values can cause repeated multi-second cold computes during heavy ingest.",
    "analyticsTopology": 1800,
    "analyticsChannels": 1800,
    "analyticsHashSizes": 3600,
    "analyticsSubpaths": 3600,
    "analyticsSubpathDetail": 3600,
    "nodeAnalytics": 60,
    "nodeSearch": 10,
    "invalidationDebounce": 30,
    "_comment": "All values in seconds. Server uses these directly. Client fetches via /api/config/cache."
  },
  "liveMap": {
    "propagationBufferMs": 5000,
    "_comment": "How long (ms) to buffer incoming observations of the same packet before animating. Mesh packets propagate through multiple paths and arrive at different observers over several seconds. This window collects all observations of a single transmission so the live map can animate them simultaneously as one realistic propagation event. Set higher for wide meshes with many observers, lower for snappier animations. 5000ms captures ~95% of observations for a typical mesh.",
    "maxNodes": 2000,
    "_comment_maxNodes": "Maximum nodes the /live map fetches (and renders) in one page. Default 2000. Raise this on deployments that have measured perf headroom on mid-range mobile (heap + frame-time). Server clamps to [100, 20000]: misconfigured values are coerced silently. Also caps the matching /api/packets?limit fetch the live VCR-rewind code uses. Reporter: #1574."
  },
  "timestamps": {
    "defaultMode": "ago",
    "timezone": "local",
    "formatPreset": "iso",
    "customFormat": "",
    "allowCustomFormat": false,
    "_comment": "defaultMode: ago|local|iso. timezone: local|utc. formatPreset: iso|us|eu. customFormat: strftime-style (requires allowCustomFormat: true)."
  },
  "packetStore": {
    "maxMemoryMB": 1024,
    "estimatedPacketBytes": 450,
    "retentionHours": 168,
    "hotStartupHours": 0,
    "_comment": "In-memory packet store. maxMemoryMB caps RAM usage. retentionHours: only packets younger than this are kept in memory (0 = unlimited). hotStartupHours: hours loaded synchronously at startup; background loader fills the remaining retentionHours window. 0 = disabled (loads full retentionHours synchronously, legacy behavior). Set to a positive value (e.g. 24) to reduce startup time on large DBs.",
    "_comment_gomemlimit": "On startup the server reads GOMEMLIMIT from the environment if set; otherwise it derives a Go runtime soft memory limit of maxMemoryMB * 1.5 and applies it via debug.SetMemoryLimit. This forces aggressive GC under cgroup pressure so the process self-throttles before the kernel SIGKILLs it. To override, set GOMEMLIMIT explicitly (e.g. GOMEMLIMIT=850MiB). See issue #836."
  },
  "runtime": {
    "maxMemoryMB": 0,
    "_comment_runtime_maxMemoryMB": "Go soft memory limit (GOMEMLIMIT) in MiB applied via runtime/debug.SetMemoryLimit at startup. Precedence: GOMEMLIMIT env var > runtime.maxMemoryMB > packetStore.maxMemoryMB-derived (server only). 0 (default) preserves existing behavior. Set on memory-constrained deployments (2 GB Pi, 4 GB VMs) to trigger earlier GC and avoid container OOM-kill. Floor recommendation: ≥1.5× working set; setting below the working set causes a GC death-spiral. Applies to BOTH cmd/server and cmd/ingestor. See #1010."
  },
  "resolvedPath": {
    "backfillHours": 24,
    "_comment": "How far back (hours) the async backfill scans for observations with NULL resolved_path. Default: 24. Set higher to backfill older data, lower to speed up startup."
  },
  "neighborGraph": {
    "maxAgeDays": 5,
    "maxEdgeKm": 500,
    "cacheRecomputeIntervalSeconds": 300,
    "_comment": "maxAgeDays: neighbor edges older than this many days are pruned on startup and daily. Default 5. maxEdgeKm: geo-implausibility filter — when both endpoints have GPS, edges with haversine distance > maxEdgeKm are rejected at build time to prevent disambiguator self-reinforcement on wide-geo MQTT deployments. Default 500 km (well above any plausible terrestrial LoRa hop). 0 ⇒ use default; set negative to disable the filter. Rejected count surfaces in /api/analytics/neighbor-graph stats. Issue #1228. cacheRecomputeIntervalSeconds: how often the background recomputer rebuilds the default-shape /api/analytics/neighbor-graph response (#1481 P0-1). Default 300 (5 min). Lower = fresher data, more CPU per minute. Issue #1483."
  },
  "observersCache": {
    "ttlSeconds": 30,
    "_comment": "TTL for the default-shape /api/observers response cache (#1481 P0-3). Default 30s. Lower = fresher data, more SQL pressure on the 1.9M-row observations table. TTL-boundary refills are collapsed via singleflight so concurrent requests cause exactly one SQL fill. Issue #1483."
  },
  "batteryThresholds": {
    "lowMv": 3300,
    "criticalMv": 3000,
    "_comment": "Voltage cutoffs (millivolts) for the per-node battery trend chart on /node-analytics. Latest sample below lowMv shows the node as ⚠️ Low; below criticalMv shows 🪫 Critical. Both default to 3300 / 3000 if omitted. Source data: observer_metrics.battery_mv populated from observer status messages; only nodes that are themselves observers (matching pubkey ↔ observer id) yield a series. Issue #663."
  },
  "_comment_mqttSources": "Each source connects to an MQTT broker. Supported schemes: mqtt:// (plain TCP), mqtts:// (TLS), ws:// (WebSocket), wss:// (WebSocket TLS). topics: what to subscribe to. iataFilter: only ingest packets from these regions (optional). region: default IATA region for this source — used when packet/topic doesn't specify one (optional, priority: payload > topic > this field).",
  "compression": {
    "gzip": false,
    "websocket": false,
    "level": 6,
    "minSizeBytes": 1024,
    "contentTypes": [
      "application/json",
      "application/javascript",
      "application/xml",
      "text/html",
      "text/css",
      "text/plain",
      "image/svg+xml"
    ]
  },
  "_comment_compression": "Opt-in HTTP gzip middleware + WebSocket permessage-deflate. Both default to false — enable ONLY when your upstream reverse proxy is NOT already compressing. gzip: enables the gzipMiddleware wrapper around the HTTP handler. websocket: sets gorilla websocket Upgrader.EnableCompression. level: gzip compression level 1..9 (1=BestSpeed, 9=BestCompression, default 6). minSizeBytes: advisory minimum response size below which compression would not pay off. contentTypes: MIME allow-list — only responses with these Content-Type values are compressed. Already-compressed types (image/*, video/*, audio/*, application/zip, application/x-gzip, application/pdf, application/octet-stream) are always skipped, as are responses whose handler already set Content-Encoding. Omit contentTypes to use the built-in default allow-list.",
  "_comment_channelKeys": "Hex keys for decrypting channel messages. Key name = channel display name. public channel key is well-known.",
  "_comment_hashChannels": "Channel names whose keys are derived via SHA256. Key = SHA256(name)[:16]. Listed here so the ingestor can auto-derive keys.",
  "hashRegions": [
    "#belgium",
    "#eu"
  ],
  "_comment_hashRegions": "Region names for scope matching on transport-route packets. Key = SHA256('#name')[:16]. Add any region names used by nodes in your network.",
  "_comment_defaultRegion": "IATA code shown by default in region filters.",
  "_comment_mapDefaults": "Initial map center [lat, lon] and zoom level.",
  "_comment_regions": "IATA code → display name mapping for the region filter UI. Each key is a 3-letter IATA code that an observer is tagged with (resolved priority: MQTT payload `region` field > topic-derived region > mqttSources.region). Observers without an IATA tag will not appear under any region filter — only under 'All Regions'. The region filter dropdown shows one entry per code listed here PLUS any extra IATA codes the server discovers from observers at runtime (so you can omit codes here and they will still be selectable, just labelled with the bare IATA code instead of a friendly name). Selecting 'All Regions' (or no region) returns results from every observer including those with no IATA tag; selecting one or more codes restricts results to packets observed by observers tagged with those codes. The reserved value 'All' (case-insensitive) is treated as 'no filter' on the server, so the URL ?region=All behaves identically to omitting the param. Issue #770.",

  "analytics": {
    "defaultIntervalSeconds": 300,
    "recomputeIntervalSeconds": {
      "topology": 300,
      "rf": 300,
      "distance": 300,
      "channels": 300,
      "hashCollisions": 300,
      "hashSizes": 300,
      "roles": 300,
      "observersClockSkew": 300,
      "nodesClockSkew": 300
    }
  },
  "_comment_analytics": "Issue #1240 + #1256 + #1265. Each analytics endpoint (topology, rf, distance, channels, hashCollisions, hashSizes, roles, observersClockSkew, nodesClockSkew) is recomputed in the background on the configured interval and served from an atomic-pointer cache. Reads never block on compute. Default 300s (5 min) per endpoint reflects the operator principle: serving slightly stale data quickly beats real-time data slowly. Lower values = fresher data at higher CPU cost. Only the default query (no region/window) is precomputed; region- and window-filtered requests fall back to the legacy on-request compute + 60s TTL cache.",
  "customizer": {
    "disabledTabs": [],
    "_comment_disabledTabs": "Issue #1508. List of customizer-modal tab ids to hide from end users. Useful when operators want to expose only daily-use viewer controls and keep one-shot admin chrome out of the way. Recognized ids: branding, theme, nodes, home, display, geofilter, export. Example: [\"branding\", \"geofilter\", \"export\"] hides the admin tabs and leaves theme/colors/home/display visible. Default [] keeps the legacy behavior (all tabs visible). Operators edit this in config.json directly — there is no in-app UI for this list (by design)."
  }
}