# Install Buttons on Debian or Ubuntu

> Install the headless Linux build with PostgreSQL 17, Valkey and Avahi, run it manually, and set it up as a systemd service.

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. Upgrade Buttons and Remove Buttons , for what happens later when you upgrade or remove this installation.