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