buzz-self-hosting

name	buzz-self-hosting
description	Use when helping a user set up, debug, or operate a self-hosted Buzz relay through Docker Compose. Do not use for general Docker questions or non-Buzz Nostr deployments.
version	1.0.0
metadata	{"hermes":{"tags":["buzz","self-hosting","relay","docker","compose","deployment","troubleshooting","nostr"]}}

Buzz Self-Hosting Guide

Walk the user through standing up their own buzz-relay with the Docker Compose stack in deploy/compose/, and debug it layer by layer when agents or clients misbehave. Every footgun in here was hit in a real setup; check them before inventing new theories.

Guide, don't drive: give the user paste-ready commands and let them run anything that changes state. Verify results yourself with read-only checks (logs, rosters, queries).

The mental model

• One relay = one community. The relay URL IS the community. The relay routes connections to a community by the exact hostname in BUZZ_DOMAIN. A connection with any other Host gets 404 on the WebSocket upgrade — this looks like "relay is down" but isn't.
• The stack is: relay + Postgres (events, search, memberships) + MinIO (media + git packfiles) + Redis (pub/sub only, nothing durable) + a git volume.
• On a closed relay (RELAY_OWNER_PUBKEY set, BUZZ_REQUIRE_RELAY_MEMBERSHIP=true), everything that connects — humans AND agents — must be in the relay member roster.

Setup steps

1. cd deploy/compose && cp .env.example .env, then edit .env:
   • Secrets are all generated/invented locally. Nothing comes from a portal. openssl rand -hex 32 for BUZZ_RELAY_PRIVATE_KEY and BUZZ_GIT_HOOK_HMAC_SECRET; invent Postgres/Redis/S3 passwords (Compose creates those services with whatever you set).
   • RELAY_OWNER_PUBKEY = the user's own pubkey, 64-char hex, from their Buzz Desktop profile. Footgun: this var has no BUZZ_ prefix — easy to miss among neighbors that all do.
   • BUZZ_RELAY_PRIVATE_KEY is the relay's identity. Set once, never rotate; back up .env itself.
   • Pin BUZZ_IMAGE to a release tag for anything long-lived; :main moves daily.
2. Set the URL block (BUZZ_DOMAIN, RELAY_URL, BUZZ_MEDIA_BASE_URL, BUZZ_MEDIA_SERVER_DOMAIN, BUZZ_CORS_ORIGINS) — all derive from one host choice. See the localhost footgun below before choosing.
3. ./run.sh config (validates; catches leftover CHANGE_ME), then ./run.sh start. TLS on a public domain: BUZZ_COMPOSE_TLS=true ./run.sh start.
4. Liveness: curl -fsS http://127.0.0.1:3000/_liveness.
5. Register members: ./run.sh add-member <pubkey> for every human and every agent, with sleep 1 between adds (same-second roster events collide). Verify with ./run.sh list-members.
6. Connect the desktop app with the exact RELAY_URL, create channels, add agents to channels, @mention.

Footgun: never use localhost for a local relay — use 127.0.0.1 everywhere

buzz-core::relay::normalize_relay_url rewrites every loopback host to 127.0.0.1 (localhost, ::1). The desktop app runs each managed agent's relay URL through it before spawning the harness. The relay, however, routes by the literal BUZZ_DOMAIN. Result with BUZZ_DOMAIN=localhost: the app itself connects fine (its own HTTP client doesn't rewrite the Host header) but every agent harness gets 404 and exits code 1. The app UI offers no way around it — the per-agent relay_url field is deliberately ignored (agents always inherit the active workspace relay).

Therefore: for local deployments set BUZZ_DOMAIN=127.0.0.1 and use ws://127.0.0.1:3000 in the app and everywhere else. Real public domains are unaffected.

Diagnostic — test the host routing directly (101 = good, 404 = wrong host):

curl -s -o /dev/null -w "%{http_code}\n" -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" -H "Sec-WebSocket-Version: 13" http://<host>:3000/

Footgun: changing BUZZ_DOMAIN re-keys the community

The relay ensures its deployment community keyed to the host (Deployment community ensured, host=... in relay logs). Change the domain → restart → a fresh empty community. The desktop app will keep showing the old community's channels and member lists from cache — messages even still send (kind 9) — but channel records (39000/39002, 9007/9000) don't exist relay-side, so agents discover 0 channels no matter what the UI shows.

Fix: in the app, remove the community entirely and re-add it, then create channels fresh. Verify server-side, not in the UI:

docker compose --env-file .env -f compose.yml logs relay --since 10m | grep '"Event ingested via pipeline"'

Channel creation must produce kind 9007/40100 events; adding a member to a channel produces kind 9000. If the user "did it in the app" but those kinds never arrive, the app state is stale — clean re-add.

Debugging agents that don't respond — check layers in this order

Agent harness logs: %APPDATA%\xyz.block.buzz.app\agents\logs\<agent-pubkey>__<relay-hash>.log (Windows). Read the newest run — stale error banners in the app UI often describe an old failure.

Log symptom	Layer	Fix
relay connect failed ... 404 Not Found, exit 1	Hostname routing	127.0.0.1 everywhere (see above)
Connects, but roster (list-members) lacks the agent	Relay membership	./run.sh add-member <agent-pubkey>
discovered 0 channel(s) — agent will sit idle	Channel membership	Add agent to a channel; verify a kind-9000 event lands; if UI says it's added but log still says 0 → stale community state, clean re-add
discovered 1 channel(s) + subscribed, mention ignored	respond_to	Default is owner-only; only the owner's mentions wake it
Wakes but errors instead of replying	Model auth	Per-runtime credentials (Hermes setup, Claude login, OpenAI key) — plumbing is fine

Agent pubkeys and (plaintext!) private keys live in %APPDATA%\xyz.block.buzz.app\agents\managed-agents.json — treat as sensitive. The entries with private_key_nsec are the runtime records.

A healthy sequence in the harness log: connected to relay → discovered N channel(s) → subscribed to channel <uuid>; live adds show membership notification: subscribing to new channel.

Windows-specific footguns

• ./run.sh is bash. In PowerShell it opens the file in an editor instead of running. Use Git Bash (/d/path style paths) or bash run.sh.
• Git Bash mangles container paths: docker compose exec relay /usr/local/bin/buzz-admin ... becomes C:/Program Files/Git/usr/local/bin/... and fails with "OCI runtime exec failed". Fix: export MSYS_NO_PATHCONV=1 first, or run docker commands from PowerShell.
• $EDITOR .env is a Unix-ism; PowerShell users should notepad .env.
• A file named .env looks nameless in Explorer unless "File name extensions" is on.
• If the app won't launch, check for hung instances: Get-Process buzz-desktop, buzz-acp — multiple Not-Responding buzz-desktop processes block new launches. Kill them all: Get-Process buzz-desktop, buzz-acp -ErrorAction SilentlyContinue | Stop-Process -Force.

Verification & inspection

• Base stack exposes only relay port 3000. Admin surfaces need the dev overlay: BUZZ_COMPOSE_DEV=true ./run.sh start → MinIO console :9001 (S3 creds from .env), Adminer :8082 (server postgres, user buzz), Prometheus :9090. Home machines only — the overlay also publishes Postgres and Redis.
• Prove data is local: docker compose --env-file .env -f compose.yml exec -T postgres psql -U buzz -d buzz -c "SELECT kind, left(content,60) FROM events WHERE kind=9 ORDER BY created_at DESC LIMIT 5;"
• Postgres = the record (events partitioned by month, mention index, FTS, audit log, rosters). MinIO = media (content-addressed SHA-256) + git packfiles. Redis = disposable.

Backups

Volumes live inside Docker Desktop's WSL2 disk — not browsable, not backed up until dumped to real files:

copy .env <backup-dir>\env-backup.txt
docker compose --env-file .env -f compose.yml exec -T postgres pg_dump -U buzz buzz > <backup-dir>\buzz-db.sql
docker run --rm -v buzz-prod_buzz-minio-data:/data -v <backup-dir>:/backup alpine tar czf /backup/minio-data.tar.gz -C /data .
docker run --rm -v buzz-prod_buzz-git-data:/data -v <backup-dir>:/backup alpine tar czf /backup/git-data.tar.gz -C /data .

.env is part of the backup — restoring data volumes without its keys restores nothing.

Hosted → self-hosted migration

There is no export tool. Identity keypairs carry over (same person everywhere); agent definitions are local files; git repos migrate fully (clone from hosted, push to new relay). Channel history, DMs, media, canvases do not. A new relay starts empty — set expectations before the user tears anything down, and don't remove hosted communities until anything worth keeping (repos, archives via buzz messages get) is pulled.