Docker DMR bridge: HTTP control never starts; CAD sends token hash not plaintext

[kmk1971]

Summary

The Docker DMR bridge (services/dvswitch/docker) cannot work as shipped. Two
defects block it completely; three smaller ones affect the UI. With workarounds
applied I have the bridge fully working — HBP login, AMBE vocoder, live receive
and browser push-to-talk — so everything below is reproducible on a real setup.

Reported after building this from scratch against a private HBLink3 master.

Environment

• TicketsCAD v4.1.2 (272513b), Docker Compose build pack under Coolify, Ubuntu 24.04
• Bridge from services/dvswitch/docker, same host as the CAD, attached to the CAD's Docker network
• Master: HBLink3 (HBLink-org/hblink3) on Debian 12, single MASTER-1, REPEAT: True, UDP 54000
• Second peer for audio testing: DroidStar with ESSID 01

---

1. BLOCKER — the HTTP control server can never start on Docker

services/dvswitch/hbp_client.py:1468

if bearer and piper_bin and piper_voice:
    worker = threading.Thread(target=client.run, name="hbp-loop", daemon=True)
    worker.start()
    http_server = serve_http(...)

piper_bin / piper_voice come from DMR_PIPER_BIN / DMR_PIPER_VOICE, which
default to "". Those two variables appear only in
services/dvswitch/hbp-client.env.example (the bare-metal file). They are in
none of:

• services/dvswitch/docker/.env.example
• services/dvswitch/docker/docker-compose.yml
• services/dvswitch/docker/Dockerfile
• services/dvswitch/docker/entrypoint.sh

So on the Docker path the condition is always false, serve_http() never runs,
and port 18091 never opens. Execution falls through to client.run() inline, so
the DMR side works perfectly and nothing indicates a problem.

This fails silently. The entrypoint still prints starting hbp_client.py (HTTP control on 18091) and the HBP side logs a clean login, so the bridge looks
healthy. Symptoms are only visible from the CAD side:

• Channel never connects
• curl to 18091 from the host: curl: (56) Recv failure: Connection reset by peer
  (docker-proxy accepts the TCP connection, then finds nothing listening)

Workaround — compose override, no rebuild needed:

services:
  dmr-bridge:
    environment:
      DMR_PIPER_BIN: /usr/bin/true
      DMR_PIPER_VOICE: /dev/null

After this: INFO [hbp] HTTP control listening on :18091.

