Skip to content

Replace the community relay-setup guides with a first-party step-by-step guide on the website #897

Open

Description

@chappie-daemon

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 to https://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, runs pnpm install on the host, writes settings.yaml by hand and fronts it with nginx + certbot. Nothing in it matches today's Compose CLI, the GHCR production image, or the deploy/ 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:

  1. 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.
  2. Get the code — git clone and cd nostream; note the release-managed files vs. your .env.
  3. Bootstrap the deploy root — ./deploy/bootstrap.sh /opt/nostream, what it creates, .env permissions, the generated SECRET.
  4. Choose the relay image — ghcr.io/cameri/nostream:<tag> versus a local build, and how pinned tags relate to releases.
  5. Configure .env — RELAY_URL / domain, secrets, optional payment processor keys; link to CONFIGURATION.md rather than duplicating every key.
  6. First start — docker compose up -d, confirming Postgres and Redis are healthy, migrations ran, and the relay is listening on loopback only.
  7. Put it behind TLS — Caddy or nginx in front (pick one as the primary path), WebSocket upgrade headers, then accept wss:// in a client.
  8. Verify — NIP-11 document over HTTPS, /healthz and /readyz, publish one event and read it back, nostream info.
  9. Keep it running — updating via deploy/recreate-relay.sh, backups, log location; link to the deploy runbook and HAProxy page instead of repeating them.
  10. 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 full settings.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/setup exists, is linked from /docs and 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

  1. avantikonde commented on Oct 22, 2026

    @avantikonde

    Hi @cameri @chappie-daemon ,

    I've resolved this issue! The changes:

    • Add a first-party, copy-pasteable production setup guide at docs/SETUP.md (verified against v3.6.2 on Ubuntu 24.04 LTS).
    • Expose the guide on the website under /docs/setup as the primary "Start here" card and link it from /get-started.
    • Clean up README.md by replacing the dead ZEBEDEE URL and stale 2022 guide with the link to https://nostream.dev/docs/setup.
    • Pass all website build checks (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!

  2. chappie-daemon commented on Oct 29, 2026

    @chappie-daemon
    CollaboratorAuthor

    Cherry-picked your branch onto current main and opened a PR crediting you as the author: #1000

    The commit is unchanged — you remain the author, I am only the committer. It applied cleanly, and the changeset you included validates as-is (nostream minor / nostream-website patch), 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 .env keys against env.example, and the bootstrap next-steps all match precisely.

  3. avantikonde commented on Oct 29, 2026

    @avantikonde

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    WebsitedocumentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions