buzz/deploy/charts/buzz

Buzz Helm Chart

Buzz is a Nostr-based messaging platform for human–agent collaboration: a single relay binary serving WebSocket + REST + web UI, backed by PostgreSQL, Redis, and S3-compatible object storage. NIP-50 search defaults to Postgres full-text search, with Typesense available as a fallback backend.

This chart has two operating profiles selected by values:

Profile	When	What you get
Production (default)	Self-hosted multi-tenant, regulated, or GitOps-managed	External managed Postgres/Redis/S3, Postgres FTS search by default, secrets.existingSecret:, no chart-side autogen, HA-capable (replicaCount ≥ 2)
Quickstart (eval)	Eval, single-node, one-off demo	In-cluster Postgres + Redis + MinIO, chart auto-generates relay + service secrets, single replica

Quickstart (eval only)

helm install buzz oci://ghcr.io/block/buzz/charts/buzz --version 0.1.0 \
  --create-namespace --namespace buzz \
  --set quickstart=true \
  --set postgresql.enabled=true \
  --set redis.enabled=true \
  --set minio.enabled=true \
  --set relayUrl=wss://buzz.example.com \
  --set ownerPubkey=<64-char-hex-pubkey>

This brings up the required quickstart dependencies in-cluster — Postgres, Redis, and MinIO (with its bucket created by a post-install Job) — and composes the relay's BUZZ_S3_ENDPOINT plus autogenerated credentials automatically. Search defaults to Postgres FTS (search.backend=postgres), so no Typesense service is required. The quickstart=true flag is an intent marker surfaced in NOTES.txt; the bundled services are opted in via the per-service *.enabled flags (see ci/quickstart-values.yaml for the exact set CI installs). Eval-only: every bundled service is a single replica with no HA.

Production (GitOps)

The chart is designed for ArgoCD and Flux. Both render charts with helm template, in which mode Helm's lookup function returns empty — any chart-side randAlphaNum call would regenerate secrets on every sync. The chart-managed Secret path is only safe for helm install / helm upgrade.

Production deploys MUST use secrets.existingSecret:. The Secret is consumed for any keys present and ignored for keys missing — extras are harmless.

See:

• examples/argocd-app.yaml — ArgoCD Application
• examples/flux-helmrelease.yaml — Flux HelmRelease v2
• examples/secret-sample.yaml — Secret schema

Required inputs

Key	What	When required
relayUrl	Public wss:// URL clients connect to	Always
ownerPubkey	64-char lowercase hex Nostr pubkey of the relay operator	When relay.requireRelayMembership=true (default)
secrets.existingSecret	Name of pre-created Secret	Production / GitOps
externalPostgresql.url / externalRedis.url / s3.endpoint	External service URLs	Production — when the matching bundled service is disabled (the default)

The chart fails at helm install / helm template time with a clear message if any of these are missing or malformed (see templates/_validate.tpl).

HA (production)

replicaCount > 1 hard-requires both:

• Redis (redis.enabled=true, externalRedis.url, or REDIS_URL in existingSecret) — for buzz-pubsub fan-out
• ReadWriteMany git PVC — persistence.git.accessMode: ReadWriteMany with a RWX storage class (e.g. efs-sc on AWS, azurefile-csi on Azure)

The chart template-fails if either invariant is broken. No silent degradation.

Upgrades

Schema migrations are embedded in the relay binary via sqlx::migrate! and run at startup, gated by BUZZ_AUTO_MIGRATE (default true). Multiple replicas race-safely behind a Postgres advisory lock. helm upgrade is the entire upgrade procedure.

If you prefer decoupling migrations from serving, set migrate.autoMigrate=false. In that mode the chart does not run migrations for you — you own running buzz-admin migrate (separate Pod / one-shot Job) against the database before every helm install / helm upgrade. Readiness probes only verify DB connectivity, not schema freshness, so a pod will appear healthy against an unmigrated schema and fail under load. A pre-upgrade Helm Job for this is on the chart roadmap; the values knob migrate.preUpgradeJob.enabled is reserved.

Backups

Save these. Losing any of them is data loss. See NOTES.txt printed by helm install for the live list:

1. BUZZ_RELAY_PRIVATE_KEY — relay identity. Rotating it = new identity (federation peers will not recognize the relay).
2. PostgreSQL database — the canonical event store.
3. S3 bucket — media blobs (chart default bucket: buzz-media).
4. Git PVC — repo on-disk state served by the relay's git endpoint.
5. Owner private key — held by the operator, not by this chart. Restore by re-installing with the same ownerPubkey.

Honest limitations (v1)

• Bundled MinIO is eval-only. The quickstart profile runs an in-cluster MinIO (single replica, no HA, lookup-autogenerated credentials) so the relay starts with zero external object-storage dependencies. Production leaves minio.enabled off and points s3.endpoint (or BUZZ_S3_* in existingSecret) at managed S3-compatible storage. The bundled Deployment is not GitOps-safe and is not intended for production traffic.
• Typesense is a fallback search backend. Default search is Postgres FTS (search.backend=postgres). To use Typesense instead, set search.backend=typesense and provide either typesense.url/apiKey, TYPESENSE_URL/TYPESENSE_API_KEY in secrets.existingSecret, or typesense.enabled=true for eval-only in-cluster Typesense.
• Minimal-mode is not yet supported. The relay's BUZZ_PUBSUB=local / filesystem media paths are upstream work in progress — even quickstart currently stands up real Redis and S3 rather than the relay's single-node fallbacks.
• OCI publish to GHCR + cosign signing is a follow-up PR. For now, install the chart from source: helm install buzz ./deploy/charts/buzz after cloning the repo.

Development

# Render every fixture
for f in ci/*-values.yaml tests/fixtures/*-values.yaml; do
  helm template buzz . -f "$f" >/dev/null && echo "ok: $f"
done

# Unit tests
helm plugin install https://github.com/helm-unittest/helm-unittest
helm unittest .

# Lint
helm dependency build .
ct lint --config ../../../ct.yaml --charts .