Installation

Installation

Requirements

• Python 3.8 or newer
• An RTL-SDR dongle for live capture (optional for UI work and synthetic fixtures)
• Linux is recommended. macOS and Windows require suitable USB drivers.

Local install

git clone https://github.com/Slayingripper/SpectrumAlert.git
cd SpectrumAlert

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Verify the CLI:

spectrum-alert --help
spectrum-alert version

Receiver access on Linux

Confirm the dongle is visible:

lsusb | grep 0bda:2838
rtl_test -t

If rtl_test reports a permissions error, add your user to plugdev and reload the session:

sudo usermod -aG plugdev "$USER"

The RTL-SDR packages ship udev rules on most distributions. Reconnect the dongle after installing them.

Check that SpectrumAlert sees the receiver:

spectrum-alert monitor status

A missing dongle is not a startup failure. The dashboard still loads and reports that no SDR is attached.

Docker install

docker compose up -d

Open http://localhost:8088. See Docker for USB access, ports and headless profiles.

Remote receivers

A receiver on another host can be used through rtl_tcp:

# On the remote host
rtl_tcp -a 0.0.0.0 -p 1234

# In SpectrumAlert
spectrum-alert geo add-receiver Hill --lat 35.08 --lon 33.38 \
  --mode rtltcp --host 10.0.0.5 --port 1234

Verify the install

spectrum-alert monitor status
spectrum-alert geo receivers
pytest

The UI contract and backend test suite runs without an SDR. The single hardware-dependent collection test requires a real dongle.

Next

• Quick Start
• Web Dashboard
• CLI Reference