Suggested fix: decouple the HTTP surface from TTS. /health,
/audio-stream, /tx/audio and /tx/stream don't need Piper — only /tx/text
does. Gate on if bearer: and have /tx/text return a clear 503 ("TTS not
configured") when piper_bin/piper_voice are empty, rather than taking the
entire control surface down with it.

Related: Piper isn't installed in the Docker image at all, so /tx/text
can't work on Docker even with the gate fixed. Either ship it, or document Docker
as RX + raw-audio-TX only.

---

2. BLOCKER — the CAD sends the token hash to the bridge; every server-side call is 401

api/dvswitch.php:284-285 mints the bearer and stores it hashed:

$token = bin2hex(random_bytes(32));
$hash  = hash('sha256', $token);   // $hash is what goes into bridge_token

The plaintext is returned once and never persisted. But every server-side caller
reads that same column and uses it directly as the Authorization: Bearer value:

• api/dmr-tx-audio.php:77
• api/dmr-stream.php:87
• proxy/dmr-proxy.php:131
• inc/channel_registry.php:450-456
• inc/weather_radio.php:49, 219

They send the SHA-256 hash; the bridge compares against the plaintext
DMR_BEARER_TOKEN and returns 401.

Symptoms. Push-to-talk:

Transmit failed (HTTP 401): {"error":"bridge tx-audio failed",
 "detail":"{\"error\": \"unauthorized\"}","http_code":401}

And live audio never plays, because /audio-stream 401s on a retry loop:

INFO [hbp] HTTP "GET /audio-stream HTTP/1.1" 401 -
INFO [hbp] HTTP "GET /audio-stream HTTP/1.1" 401 -
...every ~3 seconds

Only channel_test_health works, because dvs_bridge_call() uses
$ch['_token_plain'] — a value the operator pastes into the Test dialog by
hand. Nothing that runs unattended can ever authenticate.

Workaround — store the plaintext. api/dmr-ingest.php:130 already accepts
either form:

$ok = hash_equals($stored, $incoming) || hash_equals($stored, $incomingHash);

so ingest still authenticates correctly:

UPDATE dmr_channels SET bridge_token = '<plaintext token>' WHERE label = '<label>';

Immediately after this, /audio-stream returns 200 and PTT works:

INFO [hbp] HTTP "GET /audio-stream HTTP/1.1" 200 -
INFO [hbp] audio-stream subscriber 1f45a76f connected (subs=1)

Suggested fix: a background daemon cannot derive a bearer from a hash, so
hashing at rest can't work here. Encrypting it with the existing app_keys field
encryption (already used for 2FA secrets and encrypted fields) and decrypting in
dvs_bridge_call() would keep it out of the DB in the clear while remaining
usable.

Note also that rotating the token or recreating the channel writes a fresh hash,
putting the deployment straight back to 401.

---

3. "TX 0.5s 1 kHz tone" posts to an endpoint that doesn't exist

api/dvswitch.php:439 (channel_test_tx):

$resp = dvs_bridge_call($ch, '/tx/test', 'POST', [...]);

hbp_client.py implements /tx/audio (1036), /tx/stream (1040),
/transcript (1045) and /tx/text (1353). There is no /tx/test; the request
falls through to the 404 at line 1386.

{ "ok": false, "status": 404, "body": { "error": "not found" } }

Presumably not Docker-specific. Worth having — it would be the fastest way to
verify the TX audio path.

---

4. "Recent transcripts" likewise

channel_recent_calls calls GET /calls/recent. The bridge's do_GET handles
only /health, /audio-stream and /recording* before its 404 at line 900.

---

5. Radio widget hardcodes TG 3127

inc/navbar.php:954 and :989 print TG 3127 and Listening for TG 3127…
regardless of the channel's configured talkgroup (mine is TG 10). Also referenced
in assets/js/radio-widget.js:5 and inc/radio_ai_client.php:170. Cosmetic.

---

What works, with workarounds applied

Vocoder self-test:

[entrypoint] md380-emu is answering on UDP 2470
INFO [hbp.ambe] round-trip PCM peak amplitude = 43 (should be >> 0)
OK — md380-emu codec round-trip succeeds

HBP login, bridge side:

INFO [hbp] bound local UDP 62032
INFO [hbp] sent RPTL for DMR ID 4300098
INFO [hbp] HTTP control listening on :18091
INFO [hbp] sent RPTK (auth hash)
INFO [hbp] sent RPTC config (302 bytes)
INFO [hbp] RUNNING — authenticated to <master>:54000 as DMR ID 4300098

Same login, HBLink3 side:

(MASTER-1) Repeater Logging in with Radio ID: 4300098
(MASTER-1) Peer 4300098 has completed the login exchange successfully
(MASTER-1) Peer b'A61KT   ' (4300098) has sent repeater configuration

Live receive — DroidStar as a second peer (ESSID 01 → 430009801), keyed on TG 10:

{"ok": true, "state": 4, "running": true, "rx_dmrd": 445, "rx_keepalive": 498}

445 DMRD frames, ~9 seconds of speech, decoded through md380-emu.

Transmit — browser push-to-talk:

DMRD seq=62 TS2 voice      dtype=1 src=4300098→tg=10 rpt=4300098 stream=4a94e82a
DMRD seq=67 TS2 voice_sync dtype=0 src=4300098→tg=10 rpt=4300098 stream=4a94e82a

voice_sync every sixth frame with dtype=1..5 between — a correct A–F
superframe.

---

Smaller notes

The voice compose profile isn't needed for either direction.
api/dmr-stream.php (SSE) and api/dmr-tx-audio.php both call the bridge
directly from the app container. dmr-proxy only backs the optional /dmr-ws
WebSocket PTT path; when it isn't running the widget correctly falls back:

[radio] WS TX setup failed; falling back to batched
[radio] tx-audio OK {accepted: true, pcm_bytes: 45120, duration_ms: 2820}

Worth documenting, since docs/RADIO-DMR-DOCKER.md implies the profile is needed
for browser PTT.

The DMR settings page still describes the bare-metal path. "Bring up a new
bridge host" in settings.php documents a Debian 13 VM at 10.0.0.10,
analog-bridge/mmdvm-bridge packages, /etc/ticketscad/dvswitch-<instance>.env
and systemctl enable --now ticketscad-dvswitch@<instance>. The bearer-token
panel shown after channel creation says the same. For a Dockerised CAD this is a
dead end, and it's the first thing a new user reads. The Bridge host field
also pre-fills 10.0.0.10.

HBLink3 startup timing, for anyone else testing: it parses the radioid.net
alias files before reactor.listenUDP, so the master takes 30–45 seconds to
start listening. Checking too early looks like a failure.

---

I have a working HBLink3 master and a clean Coolify CAD
I've also written up the full
deployment as a guide for other Docker users if that would be useful.

— Khalaf Almazrouei

[kmk1971]

Hope this helps. Below is the full guide from my own deployment — this is what actually worked for me, start to finish, including the workarounds for the two blockers above. Written for other Docker users so they don't lose the same hours.`

TicketsCAD v4 + DMR/DVSwitch bridge on Docker — a working deployment guide

By Khalaf Almazrouei

Status: tested end-to-end on 2026-07-27 against TicketsCAD v4.1.2, a private HBLink3 master, and DroidStar as a second peer. Two-way voice confirmed.

This is the Docker path. The official DMR docs assume bare metal with systemd (/etc/ticketscad/dvswitch-<instance>.env, systemctl restart ticketscad-dvswitch@…) — none of that applies if your CAD runs in Docker, Coolify, Portainer or similar.

It also documents five defects found along the way, two of which make the Docker bridge non-functional as shipped, with the workaround for each. If you're reading this after those are fixed upstream, skip to the version note at the end.

---

1. How the pieces actually fit

   Radio / hotspot / DroidStar ─┐
                                ├─ UDP 54000 ─►  HBLink3 MASTER-1
   TicketsCAD DMR bridge ───────┘                 REPEAT: True
                                                  (repeats between its peers)
The bridge = ONE container running TWO programs:

hbp_client.py   HomeBrew Protocol out to the master (outbound UDP)

+ HTTP control surface on :18091 for the CAD

md380-emu       AMBE+2 vocoder on UDP 2470, localhost only

(they share a network namespace — hence one container)
CAD container ──HTTP :18091 + bearer token──► bridge container

Four things that explain most failures:

• The vocoder is the whole game. md380-emu is MD-380 radio firmware under qemu emulation. Without it you get a bridge that connects perfectly and passes silence.
• Port 18091 is protected by a bearer token over plain HTTP. No TLS. Run the bridge on the same host as the CAD and put both on the same Docker network, so the port never leaves the machine.
• A master with one peer is a closed loop. The bridge will log in and the codec will pass its self-test, but nothing is audible until a second peer connects.
• The bridge is its own compose project. It is deliberately separate from the CAD so it survives CAD redeploys. That also means your orchestrator doesn't manage it.

---

2. Prerequisites

• A Docker host for the CAD (this guide uses Coolify, but plain docker compose works identically).
• A second host for the HBLink3 master, or the same host if you prefer.
• Your DMR ID and callsign from radioid.net. You are the control operator for everything the bridge transmits.
• A hostname with DNS pointing at the CAD host, if you want HTTPS.

Placeholders used throughout — substitute your own:

Placeholder	Meaning
	IP/hostname of the Docker host running TicketsCAD
	IP/hostname of the HBLink3 server
cad.example.com	the CAD's public hostname
YOUR_DMR_ID	e.g. 1234567
YOUR_CALLSIGN	e.g. N0CALL
	the Docker network your CAD container is on

---

Version note

Written against TicketsCAD v4.1.2 and HBLink-org/hblink3 as of July 2026. The five defects in §7 were reported upstream on 2026-07-27. If your version is newer, check the changelog before applying the workarounds — particularly the plaintext-token one, which should become unnecessary once the token is encrypted at rest rather than hashed.

Licence note: DVSwitch and md380-emu are amateur-radio-only. Suitable for CERT / volunteer fire / ARES use; not for commercial dispatch. You are the control operator for everything your bridge transmits.

---

Credits

Written by Khalaf Almazrouei after building this deployment from scratch — a fresh Debian 12 host for the master, TicketsCAD on Coolify, and the bridge built and debugged until voice passed in both directions.

Thanks to Eric Osterberg for TicketsCAD and for building the Docker bridge in response to the original question, and to the HBLink3 and DVSwitch projects.

Corrections and improvements welcome — particularly from anyone who reproduces this against a different master (BrandMeister, TGIF, FreeDMR) or a newer TicketsCAD release.

`

[ejosterberg]

Thank you for this — it is one of the most useful reports this project has received. You found both defects, located them exactly, and proved them on a real HBLink3 setup rather than by reading. I have reproduced both against the current tree and you are right on both counts.

1. HTTP control never starts on Docker — confirmed.
hbp_client.py:1468 still reads if bearer and piper_bin and piper_voice:, and DMR_PIPER_BIN / DMR_PIPER_VOICE appear only in bridge.py, example.env and hbp-client.env.example — nothing under services/dvswitch/docker/ sets them. So the condition is false on every Docker deployment and the control surface never opens.

Your suggested fix is the right one and is what we are implementing: gate on if bearer: alone, and have /tx/text return 503 when Piper is not configured, instead of taking /health, /audio-stream, /tx/audio and /tx/stream down with it. The entrypoint printing "HTTP control on 18091" while nothing listens is its own bug — a component that announces success it has not achieved. That is getting fixed too.

2. The CAD sends the token hash — confirmed, and the reasoning behind it was simply wrong.
api/dvswitch.php:285 hashes the token before storing, and api/dmr-tx-audio.php:77, api/dmr-stream.php:87 and the other callers you listed read that stored column and send it as the Bearer. So every unattended call presents a SHA-256 digest to a bridge comparing against the plaintext, and 401s.

The root cause is a category error worth naming, because it is the kind of thing that gets "fixed" in the wrong direction: hashing at rest is correct for a credential you verify, and wrong for one you present. Here the CAD is a client that must produce the token on every call, so it needs the value, not a digest of it. Hashing both sides would look like a security improvement and would break it differently.

Your observation that only channel_test_health works — because an operator pastes the plaintext into the Test dialog by hand — is the detail that makes this unarguable. The one path a human drives works; nothing automated can authenticate. That is exactly the shape of failure that hides for months.

Also noted: Piper is not in the Docker image, and /tx/test and /calls/recent do not exist. We will either ship Piper or document Docker as receive plus raw-audio transmit only, rather than leaving the gap implied.

On your offer of a deployment guide — yes, please. A working HBLink3 + Docker walkthrough from someone who has actually stood it up is worth more than anything we would write from the inside, and we would be glad to include it in the repository with credit to you. Open a pull request whenever suits you, or send it however is easiest and we will handle the formatting.

Apologies for the two-day wait on a report of this quality. Fixes are in progress now and I will comment here when they land, so you can check them against your setup before we close this.

[ejosterberg]

Both blockers and the two missing endpoints are fixed in b2944e0 (dev repo; it reaches the public tree with the next release snapshot). Everything below was re-verified against the current tree first — your file:line citations were all still accurate.

1. HTTP control surface on Docker

hbp_client.py now gates on if bearer: alone, exactly as you suggested. /health, /audio-stream, /tx/audio and /tx/stream never had any use for speech synthesis, and taking all four down with it is what made this invisible.

/tx/text answers 503 {"error": "tts_not_configured", "detail": "…"} naming DMR_PIPER_BIN and DMR_PIPER_VOICE, rather than failing somewhere deeper.

The entrypoint no longer prints "starting hbp_client.py (HTTP control on 18091)" regardless. It now reports what will actually happen — whether the bearer token is set, whether text-to-speech is configured — and the proof of a bind stays where it belongs, in the client's own HTTP control listening on :18091. A component announcing success it has not achieved is its own defect and cost you time here.

Your compose override is no longer needed. If you want to confirm the old behaviour is gone, the log line to watch for is that HTTP control listening on :18091 with DMR_PIPER_BIN unset.

On Piper in the image: it still is not there, and that is now documented rather than implied. The reasoning: voice models are 50–110 MB each, specific to one language and one voice, and separately licensed per voice. Baking one in picks a voice for every operator and grows the image for the majority who use the browser push-to-talk path, which does not touch Piper at all. So the image ships receive + raw-audio transmit, and /tx/text is opt-in: DMR_PIPER_BIN / DMR_PIPER_VOICE are now passed through by docker-compose.yml, documented in .env.example, and there is a commented volume mount showing the two-line change. docs/RADIO-DMR-DOCKER.md has a "Text-to-speech (/tx/text)" section, and the 503 message and the docs say the same thing.

If you think that trade is wrong for real deployments, say so — you are the one who has actually stood this up.

2. The token hash

Fixed, and not by hashing on the bridge side. Your framing was right: the CAD is a client here and has to produce the value on every call, so a digest can never work. The convention was copied from api/mesh.php, where the server verifies an incoming token and hashing is correct — the mistake was applying a verify-side pattern to a present-side credential.

The token is now stored in the form the callers need — plaintext, deliberately, and stated as such in the code and the commit rather than dressed up. It is the same shape as every other outbound credential in the codebase (smtp_pass, slack_token, sms_twilio_token, zello_password), it fits the existing CHAR(64) column, and encrypting it would put the key on the same filesystem as config.php, which already holds the database credentials that got an attacker to the row. What does the actual work instead: the value is never returned by a GET (?action=channels reports a has_token boolean; ?action=channel does not select the column), it is returned exactly once from the POST that mints it, and there is now a single writer and a single reader (inc/dmr_token.php) so the two cannot drift apart again. Every one of the five call sites you listed goes through that reader — as do three you did not reach, which had the identical bug: api/dmr-tx-stream.php, api/dmr-audio.php and api/radio-ai-decide.php.

Two things you flagged in passing are also handled: rotating or recreating a channel no longer puts the deployment back to 401, and the Test dialog's token box is now optional. Leave it empty and the probe uses the channel's stored bearer — the same value sent on every unattended call, so a green /health now actually means live audio and push-to-talk will authenticate. That was the specific thing wrong with it before: the one path a human drove was the one path that could not tell you anything about the others.

What an existing install must do

Any bridge token already in the database is a SHA-256 digest and is unrecoverable. A digest and a freshly minted token are both 64 hex characters, so they cannot be told apart by inspection — the migration records which era a value came from rather than guessing.

php sql/run_migrations.php adds dmr_channels.bridge_token_format, classifies every existing non-empty token as legacy_hash (true by construction — it was written by the hashing code), and prints the affected channels by name. Those channels are flagged token unusable in Settings → Communications → DMR, are refused rather than sent, and the error names the repair instead of leaving a bare 401. The migration is idempotent and never re-flags a repaired channel.

Two ways to repair, both leaving the channel working:

1. You still have the token you copied at mint time — paste it into that channel's Test dialog and click Test /health. A 200 is the bridge itself confirming the value is the one it accepts, so TicketsCAD stores it. No bridge change, no restart.
2. You don't — rotate the token and put the new value in the bridge's DMR_BEARER_TOKEN (Docker: services/dvswitch/docker/.env, then docker compose up -d).

Your own deployment used the UPDATE dmr_channels SET bridge_token = '<plaintext>' workaround, so it will be flagged legacy_hash by the migration even though the stored value is in fact correct and working — the migration cannot tell. Route 1 clears it in a few seconds: open Test, paste the same token, /health returns 200, badge gone. Nothing you have to change on the bridge.

3 and 4 — /tx/test and /calls/recent

/tx/test is implemented in hbp_client.py. You were right that it is worth having: it is the fastest way to prove the transmit path without involving Piper or the browser. It generates a 1 kHz tone and runs it through the same AMBE + DMR framing path as /tx/audio, synchronously, capped at 5 s, and returns the packet count. (services/dvswitch/bridge.py — the older USRP bridge — always had it; the native HBP client never did, which is why the button 404'd wherever anyone actually pointed it.)

/calls/recent is removed from the CAD side rather than implemented. hbp_client.py keeps no call ring buffer, and channel_recent_messages already serves that panel from persisted dmr_messages rows — which works while the bridge is offline and needs no bearer. Nothing in the UI called the proxied version. The documented surface now matches what exists.

Tests

Two new files, 52 assertions, both green in CI on a fresh install:

• tests/test_dmr_bridge_token.php (32) drives the real writer and the real reader against a row that goes through MySQL in between, covers rotation, the legacy-hash classification and the adopt-on-verified-probe repair, and gates the source so the hashing pattern cannot come back in a ninth caller.
• tests/test_dmr_bridge_http.php (20) stands the real ControlHandler up on an ephemeral loopback port with no Piper configured and drives it over HTTP from PHP: the surface comes up without text-to-speech, /tx/text is the only thing affected, /tx/test is routed, an unknown path still 404s, and the bearer the CAD's reader hands back authenticates against the bridge's actual _auth_ok(). Nothing in either test can key a radio.

Please check it before we close this

What has not been done is the thing only you can do: none of this has been exercised against a real HBLink3 master or a real docker compose up -d --build. The tests prove the handler and the token path in isolation; they cannot prove HBP login, the vocoder, or two-way voice on your setup.

So — when convenient, would you pull and re-run your walkthrough? Specifically:

1. docker compose up -d --build without the DMR_PIPER_BIN / DMR_PIPER_VOICE override, and confirm HTTP control listening on :18091.
2. Clear the token unusable badge via the Test dialog (route 1 above), then confirm /audio-stream returns 200 and push-to-talk works without the manual UPDATE.
3. The TX 0.5s 1 kHz tone button, which should now key rather than 404.

I will leave this open until you have. Thank you again — this was an unusually precise report, and it found a defect that had been silently breaking every unattended call on every install.