truenas-stacks/docs/reference/MESHTASTIC.md

Meshtastic Stack

Overview

Self-hosted MeshMonitor stack running on PlausibleDeniability, plus the current operator note for the separate NOMAD-side MeshCore companion observer.

Related NOMAD-side bridge note: the legacy mctomqtt Docker relay was retired on 2026-06-13. N.O.M.A.D. now uses the LetsMesh companion observer flow via meshcore-capture.service, running from /home/fizzlepoof/.meshcore-packet-capture and connecting directly to the Heltec over /dev/serial/by-id/....

Important split:

• PD hosts the MeshMonitor web/UI stack.
• NOMAD owns the USB-attached Heltec companion observer via meshcore-capture.service.
• Do not assume MeshMonitor and the companion observer are the same runtime path.

Stack Location

/mnt/docker-ssd/docker/compose/meshtastic/

Containers

Container	Image	Port	Purpose
meshmonitor	ghcr.io/yeraze/meshmonitor:latest	8081→3001, 4404→4404, 1883→1883	Main UI + backend; live compose publishes the virtual-node port and embedded MQTT broker directly from this container, and now maps /dev/ttyACM0 into the container for native MeshCore USB sources
meshmonitor (virtual node)	—	4404	TCP virtual node server exposed directly by the meshmonitor container
meshmonitor (embedded MQTT broker)	—	1883	Embedded Aedes-based MQTT broker exposed directly by the meshmonitor container
meshmonitor-tileserver	maptiler/tileserver-gl-light:latest	8082→8080	Offline map tiles
meshmonitor-upgrader	docker:latest	—	Auto-upgrade watchdog

Live runtime verified on 2026-07-03:

• docker compose ps on PD showed meshmonitor, meshmonitor-tileserver, and meshmonitor-upgrader running.
• Repo compose and live runtime now agree that there is no separate meshmonitor-mqtt-proxy sidecar in the active stack.
• The embedded MQTT broker source Meshcore Peachtree Observer is configured in MeshMonitor and logs MQTT broker listening on 0.0.0.0:1883.
• A native MeshCore USB source PT Meshcore is now auto-connected in MeshMonitor via /dev/ttyACM0 after the compose file was updated to map the device into the container.
• NOMAD meshcore-capture.service was later returned to its three upstream brokers after the embedded-broker test path proved unnecessary for real MeshCore ingestion.

Architecture

Trusted-LAN mesh node (10.5.1.120)
        ↓ direct node connection configured by MESHTASTIC_NODE_IP
meshmonitor backend on PD
        ↓
PostgreSQL (shared-postgres, db: meshmonitor)

Separate path:
NOMAD Heltec companion observer (`meshcore-capture.service`)
        ↓ upstream MQTT brokers (LetsMesh US / EU + NashMe)

PD native MeshCore USB source (`PT Meshcore`)
        ↓ `/dev/ttyACM0` mapped into the meshmonitor container
        ↓ meshcore.js native companion backend

Note: the embedded MeshMonitor broker now accepts the NOMAD connection on 10.5.30.6:1883, but current MeshMonitor logs still show protobuf decode warnings for MeshCore packet payloads. Treat this as confirmed broker fanout connectivity, not yet confirmed first-class MeshCore ingestion.

Node Connection

• PD MeshMonitor compose is currently configured with MESHTASTIC_NODE_IP=10.5.1.120
• MeshMonitor itself publishes port 4404 for the virtual-node path and 1883 for the embedded MQTT broker; there is no separate meshmonitor-mqtt-proxy service in the active stack
• For native MeshCore USB sources on PD, the live compose now maps /dev/ttyACM0 directly into the meshmonitor container
• NOMAD's companion observer is a different ingest path and should not be documented as a MeshMonitor sidecar

Storage

• Appdata: /mnt/tank/docker/appdata/meshmonitor/data → /data
• Scripts: ./scripts → /data/scripts (must be pre-created on host)
• Tiles: ./tiles (gitignored — large .mbtiles files)

Auto-Upgrade

AUTO_UPGRADE_ENABLED=true — meshmonitor checks for new images and triggers self-upgrade.

Important: The upgrader mounts the compose directory as /compose inside the container. All relative bind mount paths (e.g. ./scripts) resolve to /compose/scripts on the host when the upgrader re-runs compose. Since TrueNAS root filesystem is read-only, these directories must be pre-created:

mkdir -p /mnt/docker-ssd/docker/compose/meshtastic/scripts

Networks

• default (internal stack network)
• ix-databases_shared-databases (meshmonitor only)
• pangolin (meshmonitor + tileserver)

Public URL

https://meshmonitor.paccoco.com

Known Warnings

• Node !dd972536 has a low-entropy public key — this is a device configuration issue, not a meshmonitor bug
• MeshMonitor logs can still show noisy reconnect/admin-session churn during node or radio instability; do not confuse that with the retired NOMAD mctomqtt path

Tiles

Map tiles stored in ./tiles/. Currently includes zurich_switzerland.mbtiles (34MB). Tiles directory is gitignored. To add new tiles, download .mbtiles files and place in the tiles/ directory.

TODO

• Document all running meshtastic-map container config
• Add healthcheck to meshmonitor container