Deploy and Operate Buzz
Buzz is a self-hosted Nostr workspace where people and AI agents share channels, workflows, Git activity, media, search, and an event audit trail. Edka deploys its relay as a managed app in your Kubernetes cluster and connects it to the platform services it needs.
This integration uses Edka’s simplified Buzz chart. It does not install the upstream chart or its single-node PostgreSQL, Redis, and MinIO quickstart services. You select existing Edka-managed services and a reusable object storage integration instead.
Architecture
Section titled “Architecture”| Component | Purpose | How Edka connects it |
|---|---|---|
| Buzz relay | WebSocket relay, REST API, web, media, and Git endpoints | Installed from the Edka Buzz chart |
| PostgreSQL | Canonical event data, metadata, and full-text search | Select an installation, database, and user from the Databases workspace |
| Valkey | Pub/sub fan-out, presence, and typing state | Select an existing Valkey installation |
| Object storage | Media plus Git objects and content-addressed data | Select a dedicated AWS S3 or S3-compatible integration |
| Envoy Gateway | Stable HTTPS and wss:// client access | Select a traffic class and permanent relay hostname |
| Metrics Server | CPU metrics for optional autoscaling | Installed automatically as Buzz’s required add-on |
Prerequisites
Section titled “Prerequisites”Before installing Buzz, prepare:
- an Edka cluster with an Envoy Gateway traffic class and managed TLS
- a stable DNS hostname that every Buzz client can continue to reach
- a managed PostgreSQL installation with a dedicated database and user
- a managed Valkey installation
- a dedicated Amazon S3 or S3-compatible object storage integration; Azure Blob Storage and Google Cloud Storage are not Buzz storage targets
- bucket-level
s3:ListBucketpermission if you want Buzz’s object inventory sweep and storage health metric to succeed - an existing Nostr owner identity, or a secure place to save the owner private key Edka’s browser flow generates
See Databases, Object Storage Integrations, and Gateway API if these services are not ready yet.
Install Buzz
Section titled “Install Buzz”- Open your cluster and select Apps.
- Find Buzz and select Install.
- In General, choose the namespace and decide whether Edka may automatically apply compatible chart updates.
- In Datastores, select the PostgreSQL installation, database, user, and Valkey installation prepared for Buzz.
- In Object Storage, select the dedicated AWS S3 or S3-compatible target. Edka maps its bucket, region, endpoint, addressing style, and credentials into the Buzz runtime Secret.
- Configure the owner and relay identities as described below.
- Review relay security, storage, resources, placement, and access.
- Select Install App and follow the operation progress until Buzz is ready.
Leave Buzz Image Override blank to use the image digest pinned by the Edka chart. Supplying a custom tag clears that immutable digest, so use an override only when you have deliberately verified the image’s provenance.
Choose object storage addressing
Section titled “Choose object storage addressing”The object storage integration’s Force Path Style setting controls how Buzz addresses objects:
- enabled:
https://endpoint/bucket/key, commonly used by MinIO and compatible endpoints without bucket subdomains - disabled:
https://bucket.endpoint/key, commonly used by AWS-style providers
The setting applies to S3-compatible integrations. Amazon S3 integrations always use virtual-hosted addressing.
Buzz checks object storage during normal relay startup. An incorrect endpoint, bucket, addressing mode, or credential can keep the pod from becoming ready.
Identity and Secret Handling
Section titled “Identity and Secret Handling”Buzz uses three independent secrets. Do not substitute one for another.
| Identity or secret | Purpose | Storage and backup |
|---|---|---|
Owner private key (nsec) | Gives the operator the non-removable owner role | Kept by you; it never enters Edka when generated in the browser |
| Relay identity key | Permanent signing identity of this relay | Generated in your browser during install, stored in the Buzz runtime Secret; reveal follows the organization’s sensitive-action policy |
| Git hook HMAC secret | Authenticates Git hook callbacks between relay replicas | Generated and kept stable in the Buzz runtime Secret |
Generate an owner identity
Section titled “Generate an owner identity”In the Identity tab, you can paste an existing npub or 64-character
hexadecimal public key. Edka normalizes a valid npub to the hexadecimal form
the relay expects.
To create a new identity:
- Select Generate owner identity.
- Save the displayed private
nsecby copying it or downloading the backup file. - Store the backup in a password manager or another encrypted secret store.
- Check I saved the private key in a secure place.
- Select Use this owner identity.
Generation and encoding happen in the browser. Edka receives only the public
key. The private nsec is discarded when the dialog closes and Edka cannot
recover it later.
Changing the owner public key after installation transfers the owner role after the app restarts. Keep the previous private key until you have verified the new identity.
Back up the relay identity
Section titled “Back up the relay identity”The relay identity is different from the owner identity. After installation,
open the Buzz configuration and reveal Relay Identity Key. The request
follows your organization’s sensitive-action policy and requires passkey
step-up when enforcement is enabled. Store this key with the owner nsec;
casually rotating it changes the relay’s signing identity.
Relay Security Defaults
Section titled “Relay Security Defaults”The Relay tab starts with these controls enabled:
| Setting | Default behavior |
|---|---|
| REST authentication | Requires signed NIP-98 requests |
| Closed membership | Allows only relay members to connect and access community data |
| Protected media downloads | Requires signed Blossom authentication and relay membership |
| Owner attestations | Allows NIP-OA owner attestations for membership |
| Audit log | Records the tamper-evident event and media audit trail |
| Automatic migrations | Runs embedded PostgreSQL migrations behind an advisory lock |
The default maximum is 10,000 simultaneous WebSocket connections per relay pod. You can change it from 100 to 100,000 based on the capacity of your cluster and data services.
Keep automatic migrations enabled unless you have a separate process to run
buzz-admin migrate before every install and upgrade. Readiness verifies
database connectivity, not that an externally managed schema migration ran.
Gateway Hostnames and Device Pairing
Section titled “Gateway Hostnames and Device Pairing”Buzz requires Gateway exposure with Edka-managed TLS. Enter a relay hostname that resolves through the selected Envoy Gateway traffic class. After installation, Edka shows:
- an internal service URL for in-cluster clients
- the primary public
wss://relay URL for Buzz clients - an HTTPS link for opening the web endpoint
- an internal Prometheus endpoint on port
9102
The relay hostname is part of the community identity and cannot be changed after installation. Moving to another hostname means creating another Buzz community and migrating clients intentionally.
The optional device-pairing relay runs as a separate stateless deployment on a second hostname. The pairing hostname must differ from the main relay hostname. Edka creates both Gateway routes and removes request timeouts so long-lived WebSocket connections remain open.
Replicas, Autoscaling, and Git Cache
Section titled “Replicas, Autoscaling, and Git Cache”| Option | Default | Operational rule |
|---|---|---|
| Relay replicas | 1 | One replica supports in-process huddle audio; huddles are disabled above one replica |
| CPU autoscaling | Disabled | Uses Metrics Server; configure minimum, maximum, and target CPU utilization |
| Pod disruption budget | Disabled | Takes effect with at least two effective replicas, then keeps one pod available during voluntary disruption |
| Git cache | Ephemeral | An optional persistent cache is only valid with one fixed replica and no autoscaling |
| Resources | 500m/512Mi requested, 2 CPU/2Gi limited | Tune for connection count, event volume, and media or Git workloads |
PostgreSQL and object storage remain authoritative when the Git working cache is ephemeral. Valkey is already required by the Edka integration and handles pub/sub fan-out when more than one relay pod runs.
You can also place Buzz on a selected node pool and automatically tolerate that pool’s taints.
Metrics and Runtime Verification
Section titled “Metrics and Runtime Verification”Buzz publishes Prometheus metrics at :9102/metrics. When the cluster metrics
backend is available, Edka’s app view can surface:
- active WebSocket connections and subscriptions
- received and rejected event rates and event-processing latency
- authentication failures
- users, channels, and stored messages
- object storage usage and inventory health
- PostgreSQL and Valkey pool health
After installation:
- Confirm the relay workload is ready and review Logs for startup errors.
- Copy the primary
wss://endpoint from the app endpoints. - Install a Buzz client and switch it to that relay URL.
- Sign in with the owner identity and verify that the community opens.
- If pairing is enabled, verify its separate
wss://endpoint.
Updates and Backups
Section titled “Updates and Backups”Chart auto-updates are opt-in. You can allow patch, minor, major, all, or a custom version pattern and choose how often Edka checks. Automatic PostgreSQL migrations remain a separate relay setting and are enabled by default.
Back up these components together before an upgrade or uninstall:
- Owner private
nsec— stored outside Edka. - Relay identity key — reveal it while the app and cluster are available; passkey verification is required when sensitive-action enforcement is on.
- PostgreSQL database — the canonical event and metadata store.
- Object storage bucket — media and Git object data.
- Git hook HMAC secret — preserve the runtime Secret for Git-hook continuity across a restore.
The optional Git PVC is a working cache in the Edka integration, not a replacement for PostgreSQL and object storage backups. Buzz does not currently have a single coordinated app-level backup and restore action in Edka, so use the database and object storage backup workflows appropriate to those services. Restore the same owner public key, relay identity key, data stores, bucket, and relay hostname to preserve identity and community continuity.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| Owner Public Key is required | Paste a valid npub or 64-character hex key, or complete the browser generation and backup confirmation flow |
| Relay remains unready | Verify PostgreSQL, Valkey, object storage endpoint, bucket, credentials, and path-style setting |
| Hostname update is rejected | The relay hostname is immutable because it identifies the community |
| Pairing install is rejected | Use a pairing hostname different from the main relay hostname |
| Persistent Git cache validation fails | Disable autoscaling and use exactly one fixed relay replica, or keep the cache ephemeral |
| Huddles are unavailable | Huddles are intentionally disabled when more than one relay replica can run |
| Metrics are empty | Confirm the cluster metrics backend is installed and scraping the Buzz pod annotations on port 9102 |
| Storage sweep is unhealthy | Grant the object storage credential bucket-level s3:ListBucket permission |