DockTalk Nodes: Setup & Architecture

FOR HOSTS · PLAIN ENGLISH

What you're actually plugging in

The hardware: about $165 all-in

A Raspberry Pi, a credit-card-size computer (~$53)
An RTL-SDR receiver dongle, the actual radio (~$51)
A marine VHF antenna with cable and adapters, by a window or on the roof, facing the water

All off-the-shelf, no soldering, no tools. The exact shopping list with links is on the home page. Already own a Pi or an old Linux laptop? Then you only need the dongle and antenna, about $112. And if your spot is truly prime (waterfront, marina, liveaboard), apply: we cover the whole kit for locations like that.

Setup is one pasted command

We approve your site and text you a one-time claim code.
You paste one command on the Pi. It installs everything itself in about 5 minutes: the radio software arrives as a prebuilt, versioned package, and keeps itself updated daily from then on.
The screen prints VERIFIED when DockTalk hears your receiver. From that moment your harbor is live in the app, credited to you.

Kit in hand? Follow the step-by-step setup guide — every click, nothing assumed, about 30 minutes.

What it costs to run

Power: about as much as a nightlight. A few dollars a year.
Internet: it uploads steadily but modestly, roughly 5 GB a day, about what one Netflix hour downloads. Fine on home broadband; worth knowing only if you have a data cap.
Your time: none after setup. It runs itself, recovers from power cuts on its own, and updates when you re-run the install command (we'll tell you if that's ever needed).

What it does, and never does, on your network

It only sends radio audio out. Marine VHF is public airwaves; there's nothing private in it.
Nobody can connect into it. Not DockTalk, not anyone. It opens no doors on your router, joins no VPN, and can't see other devices in your home.
Unplug it whenever you want. That's the entire off switch. Plug it back in and it resumes on its own.

What you get

Your harbor, live in the app, credited to you by name or a handle you pick.
A spot on the public leaderboard, with rank titles earned by time on watch: Deckhand the day you plug in, Commodore after a year. Early nodes keep their low commission number forever, and the first ten carry the Founding Crew badge.
Bragging rights: when a rescue from your antenna makes the feed, that was your node.

If something goes wrong

Unplug it, plug it back in. Still down? Re-run the install command, it's always safe to run again. Still stuck? Email hello@docktalk.app with your node name and we'll sort it together. You never owe us debugging time.

Want in? Apply to host a node. Takes two minutes.

FOR ENGINEERS

Architecture

Push-only. Nodes hold one secret (their own push token), accept no inbound connections, and stream outbound over HTTPS. The server cannot reach a node at all. A node is "online" exactly while its audio is arriving.

ON THE NODE (Raspberry Pi OS Lite · Debian + systemd)

RTL-SDR dongleone 2.4 MS/s window covers the port's whole VHF plan

↓

RTLSDR-Airbanddemodulates all channels in parallel (NFM), one MP3 stream each

↓

Icecast (bound to 127.0.0.1 only)local buffer between demodulator and push agent, unreachable even from the host's LAN

↓

Push agent (docktalk-push.service)one curl pipe per mount: local GET, then chunked PUT to the API with Bearer token + version header

↓ HTTPS (TLS) · outbound 443 only · ~32 kbps per channel

ON THE SERVER (single Go binary, Fly.io)

PUT /v1/push/{mount}authenticates the per-node token, validates the mount belongs to that node's port

↓

In-process relay (loopback-only)re-serves each pushed stream to the ingest exactly like any Icecast mount

↓

Pipelinesquelch-split clips → ASR → LLM curation → the app's feed, map, and live listening

Security model

Direction of trust: nodes push; no inbound path exists. No VPN, no mesh, no open ports. A compromised server learns nothing about a host's network beyond its public IP.
Auth: each node gets its own 256-bit bearer token, minted server-side when its one-use claim code is redeemed (codes are bound to the first machine that redeems them). Tokens are individually revocable. Nodes never hold shared or global credentials.
Blast radius: a stolen token lets you stream audio into that one port's channels, nothing else. Mounts are validated against the node's own channel plan.
Local exposure: the on-node Icecast binds to loopback; the token file is root-only (0600).

Supply chain & versioning

Nodes run a versioned, multi-arch Docker image (ghcr.io/michaelxavierd/docktalk-node) built by CI from sources pinned to exact upstream commits (rtlsdrblog/rtl-sdr-blog @ aed0ea1, szpajder/RTLSDR-Airband @ 8e45496). A release tag is the only thing that moves the fleet forward; v3.0.0 is the same bytes on every Pi, forever.
Nodes self-update daily against the stable tag, and report their version with every push (X-DockTalk-Version); the fleet's versions are visible on the public node API.
The installer is idempotent, and a source-build path (no Docker) remains available for unusual hardware.

The one-liner

# claim code is single-use and bound to your machine at first redeem
curl -fsSL https://docktalk.app/install | sudo bash -s -- --claim DT-XXXX-XXXX --docker

It refuses to run on non-Debian/non-systemd machines before burning the claim code, generates the port's channel plan server-side from the live catalog, proves Icecast answers before proceeding, and ends by verifying end-to-end that audio is arriving (VERIFIED), or tells you exactly which service to look at.

API surface a node touches

Endpoint	Purpose
`GET /install`	the installer script (public; the claim code is the secret)
`POST /v1/nodes/claim`	redeem claim code → node identity + push token
`GET /v1/nodes/conf`	generated RTLSDR-Airband config for the port's channel plan
`PUT /v1/push/{mount}`	the audio push (Bearer token; one long-lived request per channel)
`GET /v1/nodes`	public roster: online state, channels live, agent version

Budget numbers

Resource	16-channel node
Power	~4 to 6 W (Pi 4), ~2 W (Pi Zero 2 W with a trimmed plan)
Upload	~32 kbps/channel → ~5 GB/day at 16 channels (continuous stream, silence included)
CPU	comfortable on a Pi 4; a Pi 3 or Zero 2 W prefers a smaller channel plan

Roadmap, honestly

Done: push-only architecture, per-node tokens, pinned builds, version phone-home, loopback-locked Icecast, handles on the leaderboard, versioned Docker image with daily self-updates.
Planned: mTLS client certificates (per-node certs at claim time), and squelch-gated pushing (upload only when someone's talking, which makes cellular and solar nodes cheap to run).

Found a hole? We want to hear it. The current architecture exists because a node host pushed back on the previous one. hello@docktalk.app