tools/mqtt-bridge/deploy/: mosquitto.conf, acl.conf, the auth-sync
scripts, and a compose file for a standalone broker.
The all-in-one stack and the
deploy tool wire the same broker and
auth sync for you. This page is for running the broker on its own.
Prerequisites
- A self-hosted Convex backend. The auth sync reads its site origin (
:3211). See Mission Control and Convex. - Docker and Docker Compose on the broker host.
mosquitto_passwdships inside theeclipse-mosquittoimage. - A TLS front for the broker: a tunnel or a reverse proxy. The agent never
dials plaintext, and an HTTPS GCS needs
wss://.
The compose stack
tools/mqtt-bridge/deploy/docker-compose.yml runs two services:
The repository has no forwarding service between the broker and Convex. Fleet
status reaches Convex through the agent’s own heartbeat.
Listeners and TLS
mosquitto.conf declares two plaintext listeners and no TLS listener:
- 1883, MQTT over TCP. Keep it on the host or the Docker network. The agent does not use it.
- 9001, MQTT over WebSocket (
protocol websockets). The TLS front forwards to it.
-
With the default
server.mqtt_transport: websockets, the agent dialswss://<mqtt_broker>:443/mqtt. Put a TLS-terminating proxy or tunnel on 443 that forwards/mqttto the 9001 listener. -
With
server.mqtt_transport: tcp, the agent speaks MQTT over TLS onmqtt_port. Add a TLS listener tomosquitto.conf, for example:and set the agent’sserver.self_hosted.mqtt_portto8883.
wss:// through the same front. Tell Mission Control
where the broker is by setting MQTT_BROKER_URL on the Convex deployment to the
full WebSocket URL, for example wss://mqtt.example.com/mqtt. The GCS reads it
at run time through the public clientConfig query.
Broker authentication
The referencemosquitto.conf ships with authentication on: anonymous access
is off, and the broker checks a password file and a deny-by-default topic ACL.
An operator grant writes only the three uplink topics. A write grant on the
whole subtree would also let a browser publish the agent’s own topics and fake
telemetry for the aircraft. A publish the ACL refuses at QoS 0 is dropped
silently, so confirm a publish by subscribing.
The
ados service account stays in the password file and the ACL. The auth
sync writes it on every pass from BRIDGE_MQTT_USERNAME and
BRIDGE_MQTT_PASSWORD.
Keep the password file and ACL in sync
Agent and operator credentials come from Convex, sopasswd and acl.conf are
generated, not hand-written. scripts/regenerate-passwd.sh fetches them from
the /admin/mqtt-auth-entries HTTP action with
Authorization: Bearer $MQTT_AUTH_RELAY_SECRET, rewrites both files in place
and sends the broker a SIGHUP. It aborts if MQTT_AUTH_RELAY_SECRET is unset.
MQTT_AUTH_RELAY_SECRET is required. Generate it once and set the same value
in two places:
.env as MQTT_AUTH_RELAY_SECRET=<value>.
How the sync runs:
- All-in-one stack. The
mqtt-auth-syncservice intools/selfhost/docker-compose.ymlruns the script every 30 seconds (SYNC_INTERVAL_SECONDS). It shares the broker’s PID namespace to deliver the reload, so no Docker socket is mounted. A failed pass retries on the same interval, and a newly paired drone connects after the next good pass. - Standalone broker. Run
regenerate-passwd.shfrom a systemd timer or cron on the broker host, withCONVEX_HTTP_URLset to your site origin andBROKER_CONTAINERnaming the broker container.
acl.conf from
tools/mqtt-bridge/deploy/acl.conf, then create passwd with the service
account:
Bench mode (no auth)
For a local bench or CI fixtures,mosquitto.conf carries a commented bench
block that turns anonymous access on. Never run an internet-facing broker with
allow_anonymous true.
Verify it works
Once the stack is up andpasswd is populated, check each principal from
inside the broker container:
Next steps
Video relay
Add live video alongside the data planes.
Ports and troubleshooting
Every port in the stack and the common failure modes.