Install on Linux and Raspberry Pi

Install a ControlBird Community Edition node from a .deb or .rpm package and run it as a system service.

The Linux package installs a complete ControlBird Community Edition node and runs it as a system service. It is the alternative to running the node in Docker, and it suits a Raspberry Pi or any small Linux machine that runs the node full time.

Requirements

  • A 64-bit Linux machine with systemd: amd64 or arm64.
  • Debian, Ubuntu or Raspberry Pi OS for the .deb package. Fedora or Red Hat compatible distributions for the .rpm package.
  • At least 1 GB of RAM; 2 GB is recommended.

Raspberry Pi

Raspberry Pi 3, 4 and 5 are supported when running a 64-bit operating system. 32-bit Raspberry Pi OS is not supported. Use the arm64 package. The node writes to disk continuously, so an SSD or a high-endurance card lasts longer than a standard SD card.

Install the package

Use the package file that matches your machine's architecture. On Debian, Ubuntu and Raspberry Pi OS:

sudo apt install ./controlbird_<version>_<arch>.deb

On Fedora and Red Hat compatible distributions:

sudo dnf install ./controlbird-<version>.<arch>.rpm

The installer creates a controlbird service account, enables the controlbird service and keeps its data in /var/lib/controlbird. It does not start the node, so you can review the settings first.

Start the node

sudo systemctl start controlbird

The first start takes a short while because the node configures itself. Check on it with:

systemctl status controlbird
journalctl -u controlbird -f

Then open http://<machine address>:3000 in a browser. The first person to open it claims the node in the setup wizard. Continue with Access the ControlBird UI.

Settings

Process settings live in /etc/controlbird/controlbird.env. The node name and port are read the first time the node starts, so set them before the first start. Changing them afterwards has no effect, and a different node name starts a new, empty node next to the old one.

Network access

The web interface uses ports 3000 (HTTP) and 3443 (HTTPS). The node also listens on 9100 for its own services. Allow only the web ports through your firewall, and keep 9100 reachable from trusted machines only.

Back up your data

Everything the node stores is under /var/lib/controlbird. Back up that directory, including the sealing-key file inside the node's folder. The key protects stored passwords and tokens, and a backup without it cannot restore them.

Upgrade and remove

To upgrade, install the newer package with the same command. A running node restarts on the new version, and a stopped node stays stopped. Your data and settings are kept.

sudo apt remove controlbird

Removing the package keeps your data and settings, so reinstalling picks up where you left off. On Debian based systems, sudo apt purge controlbird deletes the data and settings as well. The controlbird service account is never removed.