Skip to content

Installation

Jump to bottom
magicint1337 edited this page Sep 5, 2025 · 13 revisions

Installation

Clean, repeatable steps to get NovaSDR built and running with its built‑in web server. No external reverse proxy is required.

Note

NovaSDR was previously called "PhantomSDR‑Plus". You may still see legacy names in banners or logs; functionality is unchanged.

Contents

  • Requirements
  • Platform packages
    • Debian/Ubuntu (incl. Raspberry Pi OS)
    • Arch Linux / Manjaro
    • Fedora / CentOS Stream / RHEL
    • openSUSE (Leap/Tumbleweed)
    • Alpine Linux
  • GPU/CPU OpenCL acceleration (NVIDIA, AMD, Intel, Portable/CPU)
  • Build steps (backend + frontend)
  • Verify installation
  • Next steps

Requirements

Backend toolchain:

  • C++23 compiler (GCC 12+/Clang 15+)
  • Meson, Ninja, pkg-config
  • Libraries:
    • FFTW3f
    • zstd
    • FLAC++
    • zlib
    • Boost (system, iostreams)
    • libcurl

Optional accelerators (only if you intend to use them):

  • OpenCL runtime and headers (plus your GPU vendor’s runtime/driver)
  • CUDA toolkit (cuFFT) for NVIDIA GPUs
  • Intel MKL (when specifically compiled with MKL)

Frontend toolchain:

  • Node.js 18+ (for development and production build)

Important

Accelerators must be both installed on the system and compiled into NovaSDR to be usable. If you request an accelerator that isn’t compiled in, the server exits with a clear error (handled in broadcast_server::broadcast_server()).

Platform packages

Debian / Ubuntu (22.04+)

sudo apt update && sudo apt install -y \
  build-essential meson ninja-build pkg-config git \
  libfftw3-dev libzstd-dev libflac++-dev zlib1g-dev \
  libboost-system-dev libboost-iostreams-dev libcurl4-openssl-dev \
  nodejs npm

Optional (common tools and OpenCL loader):

sudo apt install -y clinfo ocl-icd-opencl-dev

Tip

For Ubuntu derivatives, package names are the same. If your Node.js is old, install a current LTS from NodeSource or nvm.

Raspberry Pi OS (Bookworm, 64‑bit recommended)

Raspberry Pi OS is Debian‑based, so package names match. Use 64‑bit (arm64) for best toolchain compatibility.

sudo apt update && sudo apt install -y \
  build-essential meson ninja-build pkg-config git \
  libfftw3-dev libzstd-dev libflac++-dev zlib1g-dev \
  libboost-system-dev libboost-iostreams-dev libcurl4-openssl-dev \
  nodejs npm clinfo ocl-icd-opencl-dev

OpenCL on Raspberry Pi:

  • NovaSDR does not support GPU acceleration on Raspberry Pi. Do not attempt to enable GPU OpenCL.
  • If you want to validate an OpenCL path on the CPU, use POCL (portable CPU OpenCL): 
    sudo apt install -y pocl-opencl-icd
clinfo | grep -E "Platform Name|Device Name"
  • In your config, keep: 
    [input]
accelerator = "none"

Arch Linux / Manjaro

sudo pacman -S --needed \
  base-devel meson ninja pkgconf git \
  fftw zstd flac zlib boost curl \
  nodejs npm clinfo ocl-icd

OpenCL providers (choose what matches your hardware):

  • NVIDIA: opencl-nvidia
  • AMD (AMDGPU/RADV): opencl-amd or Mesa’s intel-compute-runtime not for AMD; for AMD, ROCm packages are available via the AUR for supported GPUs
  • Intel (Gen9+/Xe): intel-compute-runtime
  • Portable CPU: pocl

List installed platforms:

clinfo | grep -E "Platform Name|Device Name"

Fedora / CentOS Stream / RHEL

sudo dnf install -y \
  gcc-c++ meson ninja-build pkgconf-pkg-config git \
  fftw-devel zstd-devel flac-devel zlib-devel \
  boost-system boost-iostreams curl-devel \
  nodejs npm clinfo ocl-icd ocl-icd-devel

OpenCL providers:

  • NVIDIA: enable RPM Fusion, install NVIDIA driver and xorg-x11-drv-nvidia-cuda (provides OpenCL ICD)
  • AMD: ROCm OpenCL is available on recent Fedora releases for supported GPUs (rocm-opencl-runtime). For others, Mesa’s mesa-opencl package may expose Rusticl on supported hardware
  • Intel: intel-compute-runtime via third‑party repositories; for older CPUs, beignet (legacy) or POCL

