Linux Installation (Ubuntu, Debian, Raspberry Pi, Fedora)¶
Disclaimer
AIS-catcher is intended for hobbyist and research projects only. It is NOT approved for use in navigation or safety-of-life applications. Read the full disclaimer.
AIS-catcher is installed with a single script that installs all dependencies, sets up a background service and starts it. The script works on Debian-based systems (Debian, Ubuntu, Raspberry Pi OS) and on Fedora, detecting apt or dnf automatically.
There are two ways to run your station:
- Managed mode (recommended) — configure and control your station from the browser.
- Manual mode — configure via the command line or configuration files.
Managed Mode¶
Run the install script
Open a terminal or log in via SSH, then run:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/jvde-github/AIS-catcher/main/scripts/aiscatcher-install) -p -M"
If curl is not available on your device, install it with sudo apt install curl (or sudo dnf install curl on Fedora).
Upgrading an existing install?
Switching from manual mode to managed mode starts with fresh settings: your existing configuration (/etc/AIS-catcher/config.json and config.cmd) is not carried over. The files themselves are left untouched, so you can refer to them when re-entering your settings via the setup wizard. Re-running the installer on an existing managed installation is just an update — your settings are kept.
Complete the setup wizard
Open the dashboard in your browser on port 8118, e.g. http://localhost:8118. On first use, the setup wizard walks you through configuring your input device and outputs, and starts the receiver:
That's it — your station is up and running. See Getting Around the Dashboard to monitor and fine-tune it.
Manual Mode¶
To configure via the command line instead, omit the -M option:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/jvde-github/AIS-catcher/main/scripts/aiscatcher-install) -p"
The background service infrastructure is still set up — see Running as a Service for the configuration files and service commands.
Install from Source¶
Both commands above install the latest pre-built package (the -p option) — a .deb on Debian-based systems, or an .rpm on Fedora. Pre-built RPMs are provided for Fedora 43 and 44 on x86_64 and aarch64; on other Fedora releases use the source build below. Leave out -p to build AIS-catcher from source instead:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/jvde-github/AIS-catcher/main/scripts/aiscatcher-install) -M"
Building from source optimizes the executable for your hardware but can take a significant amount of time (20 minutes on a Raspberry Pi 4). It is required if you need PostgreSQL support, which is not included in the pre-built packages.
Note
The pre-built packages statically link the latest Osmocom library to guarantee support for the RTL-SDR V4, and are not compatible with the first versions of the Raspberry Pi and Zero due to their limited support for floating point hardware acceleration.
Updating¶
To update AIS-catcher to the latest version, simply run the install command again. It will not overwrite any configuration files when these are available on the system.
Remote Start/Stop and Host Management¶
The separate AIS-catcher-control package adds browser-based control of the AIS-catcher process (start and stop, live log) and of the host itself (one-click updates, reboot). It is not included in the install above — install it with:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/jvde-github/AIS-catcher-control/main/install_ais_catcher_control.sh)"