Repository navigation
Install Docker
The supported way to run Kegwall. One image, one persistent volume.
- Docker Engine with the Compose plugin (
docker compose versionshould work). Docker Desktop on macOS/Windows or a Linux host both work for the basic path below. - A Linux host if you need Kegtron Cloud's UDP broadcast discovery or the Gen 1 direct-Bluetooth source — see Networking: bridge vs. host mode.
git clone <this repo's URL> kegwall
cd kegwall/deploy
docker compose up -dThen open http://<host>:8080. First visit sends you to a one-time admin setup screen
(pick a username/password — there is no default login).
This builds the image locally from the Dockerfile in the repo root (deploy/docker-compose.yml
sets build.context: ..). A published multi-arch (amd64 + arm64) image also exists at
ghcr.io/dlommm/kegwall — tagged latest plus each release version, built
by GitHub Actions for every release. To use it instead of building locally, swap the
build: block for image: ghcr.io/dlommm/kegwall:latest (or start from
deploy/docker-compose.unraid.yml, which is already pull-only).
- Single production image (multi-stage build: deps -> web build -> runtime). No dev
dependencies, no Playwright, no build toolchain in the final layer — see the
Dockerfile's own comments for the full reasoning. Built image is roughly 644MB. - Runs as a non-root
nodeuser. -
HEALTHCHECKpollsGET /api/health({"status":"ok"}when the server is up) every 30s. - Everything the app needs to persist — the SQLite database (
app.db), uploaded beer label images, and any staged backup/restore file — lives under/data, declared as aVOLUME.deploy/docker-compose.ymlmounts a named volume there (kegtron-data) so it survivesdocker compose down/ image upgrades.
Everything is environment variables — there is no config file. All have sane defaults
baked into the image (Dockerfile's ENV block); you only need to override them if you
have a reason to.
| Variable | Default (in-image) | Purpose |
|---|---|---|
PORT |
8080 |
HTTP port the server listens on. |
DATA_DIR |
/data |
Where app.db, uploads, and staged restores live. |
WEB_DIR |
/app/dist/web |
Built SPA assets routes/static.ts serves. |
NODE_ENV |
production |
Disables Fastify's dev-mode pretty logger. |
Everything else (site name, Kegtron API key, MQTT broker, alert channels...) is configured from the admin UI's Settings page after first login, not via environment variables — see docs/setup/kegtron-cloud.md and docs/setup/home-assistant.md.
deploy/docker-compose.yml uses Docker's default bridge network, which is fine for every
MQTT-based ingest path (Kegtron Cloud's WebSocket notify channel, Home Assistant
publishing, an external BLE-to-MQTT bridge) since those are outbound TCP connections the
container makes to a broker/server.
Two things need deploy/docker-compose.host-network.yml instead:
-
Kegtron Cloud's UDP broadcast/multicast relay (
Settings -> Sources -> "Listen for Kegtron UDP broadcasts") — Docker's bridge network NATs the container onto an isolated subnet, so LAN broadcast/multicast traffic never reaches it. Host networking puts the container directly on the host's network namespace, the same as a non-containerized process. -
The Gen 1 direct-Bluetooth source (
Settings -> Sources -> "Listen for Kegtron Gen 1 Bluetooth adverts directly") — talks to the host's Bluetooth adapter over a raw HCI socket, a host kernel resource bridge networking doesn't mediate at all. This also needs--privileged(or--cap-add=NET_ADMIN --cap-add=NET_RAW) and the adapter reachable inside the container — see docs/install/raspberry-pi.md for the full BLE setup.
network_mode: host only behaves as documented on a Linux host (bare metal or a Raspberry
Pi). Docker Desktop on macOS/Windows runs containers inside a Linux VM, so "host"
networking there is the VM's network, not your actual LAN — UDP discovery will not work
under Docker Desktop regardless of this setting.
cd deploy
docker compose -f docker-compose.host-network.yml up -dThe 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) spawns the
libgpiod CLI (gpiomon) against a chardev like /dev/gpiochip0
— see docs/install/raspberry-pi.md for the
bare-metal apt install gpiod setup, and
docs/setup/motion-sensors.md for the sensor buying/wiring
guide. That device is not
visible inside a container by default, in either networking mode above, since device
passthrough is orthogonal to network_mode — a bridge-network container (the default
deploy/docker-compose.yml) needs it exactly as much as a host-network one
(deploy/docker-compose.host-network.yml). Add it explicitly:
docker run --device /dev/gpiochip0 ...or, in either compose file's services.kegwall block:
devices:
- /dev/gpiochip0Without this, gpiomon inside the container can't see the host's GPIO chip at all, and
the connection doctor (Settings → Diagnostics) reports motion_gpio unhealthy with an actionable "install
libgpiod and map /dev/gpiochip0 into the container" detail rather than silently doing
nothing.
Kegwall has no built-in TLS — it's meant to sit behind a reverse proxy (Caddy, nginx, Traefik) if you want HTTPS, or to stay on a trusted LAN over plain HTTP.
Be aware of one specific thing before exposing it beyond a trusted LAN: the session cookie
(src/server/routes/auth.ts) is set httpOnly + sameSite: 'lax' but does not set the
Secure flag, and the server does not inspect X-Forwarded-Proto to decide whether to
add it. That's deliberate for LAN-over-plain-HTTP use (a Secure cookie would simply not
be sent at all over HTTP, breaking login for the common "just run it on the taproom LAN"
case) — but it does mean the cookie has no browser-enforced guarantee against being sent
over an unintended plaintext hop.
Practical guidance:
- If you terminate TLS at a reverse proxy, make sure every hop the browser can reach is HTTPS (redirect HTTP -> HTTPS at the proxy, don't leave a bare HTTP listener reachable in parallel) — the proxy terminating TLS doesn't retroactively protect a cookie that could still be sent to a plaintext endpoint if one exists.
- Prefer restricting access to a VPN or trusted LAN over exposing the login page directly to the public internet, since there's no additional cookie-level defense-in-depth here beyond what the proxy provides.
- The container itself doesn't need to know it's behind TLS — the proxy just needs to
forward requests to
http://<container>:8080as usual; no extraPORT/env configuration is required on the app side for a reverse-proxy setup.
The admin UI's Settings page has a Backup panel (download a consistent snapshot, or upload+stage a restore). Full details, including the crash-loop recovery procedure if a restore goes wrong, are in docs/recovery.md — read that before you ever need it, not after.
You can also back up the whole /data volume directly from the host, independent of the
app:
docker run --rm -v deploy_kegtron-data:/data -v "$PWD":/backup \
alpine tar czf /backup/kegtron-data-backup.tar.gz -C /data .(Volume name may differ — check docker volume ls; Compose prefixes it with the project
directory name, e.g. deploy_kegtron-data when run from deploy/.)
In-app: with a Watchtower sidecar in HTTP-API mode (see the commented block in
deploy/docker-compose.unraid.yml or the ready-made deploy/docker-compose.pi.yml),
Settings → System → Update now pulls and swaps the container in the background —
no shell needed. Manual:
cd deploy
docker compose pull # only if you switched to the published registry image
docker compose build # only if still building locally from source
docker compose up -dThe named volume is untouched by an image rebuild/pull — your data persists across
upgrades. Database schema migrations run automatically on server startup
(src/server/db/migrate.ts).
Tonight's This server row works in a container too, with caveats: CPU/RAM
figures come from /proc and describe the host (not the container's cgroup
limits), disk describes the volume holding /data, and SoC temperature / throttle
flags / watts read as unavailable (vcgencmd doesn't exist in the image). The
OS-update and reboot controls are hidden entirely — they're native-Pi-install
features (systemd trigger units).
- docs/install/raspberry-pi.md — Docker or bare-metal on a Pi, plus direct-BLE and kiosk-mode wall setup.
- docs/install/esp32-gen1.md — Gen 1 (KT-100/KT-200) devices via an ESP32 BLE-to-MQTT bridge.
- docs/recovery.md — backup/restore, including manual crash-loop recovery.
- docs/customization.md — walls, themes, custom CSS, screensaver.
Mirrored from docs/install/docker.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