Skip to main content
One Docker Compose file at 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 is selfhost, 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 deploy and npx convex env set also target it.
  • The site origin (:3211) serves HTTP actions. The drone agent heartbeat and pairing, and mqtt-auth-sync (CONVEX_URL), talk to it.
Cross the two and the GCS loads but no drone ever appears, or sign-in works while commands never reach the agent.

Environment

Copy the example file and edit it before bringing anything up.
string
A short instance name for the self-hosted backend, for example ados-selfhost.
string
required
A long random secret for the backend. Generate one with openssl rand -hex 32.
string
The client API origin the backend advertises, for example http://192.168.1.50:3210. Use your LAN IP or hostname.
string
The site (HTTP actions) origin the backend advertises, for example http://192.168.1.50:3211.
string
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.
string
The site origin (:3211). mqtt-auth-sync fetches broker credentials from it.
string
default:"ados"
The broker service principal.
string
required
The password for that principal. You also write it into the broker password file in the setup steps below.
string
required
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.
string
default:"rtsp://host.docker.internal:8554/{deviceId}"
The RTSP source the video relay pulls from. {deviceId} is replaced with the drone’s device ID.
string
required
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.
NEXT_PUBLIC_CONVEX_URL and CONVEX_URL are different values. The first is the :3210 client API for the browser; the second is the :3211 site origin. Swapping them is the most common setup mistake.

Setup

The backend needs its functions and auth keys before the rest of the stack is useful, so the order matters. Run every command from tools/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:
On a self-hosted backend every Convex CLI call needs your own --url and --admin-key. Without them the functions land on another deployment and sign-in fails with no visible error.
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

Compose builds the GCS, auth-sync and relay images on first run, then starts every service.

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:
Without these the GCS uses the managed broker and relay, which do not know your devices.

Point the agent at the stack

Set the drone’s server.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 ~/.cloudflared/config.yml. Each hostname maps to one published port:
Add a DNS route for each hostname with 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/version returns a version, so the backend answers on the client API origin.
  • docker compose logs mqtt-auth-sync shows no sync failed; retrying lines, so MQTT_AUTH_RELAY_SECRET matches on both sides.
  • docker compose logs video-relay shows Video relay listening on port 3001, so VIDEO_RELAY_SECRET is 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 :3211 site origin.
Over plain HTTP the GCS stays local and talks to drones on the LAN. Serve it behind TLS to use the cloud relay. Functions are pushed with 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.
Last modified on November 19, 2026