Repository navigation
Install Raspberry Pi
A Pi at the kegerator is the sweet spot for Kegwall: perfect reception for Kegtron's UDP pour multicast (same network segment, no VLAN questions), onboard Bluetooth for the Kegtron BLE fallback (Gen 1 and Pro), and enough CPU for the whole stack. Recommended hardware: Pi 5 (4GB+) — the only model whose PMIC can report power draw on the admin's Tonight page; a Pi 4 (4GB) works fine minus the watts readout; a Pi 3B is only suitable as a tablet-mode display.
Not a Pi? The same native installer runs on an amd64 mini PC / Intel NUC on Debian 13 — see mini-pc.md. CPU temp (coretemp/k10temp) and power (RAPL) work there too; only the Pi-only undervoltage flags are absent.
-
Server mode —
pi-install.sh, no kiosk: the server runs headless; HDMI (if plugged in) shows the normal login terminal. -
Kiosk mode —
pi-install.shwith kiosk enabled: the same server, plus this Pi's screen boots straight into the tap wall (cage + chromium — works on Pi OS Lite, no desktop needed). The installer also offers a lighter native client (--native-wall) — cog / WPE WebKit instead of chromium, rendering the same wall in a smaller, faster engine; see native-wall.md for that path and for how to tell which display mode a screen is in (cat /etc/kegwall/display-mode). -
Tablet mode — a SEPARATE touchscreen Pi running only a browser pointed at the
server's
/tabletpage (pi-tablet-setup.sh): no Node, no server components.
Two server install styles are first-class — pick one:
- Docker — pull the published multi-arch image; updates via the Watchtower sidecar and the admin UI's Update button.
- Native (bare metal) — one guided installer sets up Node, the app, and systemd units: a self-updater, an OS updater, and a reboot trigger the admin UI can fire.
mkdir -p ~/kegwall && cd ~/kegwall
curl -fsSLO https://raw.githubusercontent.com/dlommm/Kegwall/main/deploy/docker-compose.pi.yml
openssl rand -hex 16 # your Watchtower API token — paste into the compose file
docker compose -f docker-compose.pi.yml up -dOpen http://<pi-ip>:8080, create the admin account, and follow the guided setup —
it picks the Watchtower update mode for you and ends with every URL for the box.
Paste the token in Settings → System afterwards. (The compose file's comments
explain the host-network / loopback-sidecar topology; general Docker reference lives
in docker.md.) In Docker Tonight's This server row shows CPU/RAM/disk
but no SoC temperature or watts, and the OS-update controls stay hidden — those are
native-install features.
One command on a fresh Raspberry Pi OS (64-bit, Lite is fine):
curl -fsSL https://raw.githubusercontent.com/dlommm/Kegwall/main/scripts/pi-install.sh | sudo bashThe installer is interactive: it asks for the port, the Bluetooth fallback,
kiosk mode ("show the tap wall on this screen at boot?"), and OS auto-updates —
Enter accepts every default. Every question also exists as a flag for automation
(--port, --with-ble, --kiosk, --os-updates off|auto, --auto-reboot,
--non-interactive, --dir, --repo-url); a passed flag is not asked about.
What it installs: Node 24 (NodeSource) + build toolchain, a kegwall system user,
the app checked out at its latest release tag, and these systemd units:
| Unit | Job |
|---|---|
kegwall.service |
the server (KEGWALL_INSTALL=native tells the app it can offer OS controls) |
kegwall-update.{service,path} |
app self-update — Settings → System → Update now |
kegwall-os-update.{service,path} |
OS apt update — Settings → System → Update OS now |
kegwall-reboot.{service,path} |
reboot from Tonight's Reboot now button |
kegwall-kiosk.service |
kiosk mode only — cage + chromium on tty1 |
The admin UI writes a trigger file into the data directory; the matching path unit runs the privileged work. The app process itself needs zero privileges, and each updater removes its trigger before doing anything (loop-guard) and rolls back on failure.
After install: open http://<pi-ip>:8080, create the admin account, and the guided
first-run setup does the rest — site name, Kegtron key, your first wall (created
automatically, with any known Kegtron devices attached; the server also auto-attaches
the first Kegtron that ever reports to an empty wall), update mode (native is
preselected), and a final screen listing every URL for the box.
Uninstall: sudo systemctl disable --now kegwall kegwall-update.path kegwall-os-update.path kegwall-reboot.path kegwall-kiosk 2>/dev/null, re-enable the
console with sudo systemctl enable --now getty@tty1, remove
/etc/systemd/system/kegwall*.{service,path} and /usr/local/bin/kegwall-*.sh,
sudo deluser kegwall; sudo deluser kegwall-kiosk, and delete the install dir (back
up <dir>/data first — that's the database and label images).
Kegwall itself: Settings → System → Check for updates → Update now. The UI shows progress and confirms the new version when the server is back (typically under a minute on Docker, a few minutes for a native rebuild).
The OS (native installs only): Settings → System → Operating system:
-
Manual — an "Update OS now" button runs
apt full-upgradein the background (output injournalctl -u kegwall-os-update). If the update needs a reboot, the admin's Tonight page lists "An OS update is waiting for a reboot" under Needs attention, with a Reboot now button (admins only, asks first) and an explicit warning, because the wall goes dark for a minute or two and pours during the window are lost unless they sync back from Kegtron cloud. - Automatic — unattended-upgrades (provisioned by the installer's OS-updates question; re-run the installer if you skipped it). The auto-reboot toggle decides whether the Pi may reboot itself (04:00) when required.
Manual fallbacks:
- Docker:
docker compose -f docker-compose.pi.yml pull && docker compose -f docker-compose.pi.yml up -d - Native:
cd /opt/kegwall && sudo -u kegwall git fetch --tags && sudo -u kegwall git checkout --force <vX.Y.Z> && sudo -u kegwall npm ci && sudo -u kegwall npm run build && sudo systemctl restart kegwall
The Hardware list on the admin's Tonight page polls GET /api/system/stats for its This
server row: CPU load, RAM, disk,
uptime, SoC temperature, and — Pi 5 only — live power draw in watts (older Pis
have no power-measurement hardware). Undervoltage is checked on every poll,
including the sticky "happened at some point since boot" firmware flag: a Power problem
row appears at the top of Needs attention and a warning is logged, because chronic undervoltage corrupts SD cards. Use
the official PSU (27 W / 5 A on a Pi 5).
Enabled by the installer's kiosk question (or --kiosk). It installs
kegwall-kiosk.service: a cage (Wayland kiosk compositor) session on tty1
running chromium fullscreen at http://localhost:8080/wall/main — no desktop stack,
works on Pi OS Lite, waits for the server's /api/health before starting the
browser, hides the cursor, and restarts itself if chromium ever dies. The login
terminal on tty1 is disabled (that's the point); sudo systemctl disable --now kegwall-kiosk && sudo systemctl enable --now getty@tty1 brings it back.
To repoint it (different wall slug, different port):
sudo /opt/kegwall/scripts/pi-tablet-setup.sh --local --force http://localhost:8080/wall/<slug>
For real backlight power-off (not just browser screensaver), pair the kiosk with the display agent to control DPMS (X11) or Pi touchscreen backlight.
A second Pi with the official touchscreen makes a great dedicated pourer tablet. It runs ONLY the browser — install nothing else on it:
curl -fsSL https://raw.githubusercontent.com/dlommm/Kegwall/main/scripts/pi-tablet-setup.sh | sudo bash -s -- http://<server-ip>:8080/tablet/main
sudo rebootSame cage service as kiosk mode (Lite-friendly, fullscreen, touch-enabled,
self-restarting) but pointed at the remote server, with the cursor left visible.
Re-run with a new URL to repoint it. On a desktop image the script asks before
disabling the display manager (--desktop keeps the old in-desktop autostart
instead; --force skips the question). An Android tablet is the other option for
this role — see android-tablet.md.
Camera permission (face sign-in): the cage service's Chromium is launched with
--user-data-dir=/home/kegwall-kiosk/.kegwall-kiosk (see the flags in
pi-tablet-setup.sh) — a real, persistent profile directory for the dedicated
kegwall-kiosk system user, not a wiped-per-boot temp dir, so any camera-permission
grant Chromium records there survives reboots and future pi-tablet-setup.sh re-runs
against the same URL. If you use face sign-in, kiosk
Chromium usually still shows its normal one-time "use your camera?" prompt — tap
Allow once on the touchscreen. If your build's chrome-less kiosk mode never
surfaces that prompt, add --use-fake-ui-for-media-stream to the ExecStart line in
/etc/systemd/system/kegwall-kiosk.service and restart the service — it silently
auto-grants getUserMedia requests (it does not fake the camera itself, only the
prompt) and is the standard workaround for headless/kiosk browsers. No camera on the
Pi → neither the prompt nor the flag matters; the tablet just uses the ordinary avatar
grid.
- On the old server: Settings → Backup → Download backup (a
.dbfile). - On the fresh Pi install: Settings → Backup → Restore, upload it, restart — the restore is staged and applied atomically at the next boot. This carries the whole database: beers, taps, kegs, pours, users, and all settings incl. secrets.
-
Label images are NOT in the .db — copy them from the old data directory
(
/datain Docker,appdataon Unraid) into the Pi's data directory by hand. - Re-check Settings → System afterwards: the update mode came over with the old settings and probably names the OLD deployment style — set it for this box.
The installer's BLE question (or --with-ble) installs BlueZ and grants the raw-
socket capability. Two independent toggles then exist in Settings → Kegtron and sources:
-
Gen 1 (KT-100/KT-200) — the verified path: the decoder in
src/server/ingest/gen1/bleSource.tsis a byte-exact port of the realkegtron-bleHome Assistant parser (github.com/Bluetooth-Devices/kegtron-ble). - Pro (KT-220/KT-420) — our own reverse-engineered advertisement format (docs/kegtron/pro-ble-format.md, captured live from a KT-420 and validated with a real pour). Pros only transmit the new total at the END of a pour — this path records finished pours within seconds without UDP or cloud, but live pour progress on the wall still requires UDP. That's a transmitter-side limitation, not a receiver one.
Manual setup (what --with-ble automates):
sudo apt-get install -y bluetooth bluez libbluetooth-dev libudev-dev
sudo setcap cap_net_raw+eip $(eval readlink -f "$(which node)")(Re-run the setcap after any Node upgrade — the capability binds to the binary
inode.) BLE uses @abandonware/noble, an optionalDependency — if its native build
failed at install time, the connection doctor (Settings → Diagnostics) shows the import error.
Running the MQTT-bridge path (esp32-gen1.md) at the same time is
fine: BLE wins for any Gen 1 device it's actively hearing (a live sighting within
the last 5 minutes), MQTT is the fallback — see bleSource.ts/mqttSource.ts's
"BLE/MQTT DEDUPE" comments.
The Displays & Presence hub's GPIO motion transport (a gpio-type source added on the
hub's own Motion sources panel, /admin/presence — not Settings -> Sources, which
only holds the shared MQTT broker connection and a few enable toggles) shells out to the
libgpiod CLI (gpiomon) rather than talking to /dev/gpiochip0 directly, so it needs
libgpiod's userspace tools installed:
sudo apt install gpiod(pi-install.sh does not automate this the way it does the Bluetooth fallback above —
add it by hand if you're wiring up a PIR sensor.) Nothing else is required on bare
metal: a native install already runs as a user with access to /dev/gpiochip0 on Pi OS.
Running under Docker instead needs the chardev explicitly mapped into the container —
see docker.md's GPIO device-mapping section.
For wiring a PIR sensor (HC-SR501/AM312) to a GPIO pin, choosing a GPIO line number, and the rest of the supported motion-sensor hardware (mmWave, BLE, Zigbee), see docs/setup/motion-sensors.md — the dedicated sensors guide.
- docker.md — general Docker reference: env vars, networking modes, reverse proxy + HTTPS, backups.
- kegtron-cloud.md — API key + the UDP live-pour path.
- android-tablet.md — the Android alternative for the tablet.
Mirrored from docs/install/raspberry-pi.md. Edit the repo copy; this page is regenerated from it.
- Admin Dashboard
- Beers
- Cleaning And Pours
- Customization
- Insights
- Install Android Tablet
- Install Display Agent
- Install Docker
- Install Esp32 Gen1
- Install Mini Pc
- Install Moving To Github
- Install Native Wall
- Install Raspberry Pi
- Install Unattended Debian
- Kegtron Pro Ble Format
- Menu And Kiosk
- People
- Recovery
- Settings
- Setup Face Sign In
- Setup Home Assistant
- Setup Kegtron Cloud
- Setup Motion Sensors
- Suppliers
- Taps And Kegs