mirror of https://github.com/block/buzz.git synced 2026-08-18 06:50:31 +02:00

Files

T

Cea Stapleton Cordasco 6636ce9f68 docs(nips): specify v2 proxy transport and bounded denial observation

The published contract named a `trusted-proxy-hmac-v1` profile that no
implementation accepts. This replaces it with `trusted-proxy-hmac-v2` as the
sole stock proxy transport, specified from the wire format: envelope layout,
length-prefixed MAC input, canonical encodings, discovery identifier, replay
namespace, and lease bounds, with negative vectors.

Denial handling is re-scoped. The no-mutation invariant now covers
authoritative authorization state only, and denial observability moves to a
separately bounded, non-authoritative channel carrying reason codes and
correlation identifiers under payload minimization. A denied admission
creates no authorization receipt, and a failed observation write never
blocks, retries, or latches the denial.

Runtime operations, deployment, and integration guidance is framed as future
contract rather than current behavior. Subject stability is stated as a
verifier trust assumption with its reassignment consequence, and the
key-snapshot rollback claim is narrowed to what the model enforces.

This is a documentation change. It adds no runtime parser, adapter, or
enforcement path. Session-path rechecks and the policy digest input set
remain relay-side follow-ups. The 24 trace and 16 invariant identifiers are
unchanged.

2026-08-12 13:11:31 -05:00

.env.example

Add production Docker Compose bundle (#985 )

2026-06-13 13:28:25 -04:00

Caddyfile

Add production Docker Compose bundle (#985 )

2026-06-13 13:28:25 -04:00

compose.caddy.yml

Add production Docker Compose bundle (#985 )

2026-06-13 13:28:25 -04:00

compose.dev.yml

Multi-tenant Buzz relay: community_id as a server-resolved key (comprehensive rewrite) (#1321 )

2026-06-29 12:39:02 -04:00

compose.yml

Multi-tenant Buzz relay: community_id as a server-resolved key (comprehensive rewrite) (#1321 )

2026-06-29 12:39:02 -04:00

README.md

docs(nips): specify v2 proxy transport and bounded denial observation

2026-08-12 13:11:31 -05:00

run.sh

Multi-tenant Buzz relay: community_id as a server-resolved key (comprehensive rewrite) (#1321 )

2026-06-29 12:39:02 -04:00

README.md

Buzz Docker Compose deployment

This is the single-node/VPS deployment bundle. It is intentionally separate from the root docker-compose.yml, which remains local development infrastructure.

Quick start

cd deploy/compose
cp .env.example .env
$EDITOR .env       # replace every CHANGE_ME value
./run.sh start

For a public VPS with automatic Let's Encrypt certificates:

cd deploy/compose
BUZZ_COMPOSE_TLS=true ./run.sh start

The bootstrap script should eventually replace manual .env editing for normal users. It is responsible for generating stable secrets and, optionally, an owner keypair.

Production notes

Requires Docker Compose v2.24.4 or newer; the TLS override uses Compose's !reset tag to remove the direct relay port when Caddy terminates HTTPS.
Default BUZZ_IMAGE tracks ghcr.io/block/buzz:main for early testing. Pin it to ghcr.io/block/buzz:sha-<7> or a semver release tag for production once available.
Keep BUZZ_RELAY_PRIVATE_KEY, BUZZ_GIT_HOOK_HMAC_SECRET, database/Redis, and S3 secrets stable across restarts.
RELAY_OWNER_PUBKEY is intentionally not prefixed with BUZZ_; it must be a 64-character hex Nostr pubkey when closed relay mode is enabled.
BUZZ_AUTO_MIGRATE is opt-in. Set BUZZ_AUTO_MIGRATE=true or run buzz-admin migrate before starting the relay when bootstrapping a fresh database. Auto-migration requires an image that includes embedded SQLx migrations.
PostgreSQL must allow the pgcrypto extension — schema bootstrap and migrations run CREATE EXTENSION IF NOT EXISTS pgcrypto (used for gen_random_uuid() and digest hashing). On managed PostgreSQL, ensure the extension is permitted for the migration role or pre-create it as an administrator.
The proposed NIP-FI configuration contract is future-facing; this bundle does not imply that the current relay parses or enforces it. See the identity configuration contract.
The stack uses Postgres, Redis, MinIO, and a git data volume because those are real Buzz dependencies today. Minimal mode can simplify this later.

Run ./run.sh backup-hint for the backup checklist.

NIP-FI readiness

This Compose bundle does not provision a NIP-FI runtime, trusted edge, issuer integration, or conformance runner. It makes no claim that the proposed BUZZ_NIP_FI_V1_CONFIG_JSON document is parsed or enforced. Do not advertise or enforce NIP-FI from this bundle, and do not add a provider-specific sidecar or unsigned corporate identity header as a substitute.

An activating deployment must pin an exact image, isolate verifier ingress when trusted-proxy-hmac-v2 is enabled, deliver HMAC secrets through a secret store rather than .env, and pass the complete exact-head behavioral matrix before activation. A valid Compose render or healthy relay does not close those gates. See the provider-neutral deployment guide and runtime operations guide.

Validation

Before sharing an install link publicly, verify a fresh install with:

cd deploy/compose
cp .env.example .env
$EDITOR .env
./run.sh config
./run.sh start
curl -fsS "http://127.0.0.1:$(grep -E '^BUZZ_HTTP_PORT=' .env | cut -d= -f2-)/_liveness"
./run.sh status