Repository navigation
Replace the community relay-setup guides with a first-party step-by-step guide on the website #897
Description
Replace the two third-party guides that currently serve as nostream's onboarding path with one guide we own and keep working.
Why
README.md § Full Guide points only at community write-ups:
- "Set up a Paid Nostr relay with Nostream and ZEBEDEE" —
https://docs.zbdpay.com/payments/nostr/nostr-relay. Dead link: 301s tohttps://docs.zbdpay.com/bitcoin/payments/coverage, a generic "Global Support" page with no nostream or relay content. - "Set up a Nostr relay in under 5 minutes" —
https://andreneves.xyz/p/set-up-a-nostr-relay-server-in-under. Still loads (200), but it is a December 2022 Substack post that clones the repo, runspnpm installon the host, writessettings.yamlby hand and fronts it with nginx + certbot. Nothing in it matches today's Compose CLI, the GHCR production image, or thedeploy/bootstrap path.
The website (website/site, deployed to nostream.dev) has no operator guide at all: /get-started is the agent-schematic card and /docs is a set of reference pages (quick start, CLI, configuration, deploy, runbook, Tor/I2P, Redis). Its docs index reads "Every page here is rendered from the repository, so it matches the code" — true for the reference pages, but the only narrative, end-to-end setup path it offers is the README. So both surfaces inherit the same legacy guides.
A reader who wants to stand up a relay without an AI agent currently has no first-party, current, step-by-step path.
What to build
One canonical guide on the website, published under /docs (e.g. /docs/setup), written and reviewed in this repo and rendered from a file in the repo so the "rendered from the repository" claim stays true.
Suggested spine, drawn from deploy/README.md, CLI.md and CONFIGURATION.md — adjust where they disagree:
- What you need — Linux host, Docker Engine + Compose plugin installed from Docker's apt/yum repo (not snap), a domain you control, DNS A/AAAA pointed at the host.
- Get the code —
git cloneandcd nostream; note the release-managed files vs. your.env. - Bootstrap the deploy root —
./deploy/bootstrap.sh /opt/nostream, what it creates,.envpermissions, the generatedSECRET. - Choose the relay image —
ghcr.io/cameri/nostream:<tag>versus a local build, and how pinned tags relate to releases. - Configure
.env—RELAY_URL/ domain, secrets, optional payment processor keys; link toCONFIGURATION.mdrather than duplicating every key. - First start —
docker compose up -d, confirming Postgres and Redis are healthy, migrations ran, and the relay is listening on loopback only. - Put it behind TLS — Caddy or nginx in front (pick one as the primary path), WebSocket upgrade headers, then accept
wss://in a client. - Verify — NIP-11 document over HTTPS,
/healthzand/readyz, publish one event and read it back,nostream info. - Keep it running — updating via
deploy/recreate-relay.sh, backups, log location; link to the deploy runbook and HAProxy page instead of repeating them. - Optional next steps — payments (link to the existing payments section), Tor/I2P page, manual/admin console.
Requirements for the guide:
- Every command must be copy-pasteable and run against the current release. Strip dead or stale commands from the community guides rather than inheriting them.
- State the version it was verified against and how it will be kept current (e.g. reviewed when a release changes
deploy/). - No referral links, no third-party product upsells, no screenshots that go stale.
- Call out what a reader should not do (copy
migrations/to the host, write a fullsettings.yaml, expose the relay port directly) — the traps the old guides taught.
README change: replace the § Full Guide list with a single link to the website guide, plus a one-line "prefer to do it by hand?" pointer to /docs. Keep the in-repo quick starts in place; they are referenced by website/site docs pages and by CLI.md. The line in § Accepting Payments that says "Complete one of the Quick Start guides in this document" should point at whichever path is canonical.
Website change: /docs index gets the guide as the "Start here" card ahead of the reference pages; /get-started gains a visible "or set it up yourself → /docs/setup" link so the schematic is not the only route on that page.
Out of scope
- Rewriting the third-party guides' authors or crediting them differently (a short "further reading" line may remain).
- Provider-specific guides (AWS is issue Add AWS deployment guide #645; Railway has its own template).
- Changes to the Rust rewrite's docs.
Acceptance criteria
-
https://nostream.dev/docs/setupexists, is linked from/docsand from/get-started, and is built from a tracked file in the repo. - Following the guide on a clean Ubuntu 24.04 VPS reaches a relay answering
wss://with a valid NIP-11 document and a successful event publish/read, with no step that is not in the guide. -
README.md§ Full Guide no longer links a dead URL and points to the verified guide; the ZEBEDEE/ZBD link is gone. - No command in the guide fails against the release named at its top.
-
pnpm --dir website/site build(or the site's build command) passes.
Activity
avantikonde commentedon Oct 22, 2026
Hi @cameri @chappie-daemon ,
I've resolved this issue! The changes:
docs/SETUP.md(verified against v3.6.2 on Ubuntu 24.04 LTS)./docs/setupas the primary "Start here" card and link it from/get-started.README.mdby replacing the dead ZEBEDEE URL and stale 2022 guide with the link tohttps://nostream.dev/docs/setup.pnpm --dir website/site build), linting, and changesets.The commit is ready on my fork branch:
avantikonde/nostream@main...avantikonde:nostream:docs/setup-guide
Since PR creation is currently limited to repository collaborators, could you please either grant collaborator access so I can open the PR, or pull the branch directly from
avantikonde/nostream:docs/setup-guide?Thank you!
chappie-daemon commentedon Oct 29, 2026
Cherry-picked your branch onto current
mainand opened a PR crediting you as the author: #1000The commit is unchanged — you remain the author, I am only the committer. It applied cleanly, and the changeset you included validates as-is (
nostreamminor /nostream-websitepatch), so nothing was added.One thing worth clearing up: opening a PR does not require collaborator access. External fork PRs work on this repository — there are several open from other forks right now. No collaborator access was granted, and none is needed for your next contribution: you can open a PR directly from
avantikonde:docs/setup-guide.Thanks for the careful work on the guide. It checks out against the repo in detail — the
deploy/*paths, the.envkeys againstenv.example, and the bootstrap next-steps all match precisely.avantikonde commentedon Oct 29, 2026
Thanks a lot for opening the PR, the attribution, and clarifying how fork PRs work here! Really appreciate the detailed feedback. Looking forward to picking up the next issue.