beacon-server/README.md

MeshCore Beacon

MeshCore Beacon is a MeshCore network observation backend. It connects to one or more MeshCore MQTT brokers, ingests LoRa packet traffic in real time, stores it in PostgreSQL, and streams live events to WebSocket clients.

What it does

• Subscribes to MeshCore MQTT brokers and decodes incoming LoRa packets using meshcore-go
• Stores packets, observations, nodes, observers, traces, routes and channel messages in PostgreSQL
• Deduplicates observations across multiple brokers (the same packet heard by two brokers is one observation per observer)
• Decrypts group text messages for known channel keys
• Detects firmware capability flags from path hash sizes
• Streams live events to WebSocket clients with subscription filtering by IATA, region, payload type, and event type
• Serves a REST API for querying stored data
• Seeds regions, IATA display names, and channel keys from a YAML config file on startup

This repo is the code. Deploying, configuring and operating Beacon is documented in beacon-docs; see Documentation below.

Stack

Component	Technology
Language	Go 1.26
Router	Chi v5
Database	PostgreSQL 16
Caching	Redis 7
DB queries	sqlc + pgx/v5
MQTT	paho.mqtt.golang
WebSocket	coder/websocket
Packet decode	meshcore-go
Config	YAML via gopkg.in/yaml.v3
Env	godotenv

Running it locally

You need Go 1.26+ and a PostgreSQL 16 database. Docker is the easy way to get the database.

git clone https://github.com/MeshCore-Beacon/beacon-server.git && cd beacon-server
cp env.example .env
cp config.yaml.example config.yaml
docker run -d --name beacon-postgres -p 5432:5432 \
  -e POSTGRES_USER=beacon -e POSTGRES_PASSWORD=beacon -e POSTGRES_DB=beacon postgres:16-alpine
go run ./cmd/beacon

Fill in POSTGRES_DSN and your MQTT broker credentials in .env. Every variable is described in Configuration, and the fully annotated config.yaml lives in beacon-docs as well; the copy here is a working starter. Migrations run on startup. The API listens on LISTEN_ADDR (default :8080) and Swagger is at http://localhost:8080/swagger/index.html.

To run the web frontend against it, see Running the full stack locally.

The published image is ghcr.io/meshcore-beacon/beacon-server. latest tracks stable releases, dev follows the development branch, and each release is also tagged X.Y.Z and X.Y.

What you see on an empty database

Path resolution, capability detection and known routes depend on nodes having advertised to a local observer. On a fresh database every hop shows "confidence": "none" and supportsMultibytePaths is false until adverts populate node_short_ids. That is expected and fills in as the mesh is observed.

GRP_TXT packets whose channel key is not known yet are stored hash-only. After adding the key to config.yaml, the next restart decrypts the matching history; look for config: backfilled N previously-undecrypted channel message(s) in the log.

Documentation

In beacon-docs:

• Deploy with Docker
• Getting packets in: brokers, the subscriber account, topics
• Configuration: environment variables and config.yaml
• API contract: REST, WebSocket, admin endpoints
• Reverse proxy and rate limits
• Upgrading
• Operations, backup and export and CPU profiling
• High level design
• Releases and versioning

In this repo: Historical stats explains the hourly rollups behind the stats endpoints, for anyone changing them. docs/swagger.yaml is the generated OpenAPI description.

Contributing

CONTRIBUTING.md covers code style, tests, and database and API changes. Branches, commits and the release flow are shared across the Beacon repos and live in beacon-docs/CONTRIBUTING.md. Please read the Code of Conduct. Security reports go through SECURITY.md.

Acknowledgements

See CONTRIBUTORS.md for the people who have helped build Beacon, and SHOULDERS.md for the open source projects it stands on.