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

> Learn how to self-host Buzz, the Nostr workspace, with our complete guide. Deploy Buzz Relay using Docker Compose or bootstrap a dev environment with Hermit.

- Repository: [Block Open Source/buzz](https://github.com/block/buzz)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/docker-compose.yml) at the repository root handling development dependencies, and [`deploy/compose/docker-compose.yml`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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.

```bash

# 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:

```bash

# 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`](https://github.com/block/buzz/blob/main/deploy/compose/README.md):

```bash

# 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:

```bash
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:

```bash
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:

```bash

# 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`](https://github.com/block/buzz/blob/main/docker-compose.yml) for development, [`deploy/compose/docker-compose.yml`](https://github.com/block/buzz/blob/main/deploy/compose/docker-compose.yml) for production, and [`crates/buzz-relay/src/main.rs`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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.