How to Self-Host Buzz: A Complete Guide to Deploying Your Nostr Workspace

Self-host Buzz by deploying the buzz-relay binary alongside PostgreSQL, Redis, and MinIO using the Docker Compose stack defined in deploy/compose/docker-compose.yml, or bootstrap a development environment using the Hermit toolchain at bin/activate-hermit.

Buzz is a self-hostable, Nostr-based team workspace maintained by Block that runs as a single-process relay. Learning how to self-host Buzz gives you complete control over your data and privacy while enabling you to host independent communities on your own infrastructure.

Architecture of a Self-Hosted Buzz Deployment

According to the block/buzz source code, self-hosting consists of three distinct layers that work together to provide a complete workspace environment.

Infrastructure Layer

The infrastructure layer orchestrates PostgreSQL for event persistence, Redis for pub/sub messaging, and MinIO for object storage. The reference implementation uses Docker Compose, with docker-compose.yml at the repository root handling development dependencies, and deploy/compose/docker-compose.yml providing a production-grade stack that optionally includes Caddy for TLS termination.

Relay Process Layer

The core binary buzz-relay implements the Nostr WebSocket protocol and HTTP endpoints. Built from the buzz-relay crate under crates/buzz-relay/, this process handles channel management, event storage, media upload via the /media endpoint, and workflow triggers. The entry point for the relay is located at crates/buzz-relay/src/main.rs.

Client Layer

Desktop, web, and mobile clients communicate via standard Nostr events defined in crates/buzz-core/src/kind.rs. The desktop application resides in desktop/ (built with Tauri 2 and React 19), the mobile client in mobile/ (Flutter), and the command-line interface in crates/buzz-cli/. All clients connect to your self-hosted relay using the same event protocol.

Prerequisites for Self-Hosting

Before deploying, ensure your environment meets these requirements:

• Docker 19+ installed for container orchestration
• Git for cloning the repository at https://github.com/block/buzz.git
• For development: Compatibility with the Hermit toolchain (automatically activated via . ./bin/activate-hermit)
• For production: A VPS or server with ports 3000 (relay) and 443 (HTTPS) accessible

Deployment Methods

You can self-host Buzz using either the development toolchain for local testing or the production Docker Compose stack for live environments.

Development Setup with Hermit

For local development, use the pinned toolchain to build from source. This method compiles the buzz-relay crate and launches the desktop client automatically.

# Clone the repository

git clone https://github.com/block/buzz.git && cd buzz

# Activate the pinned Rust/Node/PNPM toolchain

. ./bin/activate-hermit

# Initialize environment and start dependencies

just setup

The just setup command copies .env.example to .env, pulls Docker images, runs database migrations against the migrations/*.sql schema, and starts PostgreSQL, Redis, and MinIO containers.

Next, build and launch the full stack:

# Compile all Rust crates including buzz-core, buzz-db, and buzz-pubsub

just build

# Start the relay on ws://localhost:3000 and launch the desktop app

just dev

Production Deployment with Docker Compose

For production-grade hosting, use the single-node VPS bundle documented in deploy/compose/README.md:

# From the repository root

docker compose -f deploy/compose/docker-compose.yml up -d

This compose file wires the relay to PostgreSQL and Redis containers. After the containers start, the relay listens on ws://localhost:3000 (or the host configured in your .env file).

Alternatively, run the relay container directly with explicit environment variables:

docker run -d \
  -e POSTGRES_URL=postgres://buzz:pwd@postgres:5432/buzz \
  -e REDIS_URL=redis://redis:6379 \
  -e MINIO_ENDPOINT=minio:9000 \
  -p 3000:3000 \
  block/buzz:latest

Configuration and Environment Variables

Runtime configuration is controlled through environment variables defined in .env (created by copying .env.example):

• POSTGRES_URL – Connection string for the PostgreSQL database managed by crates/buzz-db
• REDIS_URL – Connection string for Redis, used by crates/buzz-pubsub for real-time fan-out
• MINIO_ENDPOINT – Object storage endpoint for media files
• CADDY_HOST and CADDY_EMAIL – Optional settings for automatic TLS in production

The Justfile at the repository root provides high-level task runners including just setup, just build, just dev, and just ci.

Connecting Clients to Your Self-Hosted Relay

Once the relay is running, point your clients to the WebSocket URL using the BUZZ_RELAY_URL environment variable:

export BUZZ_RELAY_URL=wss://my-relay.example.com
export BUZZ_PRIVATE_KEY=your-nostr-key-hex

Using the CLI (buzz-cli), you can interact with your self-hosted instance immediately:

# Fetch latest channel messages

buzz messages list

# Create a private channel

buzz channels create "project-alpha" --private

# Upload media files

buzz media upload ./demo.mp4

Desktop users can also modify the relay URL in the Settings screen rather than using environment variables.

Summary

• Buzz operates as a single-process Nostr relay built from the crates/buzz-relay/ directory, requiring only PostgreSQL, Redis, and object storage to function.
• Two deployment paths exist: Use . ./bin/activate-hermit followed by just dev for development, or run docker compose -f deploy/compose/docker-compose.yml up -d for production hosting.
• Configuration relies on .env variables including POSTGRES_URL, REDIS_URL, and optional CADDY_HOST for TLS termination.
• All clients (desktop, mobile, CLI) connect via standard Nostr events by setting BUZZ_RELAY_URL to your self-hosted WebSocket endpoint.
• File paths to remember: docker-compose.yml for development, deploy/compose/docker-compose.yml for production, and crates/buzz-relay/src/main.rs as the relay entry point.

Frequently Asked Questions

Can I run multiple Buzz communities on a single self-hosted instance?

Yes. While the default deployment hosts one community, the same codebase supports multi-tenant mode when run behind a reverse proxy. Configure separate database schemas or distinct relay URLs to isolate communities while sharing the underlying PostgreSQL and Redis infrastructure defined in deploy/compose/docker-compose.yml.

What hardware requirements are needed to self-host Buzz?

A single-node VPS with 2GB RAM and 20GB storage is sufficient for small teams. The buzz-relay binary is architected as a single-process application, though you should scale PostgreSQL and Redis independently if you anticipate high event volumes or large media uploads through the /media endpoint.

How do I migrate data between self-hosted Buzz instances?

Migrate your PostgreSQL database containing the event schema in migrations/*.sql and your MinIO object storage buckets. The Nostr event format ensures compatibility—simply point your new instance to the migrated database and update the BUZZ_RELAY_URL environment variable to reflect the new host.

Is TLS/HTTPS supported for the WebSocket connection?

Yes. The production Docker Compose stack in deploy/compose/docker-compose.yml optionally includes Caddy for automatic TLS termination. Set CADDY_HOST and CADDY_EMAIL in your .env file, or terminate TLS at your own reverse proxy before forwarding traffic to the relay on port 3000.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}