- Docs
- Nostrfi Relay
- Getting Started
- Quickstart
Quickstart
This guide takes you from nothing to a running Nostr relay that you operate: the relay, its admin dashboard, and a TLS reverse proxy, all on one machine. You then sign in to the dashboard with your own Nostr key and connect a client. It takes about ten minutes, most of it spent downloading images.
These steps are written for release v0.3.0.
Before you start
You need:
- A Linux x86-64 machine with Docker Engine and Docker Compose v2. The
published images are built for
linux/amd64only. On ARM hosts, including Apple Silicon, see On ARM hosts. - At least 1 GB of RAM and 1 vCPU for the relay, dashboard, and proxy together. See capacity and sizing.
- Your Nostr public key in hex: 64 characters, not the
npub1…form. If you only have annpub, decode it with a NIP-19 tool, such asnak decode npub1…. - A signer for that key: a NIP-07 browser extension or a NIP-46 remote signer (bunker). The dashboard never asks for your private key.
gitandopenssl.
1. Get the release
git clone --branch v0.3.0 --depth 1 https://github.com/nostrfi/relay.git
cd relay
2. Make yourself the operator
Open backend/config.yaml and set relay_info.pubkey to your hex public key.
Set the name, description, and contact while you are there. They are
published in the relay's NIP-11 information document.
relay_info:
name: "My Relay"
description: "A Nostr relay run by me."
pubkey: "<your 64-character hex pubkey>"
contact: "you@example.com"
This pubkey becomes the relay's owner: the key that can sign in to the
dashboard, use the NIP-86 moderation API, and grant
administrators later.
moderation.admin_pubkey defaults to it.
3. Create the environment file
Create a .env file next to docker-compose.yml:
cat > .env <<EOF
COMPOSE_FILE=docker-compose.yml:docker-compose.tls.yml
RELAY_VERSION=0.3.0
DASHBOARD_VERSION=0.3.0
NUXT_SESSION_PASSWORD=$(openssl rand -base64 48)
EOF
COMPOSE_FILEadds the TLS overlay, which puts Caddy in front of the relay and the dashboard. Everydocker composecommand below then uses both files.RELAY_VERSIONandDASHBOARD_VERSIONpin the published images to this release instead oflatest.NUXT_SESSION_PASSWORDseals the dashboard's session cookie. The dashboard refuses to start a session without it. Keep the file private.
4. Start it
docker compose up -d
docker compose ps
Wait until relay and dashboard report healthy. Three containers run:
| Container | Role |
|---|---|
nostrfi-relay | The relay. It stores events in a Docker volume, relay-db. |
nostrfi-relay-dashboard | The admin dashboard, served at /admin. |
nostrfi-relay-caddy | TLS on port 8443, routing /admin to the dashboard and everything else to the relay. |
Locally, Caddy issues itself a certificate for localhost (tls internal),
so no domain or DNS is needed.
5. Check the relay answers
Ask for the relay's NIP-11 information document:
curl -k -H "Accept: application/nostr+json" https://localhost:8443/
You should get JSON with your relay's name, your pubkey, and the supported
NIPs. -k accepts Caddy's local certificate. To check readiness:
curl -k https://localhost:8443/readyz
6. Sign in to the dashboard
- Open
https://localhost:8443/adminin your browser and accept the local certificate (see Trust the local certificate to avoid the warning). - Choose Sign in, then approve with your browser extension or paste a
bunker URL. Your signer asks twice: once for the dashboard's sign-in
challenge, and once for a
whoamithat asks the relay what role your key holds. - The overview opens, with live connections, subscriptions, stored events, and events by day.
The relay decides who may sign in, so only the pubkey from step 2 can, until
you grant administrators. If sign-in is refused, check that
relay_info.pubkey is your key in hex. After changing it, run
docker compose restart relay dashboard.
See admin dashboard for what each page does.
7. Connect a client
Add wss://localhost:8443 as a relay in a Nostr client on the same machine,
publish a note, and open Events in the dashboard to see it arrive.
Trust the local certificate
Browsers and most clients reject Caddy's local certificate until you trust
it. Either open https://localhost:8443 once and accept the warning, or
export Caddy's root certificate and add it to your system or browser trust
store:
docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt > caddy-local-root.crt
A relay on a real domain gets a publicly trusted certificate instead. See the next section.
Put it on a server
To serve real clients, run the same setup on a server with a domain name pointing at it:
- In
Caddyfile, replacelocalhostwith your domain and delete thetls internalline. Caddy then obtains and renews a Let's Encrypt certificate. - In
docker-compose.tls.yml, change the port mapping8443:443to443:443and add80:80for the certificate challenge. - In
.env, addRELAY_URL=wss://your-domain. The TLS overlay passes it to the relay asauth.relay_url, which binds NIP-42 authentication and every operator signature to your relay's address. Without it, the relay expectswss://localhost:8443and refuses dashboard sign-in and moderation requests signed for your domain. - Run
docker compose up -dagain.
Then work through the production-readiness checklist, set up backups, and decide on your moderation approach.
Stop or remove it
docker compose down # stop; keeps events and certificates
docker compose down -v # stop and delete the event database and certificates
Other ways to run it
On ARM hosts
The published images are linux/amd64 only. The Compose file can also build
both images from the checked-out source. Leave RELAY_VERSION and
DASHBOARD_VERSION out of .env, then run docker compose up -d --build.
This path has not yet been tested on ARM.
The relay alone, from source
To run only the relay, without the dashboard or TLS, you need Go 1.25 or newer and a C compiler, because the DuckDB driver uses cgo:
cd backend
go run ./cmd/relay
It reads backend/config.yaml, stores events in backend/db/relay.db, and
listens on ws://localhost:8080. See
development operation.
relay-linux-amd64 binary. It
needs glibc 2.36 or newer, so it runs on Debian 12, Ubuntu 24.04, and later
distributions. On older distributions, use the container images or build
from source instead.Next steps
Previous
Nostrfi RelayNext
Changelog