Buzz Relay on Coolify

This repository deploys Buzz Relay as a Git-backed Docker Compose application on Coolify. It deliberately does not fork Buzz:

• Buzz runs from Block's published ghcr.io/block/buzz image.
• The image tracks Block's official main tag by default.
• This repository owns only deployment policy and the temporary Coolify fixes.
• No GitHub Actions or local Buzz build is required.

Included fixes

The stack includes fixes that are not yet available in stable Coolify:

1. BUZZ_CORS_ORIGINS includes tauri://localhost and http://tauri.localhost, allowing Buzz Desktop to connect.
2. buzz-git-init makes the persistent Git volume writable by Buzz's UID 1000.
3. The Buzz healthcheck uses Bash /dev/tcp; the runtime image has no curl or wget.
4. No custom Docker network is defined, so Coolify's proxy always uses the correct managed network.
5. buzz-pair-relay runs as an ephemeral, auth-free sidecar and Traefik sends only wss://YOUR_DOMAIN/pair to it, allowing Buzz Desktop to pair a phone.

Mobile device pairing

Buzz mobile pairing cannot use the authenticated main relay: the phone begins with a fresh ephemeral key that is not a relay member yet. This stack therefore runs the dedicated buzz-pair-relay binary already bundled in the official Buzz image. It stores no history or pairing data and has no persistent volume.

The main relay advertises wss://YOUR_DOMAIN/pair through NIP-11. A high-priority Traefik rule routes that exact path to the pairing sidecar on its private port 5000; every other path continues to use the main relay on port 3000. Do not point BUZZ_PAIRING_RELAY_URL directly at the main relay and do not publish port 5000 on the host.

One-time Coolify setup

1. Push this directory to a GitHub repository.

2. In Coolify, create a Private Repository (with GitHub App) resource.

3. Select this repository and choose the Docker Compose build pack.

4. Use branch main, base directory /, and Compose file /docker-compose.yaml (Coolify's default).

5. Add the variables from .env.example in Coolify. Generate new values for every CHANGE_ME entry and store them only in Coolify. Create the private S3-compatible bucket before deploying. Do not add a BUZZ_IMAGE_TAG override during normal operation; the reviewed value in docker-compose.yaml controls updates.

6. Clear Escape special characters in labels? in the application's Docker Compose settings. This allows Docker Compose to expand BUZZ_DOMAIN inside the custom Traefik /pair rule; leaving it enabled makes the hostname literal and /pair continues to reach the main relay with HTTP 404.

7. Assign https://YOUR_DOMAIN:3000 to the buzz service. The :3000 tells Coolify which internal container port to proxy; the public URL still uses normal HTTPS on port 443.

8. Deploy, then verify:

   curl -fsS https://YOUR_DOMAIN/_liveness
   curl -fsS https://YOUR_DOMAIN/_readiness
   # A plain GET must return 400; 404 means /pair is still hitting the main relay.
   test "$(curl -sS -o /dev/null -w '%{http_code}' https://YOUR_DOMAIN/pair)" = 400

Do not expose Postgres, Redis, pairing port 5000, health port 8080, or metrics port 9102 publicly.

Cloudflare R2 storage

Production media and object data is stored in a private Cloudflare R2 bucket. Create a bucket-scoped Object Read & Write token and configure:

BUZZ_S3_ENDPOINT=https://YOUR_CLOUDFLARE_ACCOUNT_ID.r2.cloudflarestorage.com
BUZZ_S3_REGION=auto
BUZZ_S3_ADDRESSING_STYLE=path
BUZZ_S3_BUCKET=buzz-nutrified-media
BUZZ_S3_ACCESS_KEY=YOUR_R2_ACCESS_KEY_ID
BUZZ_S3_SECRET_KEY=YOUR_R2_SECRET_ACCESS_KEY

Do not enable the public r2.dev URL or attach a public bucket domain. Buzz keeps the bucket private and serves authorized media through https://buzz.nutrified.pl/media.

Generating stable secrets

Generate the values once. Never rotate them during a normal image update:

openssl rand -hex 32  # BUZZ_RELAY_PRIVATE_KEY
openssl rand -hex 32  # BUZZ_GIT_HOOK_HMAC_SECRET
openssl rand -base64 36 | tr -d '\n'  # POSTGRES_PASSWORD
openssl rand -base64 36 | tr -d '\n'  # REDIS_PASSWORD

RELAY_OWNER_PUBKEY is the owner's 64-character hexadecimal Nostr public key, not an npub1... value and not a private key.

The S3 access and secret keys are issued by the object-storage provider; do not generate arbitrary values for an external R2 bucket.

Updating Buzz

No GitHub Actions are used. The Compose file tracks ghcr.io/block/buzz:main and sets pull_policy: always.

To update:

1. Open the Buzz application in Coolify.
2. Click Redeploy.
3. Coolify pulls the current official main image and recreates the Buzz container. The persistent volumes and stable secrets remain unchanged.
4. Re-run the liveness/readiness checks and connect once from Buzz Desktop.

For a controlled freeze or rollback, set BUZZ_IMAGE_TAG in Coolify to a known immutable upstream tag such as sha-63496cc, then redeploy. Remove that override to resume tracking main.

Migration to Coolify's official template

Keep this Git-backed deployment until the official Buzz service reaches stable Coolify and includes all three fixes above. There is no operational need to migrate; the wrapper remains small and Buzz itself still comes directly from Block's image.

If you do migrate, back up all three named volumes and the R2 bucket first. Preserve the relay private key, owner public key, HMAC secret, database credentials, Redis credentials, and S3 credentials.