Build, test, and deploy¶
rfSentry pins its Node toolchain and identifies decoder modules by content hash. Use repository scripts rather than an arbitrary system Node or ad-hoc WASM flags.
The optional rfSentry Server builds independently through
components/rfsentry-server/tools/build.sh. Its React/TypeScript frontend runs
type checking, DOM tests and a static production build before C++ packaging.
Only compiled local assets are installed; no JavaScript server or Node runtime
is required. Server C++ tests include the shared canonical record codec, SQLite
archive/recovery and real isolated verified-TLS enrollment/ingestion. Installed
Debian 13 amd64/arm64 qualification uses the installed gates described under
coordinated CI and artifact promotion.
See the Server build instructions
and archive contract for the
service's dependencies and durability guarantees.
Contributor checks and toolchain ownership¶
Use Conventional Commits with a subject no longer than 50 characters and body lines wrapped at 72. Activate the version-controlled hooks for an existing checkout and run the secret scan before every commit:
The commit hooks enforce staged secret/example checks and message format; the push hook
checks the outgoing commit range. Correct failures instead of bypassing hooks
with --no-verify. The project umbrella is rfsentry; component names use
rfsentry-*, while existing installed command/service names remain stable.
scripts/node-toolchain.sh selects the checksum-pinned release under
/opt/rfsentry/toolchains and changes PATH only for its launched command.
Do not replace Debian's /usr/bin/node: it remains part of the packaged
Emscripten dependency graph. Content-addressed decoder artifacts and their
explicit WASM export allowlists remain separate correctness checks.
The record-core build uses its separately pinned Emscripten 4.0.23 to compile
both genuine MEMORY64=1 and compatible MEMORY64=2 from the same C++ sources.
Web packaging must retain both hashed artifacts and their descriptor; copying
only the preferred native artifact leaves compatible browsers unable to start.
The existing core reconstruction check runs each backend sequentially and
exchanges checkpoints. This does not upgrade the SDK or add a MEMORY64=0 ABI.
A first contributor check¶
From a checkout with the pinned Node toolchain available, run this small waterfall geometry test. It uses generated arrays and needs no gateway, USB device, credentials or running browser:
./scripts/node-toolchain.sh run npm ci --prefix components/rfsentry-web --no-audit --no-fund
./scripts/node-toolchain.sh run npm test --prefix components/rfsentry-web -- test/waterfallModel.test.ts
For interactive UI work use make web after installing those dependencies.
For a contribution, describe the change in an issue and link a fork commit
or patch with its test result. The maintainer reviews and signs changes to
main. Security reports use the private channel.
Phase gates and documentation ownership¶
The topic documents under docs/roadmap/ own requirements and acceptance;
docs/WEBSDR.md provides navigation. Neither overrides installed settings. Planned work uses - [ ] Item;
completed, validated and operator-accepted work uses - [x] ~~Item~~.
Writing code or passing local tests is insufficient to close a live/visual
acceptance gate. Preserve deferred requirements and dated evidence; update
scope explicitly rather than allowing source and roadmap to diverge silently.
Before every new delivery phase, present an overview and wait for explicit operator confirmation. Include:
- Phase goals and concrete deliverables.
- Proposed architecture and important implementation choices.
- Files, services, dependencies, and interfaces expected to change.
- Power, performance, concurrency, and licensing implications.
- Principal failure modes and rollback boundaries.
- Test and acceptance plan.
- Documentation updates expected from the phase.
Small decisions within an approved phase need not repeatedly reopen the gate, provided they preserve the approved architecture/safety boundaries. A phase is not complete until its required items and exit validation are complete. The validation chapter separates fixtures, source checks, benchmarks and operator evidence.
When architecture or operator procedures materially change, inspect and update
the repository AGENTS.md and README.md plus the matching MkDocs chapter
and relevant WEBSDR ledger. Keep AGENTS concise and normative, README an
entry point with practical operations/recovery links, and MkDocs the detailed
technical presentation. Do not copy the entire roadmap into either entry file
or describe planned mechanisms as installed behavior.
Maintain only repository instructions. Do not edit personal/global agent instructions as part of documentation housekeeping. Inspect installation, build and packaging consumers before moving sources. Keep current procedures in one chapter, plans in the relevant roadmap topic, decisions in ADRs and only purposeful substantiation in verification. Remove obsolete owner context rather than archiving it; do not append conversational or routine execution diaries. See documentation ownership.
Browser application¶
cd ~/rfsentry
./scripts/node-toolchain.sh run npm ci --no-audit --no-fund \
--prefix components/rfsentry-web
./scripts/node-toolchain.sh run npm run fixtures \
--prefix components/rfsentry-web
./scripts/node-toolchain.sh run npm run typecheck \
--prefix components/rfsentry-web
./scripts/node-toolchain.sh run npm run test:fast \
--prefix components/rfsentry-web
./scripts/node-toolchain.sh run npm run build \
--prefix components/rfsentry-web
npm run build rebuilds decoder artifacts, DSP, enrichment assets, local
basemap/celestial catalogs, the Vite application, generated decoder docs, and
the MkDocs site. The final tree is under
components/rfsentry-web/dist/; docs occupy dist/docs/.
The validation-state script fingerprints browser, decoder, detector, and built outputs. Application-only changes avoid recompiling all decoders; changes to a manifest or decoder source invalidate the decoder group so the catalog and its compiled modules are checked together.
Documentation¶
The script creates an ignored .venv-docs, installs exact build-only versions
from documentation/requirements.lock, regenerates the decoder catalog page,
and runs MkDocs in strict mode. Runtime output is static and has no Python or
Internet dependency.
Check generated decoder documentation without changing it:
Optional server foundation¶
The independent C++ rfSentry Server builds with
components/rfsentry-server/tools/build.sh and tests with its tools/test.sh.
It does not use the appliance installer or require a new WASM processing module.
The local server validation group covers native, sanitizer, security, UI and
release-manifest checks. CI uses the ownership graph below. Routine main/PR
qualification produces packages and installed-test inputs without provisioning
VMs. An ordinary package pass does not establish installed-system acceptance.
For ingestion changes affecting buffering, durability, retention, activation or
recovery, also execute the actual mounted fault sequence. ingestion.py --faults
and --case all alone do not enable it. On Linux with sudo, FUSE and mount/PID
namespaces, the local runner uses an isolated 64-MiB tmpfs/FUSE volume and the
existing binaries; it does not install packages, boot a VM or change host services:
components/rfsentry-server/tools/ingestion-mounts-local.sh \
components/rfsentry-server/build/native \
components/rfsentry-api/build/rfsentry-api-onboarding-test /var/tmp/mounts-normal.json
ASAN_OPTIONS=detect_leaks=0:abort_on_error=1 UBSAN_OPTIONS=halt_on_error=1 \
components/rfsentry-server/tools/ingestion-mounts-local.sh \
components/rfsentry-server/build/sanitize \
components/rfsentry-api/build/rfsentry-api-onboarding-test /var/tmp/mounts-sanitize.json
Build the test-only storage-fixture as in scripts/ci/server-build.sh if absent.
The separate local-index exhaustion fixture also requires mkfs.ext4
(e2fsprogs) and an owned 128-MiB loop-mounted image in the private namespace.
Run these sequentially. The local runner executes the same ingestion scenario
as the installed gate, including all six archive faults plus independent
local-index-volume exhaustion and exact recovery.
Its native-namespace pass is separate from installed-system acceptance.
Record ordinary/mounted/normal/sanitizer coverage explicitly. Missing capability
or incomplete fault evidence leaves qualification pending. Before recommending
a release tag for these changes, run the existing manual installed qualification
for both architectures at the published SHA; no release tag is needed to do so.
Coordinated CI and artifact promotion¶
The six existing Actions workflows have distinct responsibilities:
| Workflow | Owner and entry points |
|---|---|
validate.yml — Checks / Repository |
Main pushes, PR updates, weekly refresh, manual qualification and the tag's reusable qualification stage. Selects missing suites, runs baseline/appliance/generic API/WebSDR gates, calls component workflows, then records the aggregate result. |
core-foundation.yml — Checks / Core |
Reusable native/sanitizer/shared-core memory64 browser and record-protocol gates, including snapshots, receive/browser and queue/record sanitizers. |
server-package.yml — Packages / Server |
Reusable UI check/build once; native and sanitizer Debian 13 amd64/arm64 qualification and packaging. Manual Installed qualification <commit> runs and reusable installed mode consume verified bundles without compiling or publishing. |
client-release.yml — Packages / Client |
Reusable Go/browser-launcher/icon checks and six-platform unified packages, including two Debian packages. |
release.yml — Release / Project |
Tag-only execution, displayed as Release <tag>. Calls shared qualification for missing exact-main proofs, reuses qualified packages, runs missing installed architectures, then publishes. v* publishes the coordinated 10-file set; client-v* remains client-only. |
server-runner-preflight.yml — Runner / Preflight |
Manual or reusable inspection of both named private runners; selects only demonstrated build/VM capabilities. |
Repository CI calls validate.sh --ci-owned for its suites. Local
./scripts/validate.sh --full retains comprehensive behavior. API HTTP
integration still prepares real browser assets, but generic API unit tests,
record-protocol gates, full Server suites and client packages each have one CI
owner. Distinct normal/sanitizer, native/installed, architecture, TLS and actual
browser configurations remain separate gates. Unknown dependency paths and CI
infrastructure edits select the complete graph; documentation changes select
baseline checks. Weekly runs explicitly refresh the full graph.
The aggregate summary separately reports selected-check success and whether all
project/client native proofs exist. A green change-scoped run alone does not
establish full release qualification.
The existing Core job also owns the single real TLS browser record integration
case. It reuses that job's qualified reconstruction WASM and native-generated
fixtures, runs the existing scoped browser build helper, and invokes
ingestion.py --case record-browser against a build-only Server. It does not
repeat reconstruction suites. Related browser and Server runtime changes select
this owner. Failure prevents the Core bundle from being recorded; its normal
always-run evidence upload includes the browser JSON, log and screenshots.
Each successful owner uploads a 30-day ci-bundle-* artifact. Its manifest binds
repository, exact source and workflow commits, run ID/attempt, passed suites,
package versions, toolchain evidence and SHA-256 hashes. Server bundles always
include the package, gateway/record/storage fixture binaries and the exact
installed test sources. These fixtures are never installed as product files or
published as release assets. The aggregate ci-qualification-* artifact records
which artifact ID, archive digest and manifest hash proved each required suite.
A release candidate must be a commit on main's history. The resolver accepts successful main qualification or the verified successful qualification stage of a tag run for that exact commit. The latter binds the completed aggregate job, required evidence step, run attempt and workflow/source identities even while the enclosing release is still running. It never selects another commit's “latest” package or an older green run to hide a later failure. Expired/deleted native artifacts cause the tag to qualify only their missing owners; integrity mismatches, foreign runs, changed attempts, missing required gates and failed qualifications stop promotion. Runs predating this manifest format are historical evidence, not promotion donors. Packages keep the versions built from source; tagging does not rename or rebuild them.
Public Debian download names are stable: rfsentry-server_<arch>.deb and
rfsentry-client_<arch>.deb. Six portable client names cover Linux, Windows
and macOS on AMD64/ARM64. Version identity remains embedded in each
package/executable and recorded in the qualification manifest. Server packaging
reads the configured CMake build's package-version, derived from its project
version and Debian revision; an inconsistent override is rejected. Unified
client functions and all targets use the existing clientVersion source. Advance the
appropriate component version before qualification when its shipped behavior
changes. Qualification verifies the actual Debian Package/Version/Architecture
fields against the manifest and stable filename; checksums still bind the exact
bytes through installed testing and release export. Old published assets retain
their existing filenames and download links.
Push a tag to request the complete release sequence: reuse valid native proofs → run missing native suites → reuse/run installed gates → publish the same qualified packages. Project tags require all 12 native proofs; client tags require baseline and client. For example, a commit with baseline and both Server proofs runs the other nine suites and reuses the existing Server packages. No native build runs if every required proof and artifact is already valid.
Use a tag such as v0.6.20-rc.1 or client-v0.6.20-rc.1 for a release
candidate. The workflow publishes its qualified assets as a GitHub
pre-release and leaves the Latest designation available for stable releases.
A retry uploads assets to the existing release and preserves its settings.
Ordinary main pushes and qualification completions never start Release / Project. A tag directly calls the reusable qualification graph inside its own run; there is no workflow dispatch, completion-event continuation or polling loop. Main qualification, tagged release and manual installed qualification share a per-source concurrency group. The tag waits for an active qualification of that SHA, then plans from its completed evidence. It holds the source lease through installed gates and publication, so later work cannot preempt that release. Nested workflows use distinct groups to avoid waiting on their own caller. GitHub's queued concurrency keeps multiple pending requests instead of cancelling them. Different source commits remain independent; private runner slots still bound concurrent work.
Failed qualification stops the release; no automatic test retry is performed. Inspect its first failure before explicitly requesting new qualification. Later failed installed attempts cannot be hidden by older passes. Successfully completed native qualification remains valid if a later installed/publishing stage fails; that does not waive the failed installed gate.
The new behavior applies to tags containing this workflow revision. Existing tags retain their original workflow, and rerunning an old tag does not update it. Qualification reuse is exact-SHA: a later documentation-only commit cannot inherit another commit's package identity. Include candidate documentation before tagging.
To qualify an exact main candidate manually, use Checks / Repository, set
source_sha, leave full_validation=true, and set release_candidate=true.
refresh=true explicitly discards reuse; use it only when requalification is
intended. Once all required native suites pass, Packages / Server accepts a
main dispatch with source_sha for publication-disabled installed qualification.
Both installed architectures must pass, and the unchanged packages, checksums and
donor identities are retained as installed-qualified-packages-*. Its controller
uses the executing workflow revision while packages and fixtures remain bound to
the selected exact main commit. It has read-only repository permissions and no
release publisher. For example:
The manual installed run still requires completed native qualification and has no
publisher. Tagged releases retain their promoted-packages-* evidence
and verify the original tag event again before publication.
The two private agents have unique labels: lar-ghr-1 / rfsentry-slot-1 and lar-ghr-2 / rfsentry-slot-2. Preflight checks each agent's tools, available memory/disk, browser sandbox, memlock and Docker. Hashed host/workspace identities detect a shared host and overlapping work directories. Trusted main/project-tag AMD64 Server builds use slot 1 only when its Docker capability passes; Core uses slot 2 only when its existing toolchain and sandboxed browser pass. Otherwise those builds stay hosted. Tag requests verify main ancestry before private preflight/builds. Build and installed preflights have separate artifact names within the tag run. Native ARM64 always uses GitHub's ARM64 runner. Forks and routine PR builds stay hosted. Compiler caches are separated by architecture/configuration, with two compile jobs initially; Go, UI npm and pinned SDK/image caches remain. CI does not provision host packages or services.
When fresh installed passes are needed, project promotion runs AMD64 on slot 1 and ARM64 on slot 2 concurrently, with at most one job per agent. Each fresh Debian 13 guest retains 4 vCPUs, 4 GiB RAM and a 12-GiB virtual disk. Shared-host preflight requires at least 8 CPUs/12 GiB total plus available headroom and separate workspaces. AMD64 uses KVM only when usable; ARM64 on these X64 agents is explicitly TCG emulation. Same-source release requests are serialized. Do not add more private agents without profiling contention. Capability reports and actual job intervals establish placement and performance; labels alone do not.
For a reviewed same-repository PR, the existing server-runtime label requests both installed gates from that run's verified bundles. Adding the label triggers a run and subsequent updates retain it; removing it restores routine scope. Labeled fork PRs are rejected. Current operator policy remains signed scoped commits directly to main, without new PRs.
Installed gates retain real systemd, lifecycle/API/security checks, mounted
storage faults, durable ingestion, lost-ACK recovery, exact byte/identity checks,
and a locally owned sandboxed browser with trusted TLS. Unbuffered phase output,
elapsed times, bounded/redacted diagnostics and 30-second quiet heartbeats remain.
Failures stay failures. Installed evidence is retained separately under
server-installed-qualification-*; publishing requires both architectures.
A complete installed pass now earns an installed-result.json record in that
architecture's evidence artifact. It binds the exact input manifest, package,
fixtures, test sources, pinned image, VM profile and qualification policy, together
with the executing workflow/run/attempt and hashes of the public evidence.
The resolver independently verifies the successful architecture job and its required
steps. A successful sibling remains reusable even when another architecture fails.
An uploaded ci-installed-plan-* records which architectures were actually
requested, so a later failed or cancelled attempt cannot be hidden by an older pass.
A subsequent dry run or v* tag for those same inputs reuses the installed results.
If both are valid, it skips private preflight, VM preparation and VM jobs. If only
one is missing, expired or incompatible, only that architecture runs. Changed
inputs invalidate reuse; corrupted evidence stops promotion. Export revalidates
both installed passes and package bytes, and promotion.json preserves the original
per-architecture run/job/artifact references. A skipped VM job is never itself a
passing result. Manual installed qualification and tagged releases share workflow
per-source serialization, so a tag arriving during installed qualification consumes its
completed result without a second VM matrix. Reusable Server jobs have a separate
concurrency group to avoid waiting on their own release caller.
After diagnosing an installed failure, an explicit manual Packages / Server
dispatch may set requalify_architectures to a JSON array such as ["arm64"].
This requests only that fresh installed attempt while retaining an eligible AMD64
pass. The default is []; tag events cannot request this override. Requalification
is deliberate, never an automatic test retry. Existing artifacts without the new
installed result format cannot be retroactively treated as reusable passes.
Verified passes already earned through the former manual Release entry remain
eligible, with their original run/job/artifact identities.
Cross-compilation and a native package pass cannot substitute for these gates.
Gateway¶
The C/libwebsockets gateway builds and tests through the root installer or its component Makefile. Native tests cover route selection, IQ quarantine/frame facts, tuner capabilities, and the fixed-source FCC relay. The normal installer also runs a configuration-only self-check of the staged binary.
Repository validation¶
./scripts/validate.sh
./scripts/validate.sh --groups appliance,api
./scripts/validate.sh --full
./scripts/check-secrets.sh
git diff --check
Use the full validation path after changing detector algorithms, decoder sources/build matrix, generated assets, or cross-cutting persistence. Focused tests are appropriate during iteration; the final build must cover the changed boundaries.
The --groups example focuses on appliance/gateway work. Documentation-only
changes use the strict docs build, source-reference checks, and diff/secret
checks; they do not require receiver restarts or recompiling every decoder.
Changing an acceptance claim still requires evidence for that claim: a local
build is not live receiver or operator acceptance.
See publication checks for the separate scopes of secret scanning, privacy review, private exact matching, history auditing and release qualification. Private audit inputs are never part of contributor CI.
Appliance install¶
The synthetic example profile illustrates Pi 5 hardware relationships and
reserved network identity. Customize a private copy for a fresh installation.
The default example selector is not hardware detection. Normal upgrades preserve
installed configuration:
The installer warns about active SDR clients and proceeds. It copies the
complete static tree, compiles/tests the gateway, updates configuration and
services, and preserves host-only keys/tokens. --no-web-toolchain is valid
only when a complete, matching dist already exists.
The full installer stops/restarts appliance services even when browser build
hashes allow work to be skipped. --no-start still installs/enables files and
can stop existing services; it is not a dry run or a live-deploy option.
Gateway, decoder and demand services stop in that order and start in reverse.
Saved enabled continuous jobs resume; disabled jobs stay disabled. The installer
reports actual job states/faults after startup. Interactive clients must reconnect.
sudo rfsentry-jobctl list inspects jobs; rfsentry-jobctl --help explains the
default API configuration and automatic credential loading.
Use a reviewed private hardware profile for your installation. The public
example provides Pi 5 topology; adapt it explicitly for different hardware.
On a fresh appliance, explicitly supply the selected/edited identity file with
--appliance-config; upgrades preserve the installed identity and unrelated
API policy and installed hardware/health/firmware settings. Fresh hardware
requires a reviewed private --profile-dir; see
hardware profiles. For example:
sudo ./install.sh --install --profile-dir config/local/hardware-profile \
--appliance-config config/local/appliance.conf
This fresh-install example is a synthetic Pi 5 template; customize the profile before using it elsewhere. See identity and recovery profiles.
Do not execute a full install merely to verify documentation. The installer may update system configuration and restart services, and identity/port/TLS changes require gateway activation. Build checks and artifact preparation are not permission to interrupt an active receiver.
Development server¶
The Vite development server is for local UI iteration. It is not the appliance deployment model and does not replace TLS/origin/storage validation against the real gateway.
Adding a decoder¶
- Add a truthful manifest and build-matrix entry.
- Implement/import code behind the bounded decoder ABI.
- Record exact provenance, license, revision, hashes, and modifications.
- Add independent protocol fixtures and production-path IQ coverage where feasible.
- Regenerate the catalog and this site's decoder reference.
- Add a decoder chapter with its actual IQ path and limitations.
The catalog validator refuses missing ABI/build/provenance facts. Documentation does not get to vote a broken manifest into correctness, but it should make the breakage easier to find.