Skip to content

docs(compose): clarify BUZZ_CORS_ORIGINS must match client origin, not BUZZ_DOMAIN - #2908

Open
jefflitt1 wants to merge 1 commit into
block:mainfrom
jefflitt1:docs/clarify-cors-origins-desktop-client
Open

docs(compose): clarify BUZZ_CORS_ORIGINS must match client origin, not BUZZ_DOMAIN#2908
jefflitt1 wants to merge 1 commit into
block:mainfrom
jefflitt1:docs/clarify-cors-origins-desktop-client

Conversation

@jefflitt1

Copy link
Copy Markdown

Summary

  • Self-hosting operators intuitively set BUZZ_CORS_ORIGINS to their relay's own domain, matching the pattern of every other BUZZ_DOMAIN-derived variable in .env.example. That breaks the desktop/mobile client's community-connect flow with a generic browser "Load failed" error — the relay actually responds 200 to GET /api/join-policy, but the browser's CORS check rejects the response because the client's real Origin (tauri://localhost in production, http://localhost:<port> in a dev build) never matches BUZZ_DOMAIN.
  • Hit this during a fresh self-hosted install: relay liveness, NIP-11, the raw WebSocket handshake, and the join-policy endpoint itself all worked fine via curl, but the desktop app failed silently until building from source with devtools enabled surfaced the actual CORS console error.
  • Fixed our own install by leaving BUZZ_CORS_ORIGINS empty (the relay's own supported "permissive" fallback per config.rs), which is safe once BUZZ_REQUIRE_AUTH_TOKEN / BUZZ_REQUIRE_RELAY_MEMBERSHIP already gate real data access.
  • This PR is docs-only: expands the existing .env.example comment and adds a troubleshooting line to deploy/compose/README.md's Production notes, so the next self-hoster doesn't lose the same time we did.

Test plan

  • .env.example comment reviewed for accuracy against crates/buzz-relay/src/config.rs's CORS parsing (comma-separated BUZZ_CORS_ORIGINS, empty → CorsLayer::permissive())
  • No code changes — verified diff is doc-only (.env.example, README.md)

@jefflitt1
jefflitt1 requested a review from a team as a code owner July 25, 2026 23:19
@cameronhotchkies cameronhotchkies added the triage-ready Appropriate for agentic review label Jul 29, 2026
@cameronhotchkies

Copy link
Copy Markdown
Collaborator

🦾 DCO sign-off is failing on this PR. Each commit needs a Signed-off-by trailer matching your GitHub-verified email. See the contributing guide for details. Quick fix: git commit --amend --signoff (single commit) or git rebase --signoff HEAD~N (multiple commits), then force-push.

…t BUZZ_DOMAIN

Self-hosting operators intuitively set BUZZ_CORS_ORIGINS to their relay's own
domain (matching the pattern of every other BUZZ_DOMAIN-derived variable in
this file). That breaks the desktop/mobile client's community-connect flow
with a generic browser "Load failed" error, because the relay actually
responds 200 to GET /api/join-policy but the browser's CORS check rejects it
since the client's real Origin (tauri://localhost in production, or
http://localhost:<port> in a dev build) never matches BUZZ_DOMAIN.

Hit this during a fresh self-hosted install: relay health, NIP-11, the raw
WebSocket handshake, and the join-policy endpoint all worked fine via curl,
but the desktop app failed silently until building from source with devtools
enabled surfaced the actual CORS console error. Left BUZZ_CORS_ORIGINS empty
(the relay's own supported "permissive" fallback) as the fix, which is safe
once BUZZ_REQUIRE_AUTH_TOKEN / BUZZ_REQUIRE_RELAY_MEMBERSHIP already gate real
data access.

Docs-only change: expands the existing .env.example comment and adds a
troubleshooting line to deploy/compose/README.md's Production notes.

Signed-off-by: Jeff Litt <jglittell@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage-ready Appropriate for agentic review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants