Install Buttons on Debian or Ubuntu

Buttons runs as a set of managed background services, so it fits onto a dedicated Debian or Ubuntu server the same way any other production service does: no desktop session required, and it restarts on its own if the machine reboots. This page covers installing the headless Linux build, running it manually to confirm it works, and setting it up as a systemd service for unattended operation.

Before you begin#

sudo access and an internet connection on the target machine.
A Debian or Ubuntu system. Buttons requires PostgreSQL 17 specifically, installed from the official PostgreSQL repository rather than the distribution's default package.
The downloaded Linux build, extracted to a working directory.

Install prerequisites#

Update the system and install curl:

   sudo apt update
   sudo apt upgrade
   sudo apt install curl

Add the official PostgreSQL repository and install PostgreSQL 17:

   sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
   curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/postgresql.gpg
   sudo apt update
   sudo apt install -y postgresql-17

Buttons manages and runs its own PostgreSQL instance, so disable the system-wide one:

   sudo systemctl disable postgresql
   sudo systemctl stop postgresql

Install Valkey and Avahi (for mDNS/Bonjour discovery):

   sudo apt install -y valkey-server avahi-daemon libnss-mdns libudev1

Buttons manages and runs its own Valkey instance, so disable the system-wide one:

   sudo systemctl disable valkey-server
   sudo systemctl stop valkey-server

Create a group for device access, copy in the udev rules, and reload:

   sudo addgroup buttons
   sudo adduser $USER buttons
   sudo cp 50-bitfocus-buttons.rules /etc/udev/rules.d/
   sudo udevadm control --reload-rules

Replug any Stream Decks so they pick up the reloaded rules, and open a new terminal session so your group membership takes effect before continuing.

Run manually#

From the extracted build directory:

./watchdog-cli 127.0.0.1 4440

reaches the UI at http://127.0.0.1:4440 (https://127.0.0.1:4443) from the local machine only. Use 0.0.0.0 instead of 127.0.0.1 to make it reachable from other machines on the network. If Buttons is already running, stop it first; starting a second instance conflicts with the one already using these ports and this configuration.

Configuration, data, and logs are stored under $HOME/.config/bitfocus-buttons for whichever user ran the command: include that directory in your backup plan alongside the in-app backups described in Create your first backup.

Run as a service#

The build includes an example systemd unit (bitfocus-buttons.service) that expects a buttons user to exist and belong to a buttons group, running from /opt/bitfocus-buttons. None of that exists yet after the steps above: set it up:

sudo useradd --system --create-home --shell /usr/sbin/nologin --gid buttons buttons
sudo mkdir -p /opt/bitfocus-buttons
sudo cp -r . /opt/bitfocus-buttons/
sudo chown -R buttons:buttons /opt/bitfocus-buttons
sudo cp /opt/bitfocus-buttons/bitfocus-buttons.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bitfocus-buttons

The provided unit listens on 0.0.0.0:4440; edit /etc/systemd/system/bitfocus-buttons.service before enabling it if you need different arguments.

Check that it's running:

sudo systemctl status bitfocus-buttons
journalctl -u bitfocus-buttons -f

Because the service runs as the buttons system user, its configuration and data live under that user's home directory rather than yours: keep that in mind when locating logs or planning backups for a service install.

Where to go next#

Create your first backup, to protect the configuration you're about to build.
Manage your Buttons license, or activate Buttons offline if this machine has no internet access.
Choose an installation path, for how this fits alongside the other supported ways to install Buttons.
Startup configuration reference, for every command-line flag and environment variable watchdog-cli supports.
Update or remove Buttons, for what happens later when you update or remove this installation.

Was this helpful?

0 of 0 users found this page helpful