Installing the Server

Installing the Server

The Server build is a native binary that talks to the rig (USB or LAN) and serves the web UI on https://<host>:8080. Pre-built packages are on GitHub Releases.

Downloads

Platform	Package	Distro
Linux x86_64	.deb (ubuntu2404)	Ubuntu 24.04 Noble
Linux x86_64	.deb (debian12)	Debian 12 Bookworm
Linux x86_64	.deb (debian13)	Debian 13 Trixie
Linux ARM64 / Raspberry Pi	.deb (ubuntu2404)	Ubuntu 24.04 Noble
Linux ARM64 / Raspberry Pi	.deb (debian12)	Raspberry Pi OS Bookworm / Debian 12
Linux ARM64 / Raspberry Pi	.deb (debian13)	Raspberry Pi OS Trixie / Debian 13
Linux x86_64	.AppImage	Any distro with glibc 2.36 or newer
Linux ARM64 / Raspberry Pi	.AppImage	Any 64-bit distro with glibc 2.36 or newer
macOS	zip	Apple Silicon
Windows	zip	x86_64

Which .deb? The tag in the filename says: ubuntu2404 for Ubuntu 24.04, debian12 for Debian 12 and Raspberry Pi OS Bookworm, debian13 for Debian 13 and Raspberry Pi OS Trixie. Each is built natively on its distro so the library dependencies match.

Linux: .deb

sudo apt install ./wfweb_<version>-<distro>_<arch>.deb

On a Raspberry Pi OS Lite or another desktop-less system the package pulls in Qt's GUI libraries as recommends (wfweb itself never opens a window). To keep the install small:

sudo apt install --no-install-recommends ./wfweb_<version>-<distro>_<arch>.deb

or use the AppImage, which bundles everything.

Linux: AppImage

chmod +x wfweb_*.AppImage
./wfweb_*.AppImage

It bundles Qt, RADE, codec2 and everything else above glibc. The host needs glibc 2.36 or newer, the ALSA library (libasound2) and OpenSSL 3 (library plus the openssl command, used to create the certificate on first start). If it complains about FUSE, run it with --appimage-extract-and-run.

macOS

Unzip and run wfweb from a terminal. Apple Silicon only. The radio's USB serial port is found automatically for the usual Icom models; pass --serial-port otherwise.

Windows

Unzip and run wfweb-launcher.exe. It is a small window that picks the serial port or the LAN rig, the audio device and the web port, starts wfweb.exe with the matching flags, shows its log, and opens the browser once the server answers. wfweb.exe itself is unchanged: run it from a console with the flags on Command-Line Options whenever you prefer. Details in launcher/README.md.

First run

USB radio

Plug the radio in and run:

./wfweb

Any supported Icom is auto-detected over USB at its default CI-V address. If you changed the radio's CI-V address, pass it:

./wfweb --civ 0x94   # hex as shown on the radio, or decimal (148)

Then set the radio's CI-V USB menu as in Icom Menu Settings, or you get control but no scope.

LAN radio

For Icoms with Ethernet or Wi-Fi (IC-7610, IC-9700, IC-7300 Mk2, IC-705…) give the address and the credentials you set in the radio's network menu:

./wfweb --lan 192.168.1.100 --lan-user admin --lan-pass secret

Add --civ 0x<addr> for a non-default CI-V address. To start with the LAN session closed, so a restart never grabs a radio another client is using, add --no-autoconnect (or WFWEB_NO_AUTOCONNECT=1) and connect from the web UI's Reconnect button.

Open the page

Open https://<host>:8080 and accept the self-signed certificate warning. The certificate is generated on first start and kept in wfweb's data directory; to use your own, put wfweb-web.crt and wfweb-web.key there. Port 8081 is the plain-HTTP REST API for scripts; do not open the UI there.

The terminal status page

Started from an interactive terminal, wfweb shows a status page instead of the scrolling log: the URL to open for each network address, the rig and its connection, frequency and mode, connected browsers, the REST and rigctld ports, the log file and the last warning. l switches to the live log and back, q or Ctrl-C quits. Under systemd, with -b, in Docker, or piped, you get the plain log. --no-tui forces the plain log on a terminal too.

Starting at boot (systemd)

make install and the .deb install a unit template. Enable it for the user whose settings you want:

sudo systemctl enable --now wfweb@$USER

For the AppImage, point a unit's ExecStart at the file; systemd/wfweb@.service in the repository is the template to copy.

Where things live

	Linux	Docker
Settings	~/.config/wfweb/wfweb.conf	/data/wfweb/wfweb.conf
Certificate, logbook	~/.local/share/wfweb/wfweb/	/data/wfweb/wfweb/
Log file	/tmp/wfweb-*.log (or -l <file>)	container stdout
Rig files	/usr/local/share/wfview/rigs (or next to the binary)	in the image

Windows and macOS use the platform's equivalents under the user profile. --settings <file> moves the settings file; --logbook <file> moves the log.