Skip to content

Install the appliance

The repository installer is the authoritative recovery and deployment path. It validates the selected profile, builds native and browser components, runs tests, installs static assets, and updates systemd units. It never imports host secrets from Git.

Synthetic example; explicit customization

example provides a Pi 5 hardware template with reserved network identity. Customize serials, topology, RF routes and policy in a private copy. See profile and identity setup.

Inspect first

Start by checking the synthetic profile in your checkout. Its USB topology, serials and RF paths will need to match your own wiring before installation.

cd ~/rfsentry
git status --short
./install.sh --check --profile example

Review the profile and live host configuration before replacing an existing appliance. The live /etc/rtl_tcp/*.conf, /etc/rfsentry/routes.d/*.conf, /etc/rfsentry/appliance.conf and unrelated api.conf policy are authoritative when they differ from an old document. Compare the selected profile to installed inventory, routes and health/USB policy. Upgrades preserve the installed files; fresh installs require a reviewed private profile. --check installs no appliance files, but enables the checkout's Git hooks.

The check uses the gateway’s inventory, route and spur validators. It can compile them with gcc alone, or use a built or installed gateway. Correct an invalid route before installing. If neither compiler nor validator is available, --check reports incomplete coverage and exits with status 2. The full installer checks again with the built gateway before stopping services.

Network access on first installation

Place the appliance on a trusted local network. The example below uses the default gateway ports and the first receiver in the synthetic profile. Verify your actual port assignments and restrict access from untrusted networks.

Listener Example Who can connect and what controls access
Web UI and control TCP 8443 The gateway defaults to all IPv4 interfaces. HTTPS protects transport. Browser authentication defaults to disabled; configure account policy for shared networks. Machine credentials have separate grants.
Browser IQ stream TCP 8444 On the gateway listener address. A browser needs an allowed origin and the per-session IQ token obtained through control.
Raw RTL-TCP demand port TCP 1234 for the first receiver Listens on all IPv4 interfaces. A reachable RTL-TCP client can request the receiver. Restrict these ports to intended LAN clients with network/firewall policy; web authentication does not govern them.
Private RTL-TCP backend TCP 11234 for that receiver Loopback only (BIND=127.0.0.1). The demand manager owns this connection and starts the backend on demand.

See appliance identity and browser accounts for the configured UI and streaming origins.

Build and install

For a new device, first prepare a private profile following hardware profiles and upgrades, then copy/edit the profile's .example into ignored config/local/appliance.conf; see Appliance identity and TLS.

cd ~/rfsentry
./install.sh --check --profile-dir config/local/hardware-profile \
  --appliance-config config/local/appliance.conf
sudo ./install.sh --install --profile-dir config/local/hardware-profile \
  --appliance-config config/local/appliance.conf

For an upgrade using the existing installed identity:

sudo ./install.sh --install

No .example identity is automatically consumed. The explicit identity wins over the installed file; without it, installed identity wins over a deliberate profile seed. A fresh install without any selected identity fails rather than guessing. Normal upgrades preserve installed hardware/health settings, explicit API policy and existing QoS choices. They still update software, service units and managed integration files; see the preservation contract.

The installer checks required documentation sources and detectable operator-home destination errors before packages or service interruption. It stages convenience Markdown links against the complete built local site before stopping services. Filesystem races, later I/O faults and full live upgrade behavior still require normal operational safeguards; fixture tests are not a universal safety proof.

Choose a maintenance window before starting a full installation. The installer warns if it finds active SDR clients and proceeds even if they are still connected.

  1. While the existing services are running, the installer prepares dependencies, builds and checks the browser assets and local manual as needed, then tests the gateway and validates the selected configuration with the staged binary.
  2. It checks for active clients again, then stops the gateway, decoder and demand service. It installs the new binaries, static files and service units while acquisition is interrupted.
  3. On normal startup the demand service starts first, followed by the decoder and gateway. Enabled continuous jobs resume and disabled jobs stay disabled. Reconnect interactive clients and check jobs with sudo rfsentry-jobctl list.

This is not a live hot-deploy. --no-start suppresses final startup but still writes/enables files and can stop existing services; it is not a dry run or an acquisition-safe workaround. --no-web-toolchain requires a complete matching prebuilt dist, including documentation. See the build/install boundaries.

The docs are static output. MkDocs is a build dependency, not a service on the appliance. At runtime the existing rfsentry-api process serves both the application and /docs/.

Installed paths

Purpose Path
Gateway /usr/local/sbin/rfsentry-api
Gateway policy /etc/rfsentry/api.conf
Public identity / TLS policy /etc/rfsentry/appliance.conf
Receiver inventory /etc/rtl_tcp/*.conf
Route policies /etc/rfsentry/routes.d/*.conf
Detector exclusions /etc/rfsentry/spurs.d/*.conf
Static app and docs /usr/local/share/rfsentry-web/
TLS private key /etc/rfsentry/tls/server.key
Operator/job credential; optional browser authentication /etc/rfsentry/auth.token

The TLS key and token are host-only state. Never copy their content into a repository, issue, build log, or documentation page.

Verify

systemctl status rfsentry-api.service
rfsentry-config show
sudo rfsentry-qos status

Open /healthz and /docs/ on the canonical configured HTTPS origin, using the configured API port and normal certificate validation. In the preferred off-grid private-ca mode, open the appliance's responsive /trust/ page and install its public root once on each client. Verify the displayed SHA-256 value against sudo rfsentry-config trust; do not bypass validation or assume loopback is an authorized certificate name. UI/API/control uses the API listener (8443 default), while the client discovers the dedicated WSS IQ listener (8444 default). Neither number is a fixed requirement.

Open the canonical configured origin in a browser. Alternate fixed-IP and DNS origins may work, but browser storage is origin-scoped; use one canonical origin for durable FCC/FAA/product/archive state.

Offline behavior

The built docs contain the Material theme, search index, Mermaid renderer, icons, CSS, and JavaScript. They do not require a CDN. Basemap tiles or dataset updates may have their own separately documented network behavior, but opening and searching this documentation does not.