tools/selfhost/ in
ADOSMissionControlGCS (GPL-3.0)
brings up the whole cloud relay on a single host: a self-hosted Convex backend
and its dashboard, the Mission Control web GCS, the Mosquitto broker with its
auth sync, and the video relay. The ados-deploy tool
runs every step on this page for you; follow this page when you want to run
them by hand or change the stack.
You do not need any of this to fly on the LAN. Served over plain HTTP, Mission
Control connects straight to the agent and pairs over the local network with no
backend. The cloud relay is the opt-in path for reaching a drone across
networks.
Services
The compose project directory isselfhost, so Compose names the containers
selfhost-<service>-1. Published host ports are listed once, in the
port table.
mqtt-auth-sync shares the broker’s PID namespace so it can send Mosquitto a
SIGHUP after each rewrite. No Docker socket is mounted. The broker itself is
covered on Self-hosting: MQTT broker.
The two Convex origins
A self-hosted Convex backend exposes two origins, and they are not interchangeable:- The client API origin (
:3210) is what the GCS browser bundle talks to (NEXT_PUBLIC_CONVEX_URL).npx convex deployandnpx convex env setalso target it. - The site origin (
:3211) serves HTTP actions. The drone agent heartbeat and pairing, andmqtt-auth-sync(CONVEX_URL), talk to it.
Environment
Copy the example file and edit it before bringing anything up.The client API origin the backend advertises, for example
http://192.168.1.50:3210. Use your LAN IP or hostname.The client API origin (
:3210) baked into the GCS build. This is a build
argument, inlined when the image is built, not read at runtime.The password for that principal. You also write it into the broker password
file in the setup steps below.
The bearer
mqtt-auth-sync presents to Convex to fetch broker credentials.
Generate with openssl rand -hex 32 and set the same value on Convex. Without
it the broker never learns about paired devices.The RTSP source the video relay pulls from.
{deviceId} is replaced with the
drone’s device ID.The secret the relay verifies viewer tokens with. Generate with
openssl rand -hex 32 and set the same value on Convex, which mints the
tokens. The relay refuses to start while it is empty.Setup
The backend needs its functions and auth keys before the rest of the stack is useful, so the order matters. Run every command fromtools/selfhost.
1
Load the environment into your shell
Later steps read values from
.env. Export them into the current shell:2
Start the backend
3
Generate the admin key
The admin key is generated inside the backend container:Store it in a secrets manager. The commands below use it as
<admin-key>.4
Push Convex functions and schema
From a machine with the repo checked out, deploy the functions to your
:3210 origin:5
Generate and set the auth keys and secrets
The helper script prints
JWT_PRIVATE_KEY and JWKS lines. Evaluate them
into the shell, then set them, the GCS origin and both relay secrets on the
backend:SITE_URL is the origin the browser loads the GCS from, not a Convex
origin.6
Seed the broker credential files
The broker mounts its password file and ACL as files, so both must exist
before its first start. Otherwise Docker creates directories at those
paths.From then on
mqtt-auth-sync keeps both files current: it adds every
paired agent and every live operator grant, so a newly paired agent can
connect with no manual step.7
Bring up everything
Publish the relay URLs
The GCS reads the broker and relay addresses from Convex at runtime. Set them to however you expose Mosquitto’s WebSocket listener and the relay:Point the agent at the stack
Set the drone’sserver.mode to self_hosted and point both
server.self_hosted.url and pairing.convex_url at the site origin
(:3211). The full procedure is on
Self-hosting: Drone Agent.
Expose the stack through a Cloudflare tunnel
Browser cloud mode needs HTTPS. A Cloudflare tunnel gives each service a TLS hostname with no inbound port open on the host:cloudflared keeps outbound
connections to Cloudflare’s edge. Any TLS reverse proxy that forwards
WebSocket upgrades works the same way.
1
Install cloudflared
On a Debian or Ubuntu host:
2
Create a tunnel
3
Route a hostname to each service
Create Add a DNS route for each hostname with
~/.cloudflared/config.yml. Each hostname maps to one published
port:cloudflared tunnel route dns ados-relay <hostname>.4
Start the tunnel
5
Use the HTTPS origins everywhere
Rebuild the GCS with
NEXT_PUBLIC_CONVEX_URL=https://convex.cloud.example.com,
set SITE_URL to https://gcs.cloud.example.com, set MQTT_BROKER_URL
and VIDEO_RELAY_URL to the wss:// hostnames, and point the agent at
https://convex-site.cloud.example.com.Verify
curl http://192.168.1.50:3210/versionreturns a version, so the backend answers on the client API origin.docker compose logs mqtt-auth-syncshows nosync failed; retryinglines, soMQTT_AUTH_RELAY_SECRETmatches on both sides.docker compose logs video-relayshowsVideo relay listening on port 3001, soVIDEO_RELAY_SECRETis set.- Sign-in works in the GCS, so the auth keys are on the right deployment.
- A paired drone appears in the fleet, so its heartbeat reached the
:3211site origin.
npx convex deploy
on every upgrade; the GCS image does not push them on boot.
Next steps
Mission Control and Convex
Build the GCS image and run the Convex backend on their own.
Ports and troubleshooting
The port table and the common failure modes.