Verify:

clinfo | grep -E "Platform Name|Device Name"

openSUSE (Leap / Tumbleweed)

sudo zypper install -y \
  gcc-c++ meson ninja pkgconf-pkg-config git \
  fftw3-devel libzstd-devel libFLAC++-devel zlib-devel \
  libboost_system-devel libboost_iostreams-devel libcurl-devel \
  nodejs npm clinfo ocl-icd ocl-icd-devel

OpenCL providers:

  • NVIDIA: install proprietary driver and opencl-nvidia
  • AMD: ROCm (supported GPUs) or mesa-opencl
  • Intel: intel-compute-runtime (if available) or POCL (pocl)

Alpine Linux (edge/testing recommended for dev stacks)

sudo apk add --update \
  build-base meson ninja pkgconf git \
  fftw-dev zstd-dev flac-dev zlib-dev boost-dev curl-dev \
  nodejs npm clinfo ocl-icd-dev

OpenCL providers:

  • NVIDIA: packages available in community/testing with proprietary drivers
  • AMD/Intel: Mesa Rusticl (mesa-opencl) or POCL (pocl)
  • Portable CPU: pocl

Note

Alpine’s musl toolchain is stricter; if you hit compilation issues, ensure all -dev headers are present and consider edge/testing repositories.

GPU/CPU OpenCL acceleration

NovaSDR can use OpenCL (or CUDA/MKL) if compiled with those backends and the runtime is available.

  • Verify installation:

    clinfo | grep -E "Platform Name|Device Name"

    You should see at least one platform and device (GPU or CPU).

  • Enable in configuration:

    [input]
accelerator = "opencl"   # or "cuda" or "mkl"

    Selection and validation are performed during startup (see broadcast_server::broadcast_server()).

Vendor‑specific notes (Linux):

  • NVIDIA

    • Install the proprietary driver for your GPU
    • Install CUDA toolkit (optional but recommended for development)
    • Ensure an OpenCL ICD is present (on Ubuntu/Debian usually via the driver package; loader via ocl-icd-opencl-dev)
    • Verify with clinfo

  • AMD

    • ROCm OpenCL runtime for supported GPUs (modern discrete Radeon)
    • Otherwise, use Mesa’s OpenCL (Rusticl) if supported on your GPU/driver
    • Verify with clinfo

  • Intel

    • For modern iGPUs and Xe GPUs: Intel Compute Runtime (Level Zero + OpenCL)
    • For CPU fallback: Intel oneAPI OpenCL (CPU runtime) or POCL
    • Verify with clinfo

  • Portable CPU OpenCL (works on anything)

    • POCL (pocl-opencl-icd on Debian/Ubuntu, pocl on Arch/Fedora/openSUSE/Alpine)
    • Useful for validating OpenCL on systems without a supported GPU

Warning

Requesting accelerator="opencl" or "cuda" or "mkl" without the corresponding backend compiled into NovaSDR will cause a critical error and exit. Keep accelerator="none" if unsure.

Build steps

  1. Clone (or open your checkout)
git clone https://github.com/Steven9101/NovaSDR.git
cd NovaSDR
  1. Backend: configure and compile
meson setup build
meson compile -C build
  • Backend config, dependencies, and compile flags are defined in meson.build.
  1. Frontend: install and build
cd frontend
npm install
npm run build
cd ..
  • This produces static assets in frontend/dist/.
  1. Serve the built UI from NovaSDR
[server]
html_root = "frontend/dist/"

Tip

The server’s default html_root may already be suitable. If you change where you build the UI, update html_root accordingly.

Verify installation

Binary check:

./build/spectrumserver --help

You should see CLI usage printed from the program’s entry point:

  • CLI parsing and help text live in main()

Minimal run check (without a live SDR yet):

  • Prepare a minimal config.toml (see Configuration)
  • Start NovaSDR with that config: 
    ./build/spectrumserver --config config.toml
  • In a second terminal, pipe a short sample or test stream when ready (see Devices)

Note

NovaSDR expects raw samples on stdin. Without an active capture tool piping samples to the process, the UI will load but no spectrum/waterfall will update.

Next steps

Clone this wiki locally