Skip to content

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:

./scripts/setup-git-hooks.sh
./scripts/check-secrets.sh
git diff --check

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

./scripts/build-docs.sh

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:

./scripts/node-toolchain.sh run node \
  tools/docs/generate-decoder-reference.mjs --check

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:

gh workflow run server-package.yml --ref main -f source_sha=FULL_COMMIT_SHA

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:

sudo ./install.sh --install

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

make web

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

  1. Add a truthful manifest and build-matrix entry.
  2. Implement/import code behind the bounded decoder ABI.
  3. Record exact provenance, license, revision, hashes, and modifications.
  4. Add independent protocol fixtures and production-path IQ coverage where feasible.
  5. Regenerate the catalog and this site's decoder reference.
  6. 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.