block / block/buzz

Support Buzz as an app on Home Assistant

Open
#6,292 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

**Motivation**
What problem does this solve? Who runs into it and when?

I have Buzz running on a Raspberry Pi 5 with an SSD. It's working very well. I have Home
Assistant running on another Pi. It has a custom OS for HA. If I could install Buzz as an
app on HA OS I would only need 1 Pi. Buzz has been great for me so far and if it was
available as an app on HA I expect even more people would use it.

This generalizes past my setup: HA OS is one of the most common self-hosting
entry points for people who own hardware but don't want to administer a Linux
box. The app store gives you install, config schema, logs, updates, and backups
for free, and the audience overlaps heavily with Buzz's self-host story. Today
that audience can't run Buzz at all without standing up a second machine, since
HA OS has no general-purpose Docker access.

**Proposed solution**

A Home Assistant app repository (either official under `block/`, or a
`deploy/homeassistant/` directory here) containing `repository.yaml` plus a
`buzz/` app with `config.yaml`, `build.yaml`, `Dockerfile`, and `DOCS.md`.

Two design points that need decisions from the team:

1. *Single container.* HA apps are one container each, so the relay, Postgres,
Redis, and MinIO would need to be bundled behind s6-overlay v3 (`init: false`)
with a single entrypoint, with all state under `/data`. Prior art: the
community NetBox add-on bundles NetBox + Postgres + Redis this way
(https://github.com/boecht/ha-addon-netbox). This is close to what
`deploy/compose/` already does, minus Compose.

2. *Published `aarch64` images.* HA OS on a Pi is arm64, and building a Rust
workspace on-device isn't viable, so the app must pull a prebuilt image.
If `ghcr.io/block/buzz` isn't already multi-arch, that's the actual blocker
and the more broadly useful fix, since it also unblocks plain Docker on ARM
SBCs and Graviton.

The rest is mostly mapping `.env` to a `config.yaml` options schema
(`RELAY_OWNER_PUBKEY`, `BUZZ_RELAY_PRIVATE_KEY` as a password-type option,
`BUZZ_GIT_HOOK_HMAC_SECRET`, `BUZZ_HTTP_PORT`, `BUZZ_AUTO_MIGRATE`) and using
the `backup_pre` / `backup_post` hooks so HA backups get a consistent `pg_dump`
rather than a live data directory.

Two things worth calling out as non-goals:

- *Ingress probably doesn't apply to the relay.* Ingress proxies an HTTP UI
behind HA auth; Buzz desktop clients open a WebSocket with NIP-42 auth against
a fixed relay URL. The app should map a host port. Ingress may make sense for
`admin-web` only.
- *Storage sizing.* HA OS commonly boots from SD or eMMC, and the stack wants
~2.8 GiB RAM and ~15 GiB of git/media data. DOCS.md should tell users to move
the HA data disk to an SSD first, and be honest that a 4 GB Pi isn't enough.

**Alternatives considered**

- *Keep two Pis.* Works today, which is what I'm doing. Costs a machine and
duplicates backup and update chores.
- *HA Supervised instead of HA OS.* Gives you Docker and Compose, but it's the
least-supported HA install type and defeats the reason people pick HA OS.
- *Portainer or "Advanced SSH & Web Terminal" on HA OS.* Both are unsupported
routes to running non-app containers on HA OS. Fragile across HA updates.
- *An HA integration instead of an app.* Complementary rather than an
alternative: a `custom_component` that posts to a channel as a notify target
and exposes relay health, talking to a relay hosted anywhere. Useful on its
own, but it doesn't solve the one-Pi problem. Signing is the wrinkle, since
`rest_command` can't Schnorr-sign, so it needs `buzz-cli` or a secp256k1 dep.
Happy to open that separately if there's interest.

**Additional context**

- HA app developer docs: https://developers.home-assistant.io/docs/apps
- Bundled-services prior art: https://github.com/boecht/ha-addon-netbox
- Existing compose bundle this would derive from: `deploy/compose/`
- Duplicate search: none found in this repo.

I'm happy to prototype the app repository and open a PR if the team is open to
it. The arm64 image question is the part I can't answer from outside.

Contributor guide

Open the contributing guide

Research direction

Start by reading deploy/compose/ and the Home Assistant app documentation, then compare the proposed repository.yaml, buzz/config.yaml, build.yaml, Dockerfile, and DOCS.md structure with the existing deployment. Confirm the arm64 image availability and resolve the single-container, configuration, and backup-hook design decisions. Done means a working HA app repository with documented storage requirements and consistent pg_dump backups.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, docker-compose, rust
Domain
devops, infrastructure
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.