Nostrfi
/Docs
Browse documentation
Owner: NostrfiLast reviewed: 2026-11-16

Quickstart

releasedPublicly available

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.

Read the current limitations before you put real users on your relay.

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/amd64 only. 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 an npub, decode it with a NIP-19 tool, such as nak 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.
  • git and openssl.

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.

The file ships with an example pubkey. If you leave it in place, the relay runs normally, but you will not be able to sign in to the dashboard or moderate the relay.

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_FILE adds the TLS overlay, which puts Caddy in front of the relay and the dashboard. Every docker compose command below then uses both files.
  • RELAY_VERSION and DASHBOARD_VERSION pin the published images to this release instead of latest.
  • NUXT_SESSION_PASSWORD seals 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:

ContainerRole
nostrfi-relayThe relay. It stores events in a Docker volume, relay-db.
nostrfi-relay-dashboardThe admin dashboard, served at /admin.
nostrfi-relay-caddyTLS 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

  1. Open https://localhost:8443/admin in your browser and accept the local certificate (see Trust the local certificate to avoid the warning).
  2. 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 whoami that asks the relay what role your key holds.
  3. 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:

  1. In Caddyfile, replace localhost with your domain and delete the tls internal line. Caddy then obtains and renews a Let's Encrypt certificate.
  2. In docker-compose.tls.yml, change the port mapping 8443:443 to 443:443 and add 80:80 for the certificate challenge.
  3. In .env, add RELAY_URL=wss://your-domain. The TLS overlay passes it to the relay as auth.relay_url, which binds NIP-42 authentication and every operator signature to your relay's address. Without it, the relay expects wss://localhost:8443 and refuses dashboard sign-in and moderation requests signed for your domain.
  4. Run docker compose up -d again.

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.

The v0.3.0 release also attaches a prebuilt 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 Relay

Next

Changelog