.env.example: BUZZ_WEB_DIR comment implies it alone serves the web frontend at /, but BUZZ_SERVE_GIT_WEB_GUI is also required
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
## Description
`.env.example` documents `BUZZ_WEB_DIR` like this:
```
# Optional: path to the web UI dist directory. When set, the relay serves
# the web frontend at / for browser requests. Leave unset for local dev
# (use `just web` for Vite HMR instead).
# BUZZ_WEB_DIR=./web/dist
```
This reads as if setting `BUZZ_WEB_DIR` alone is sufficient to serve the web frontend at `/`. In practice it is not: `nip11_or_ws_handler` in [`crates/buzz-relay/src/router.rs`](https://github.com/block/buzz/blob/main/crates/buzz-relay/src/router.rs) only serves `index.html` for `Accept: text/html` requests to `/` when `state.config.serve_git_web_gui` is also `true`:
```rust
Err(_) => {
// Browser requesting HTML and Git web GUI is enabled → serve SPA.
if state.config.serve_git_web_gui {
if let Some(ref dir) = state.config.web_dir {
if accept.contains("text/html") {
let index = dir.join("index.html");
if let Ok(body) = tokio::fs::read(&index).await {
return axum::response::Html(body).into_response();
}
}
}
}
// Not a WS request and not asking for nostr+json — serve NIP-11 as fallback.
Json(nip11_document(&state, raw_host).await).into_response()
}
```
`serve_git_web_gui` is read from `BUZZ_SERVE_GIT_WEB_GUI` in `crates/buzz-relay/src/config.rs` and defaults to `false`. It isn't mentioned anywhere in `.env.example`.
## Impact
A self-hoster who sets `BUZZ_WEB_DIR` (and confirms `index.html` exists on disk, which the relay validates and logs at startup) but doesn't separately know about `BUZZ_SERVE_GIT_WEB_GUI` will find that `/` always returns the NIP-11 JSON relay-info document — identically for both `Accept: text/html` and `Accept: application/nostr+json` — with no indication of why the web client never loads. There's no log line or config validation error pointing at the missing flag.
## Suggested fix
Either:
1. Document `BUZZ_SERVE_GIT_WEB_GUI` next to `BUZZ_WEB_DIR` in `.env.example` and clarify that both are required to serve the web frontend at `/`, or
2. Reconsider gating web-frontend serving behind a flag named `serve_git_web_gui` at all — the name reads as being about the git web GUI specifically, not the primary web client, which made this doubly confusing to debug.
Happy to submit a docs PR for option 1 if that's the preferred direction.
Contributor guide
Research direction
Start with .env.example, then compare the BUZZ_WEB_DIR setting with BUZZ_SERVE_WEB_GUI in crates/buzz-relay/src/config.rs and the handling in crates/buzz-relay/src/router.rs. Update the example so the required configuration is explicit, and verify that a self-hoster can understand how to serve the frontend at /.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 82/100