dandri/CartoLite-Server

Fork 0

mirror of https://github.com/n30nex/CartoLite-Server.git synced 2026-10-16 11:39:52 +00:00

Files

T

n30nex c87b257d87 Update sound help for the thirty-voice library

2026-09-11 17:31:09 -04:00

6.7 KiB

Raw Blame History

CartoLite Server

A calm, musical live map for your MeshCore network.
Turn a standard MQTT feed into a fast, privacy-safe topology experience you can host yourself.

Start self-hosting · Deployment guide · Privacy boundary · Latest release

_{Live topology across the Great Lakes, with routes coloured by packet type.}

See your mesh move

CartoLite Server renders public MeshCore activity as a living map: packet trails travel hop by hop, recently heard routes hold a restrained glow, and packet types keep distinct colours. Optional Web Audio turns every visible live hop into a musical articulation. Stronger Topo shading and terrain-aware trails, ground rings, and route history add context in 3D; enabling 3D also enables Topo. The worldwide Netgraph adds a stable topology view grouped by Maidenhead grid squares, with touch navigation, synchronized traffic, and node inspection.


_{Inspect a node, its newest neighbours, and connected routes.}	_{Touch-friendly controls keep the map primary on phones.}

Built for community operators


Live topology	Vector geography, packet trails, route glow, packet-type heat, clusters, hillshade, and 3D terrain.
Find and inspect	Search downloaded node labels, open node details, and browse neighbours sorted by last heard.
Musical traffic	A grouped choice of 30 sound voices, using opt-in native browser audio and visible live hops only.
Works worldwide	Accept valid coordinates anywhere, or apply an exact region allowlist for a shared broker.
Responsive and resilient	Desktop and phone layouts, Live Follow, saved views, and automatic recovery after sleep or network loss.
Small operational footprint	One dependency-light Go service, one atomic checkpoint, no database, and a hardened container.

Privacy is the product boundary

The public API exposes only the minimum sanitized data needed to draw the live topology. CartoLite Server does not publish public keys, observer keys, raw paths, packet bodies, decoded messages, or resolver details. It includes no visitor analytics, accounts, chat, or message history.

See the exact guarantees in the privacy documentation and the stable public API v2 contract.

Quick start

You need Docker Engine, Docker Compose v2, a standard MeshCore MQTT feed, and your own CARTO Basemaps browser key.

Important

No API keys, passwords, or tokens are bundled with this repository. .env and .secrets/ are excluded from Git and the Docker build context.

Copy .env.example to .env.
Create .secrets/carto-basemap-api-key and place only your CARTO browser key in it.
Set MQTT_BROKER_URL, MQTT_TOPIC, and any optional MQTT credentials in .env.
Build and start your instance:

docker compose build --pull
docker compose up -d
curl --fail http://127.0.0.1:8080/readyz

The default bind is loopback-only. Keep it that way behind a TLS reverse proxy, or deliberately set CARTOLITE_BIND_ADDR=0.0.0.0 for trusted LAN access. The deployment guide covers production configuration and updates.

MQTT input

MQTT bridge envelopes are limited to 64 KiB before normalization, and RF evidence must contain finite numbers. The geographic map requires WebGL2; Netgraph uses Canvas2D.

The subscriber defaults to meshcore/# and accepts the standard topic shape:

meshcore/<region>/<publisher-key>/packets
meshcore/<region>/<publisher-key>/status

REGION_ALLOWLIST is empty by default, so every syntactically valid region is accepted. Set it to exact comma-separated labels such as EU_WEST,AU_NSW when a shared broker should feed separate public maps. Use MQTT_TOPIC to narrow the subscription itself.

The server accepts the standard packet/status JSON or raw packet hex published by a MeshCore MQTT bridge. Unknown topic shapes and malformed messages are counted and ignored.

Basemap key

Docker supplies the CARTO key to the web build through a BuildKit secret. It stays out of source, Compose, image labels, and build logs. Like any browser map credential, it is visible to visitors in tile requests after deployment, so use a CARTO project key restricted for your site.

CartoLite Server does not publish a universal prebuilt image because each operator builds the frontend with their own browser-visible basemap key.

Project scope

This repository contains the standalone server, browser map, and worldwide Netgraph. It has no country boundary, default region allowlist, Android app, Labs, analytics, database, chat, history, or operator dashboard.

Documentation

License

MIT. CartoLite Server is derived from the CartoLite map system and keeps its privacy-first public-data boundary.

6.7 KiB Raw Blame History