layout

title

description

tableOfContents

outline

pagination

visible
true

visible

visible
true

visible
true

visible
true

Nostr relay

A nostr relay written in Rust with support for the entire relay protocol and data persistence using SQLite.

What is Nostr?

Nostr is a straightforward and open protocol for global, decentralized, and censorship-resistant social media. It offers numerous advantages for users and is completely free, requiring no ID or third-party verification to begin connecting with like-minded individuals and expanding your community. While nostr is sometimes confused as just another social media platform, it goes beyond that. Explore the resources provided here to discover its significant potential.

This protocol is based on relays. Relays are servers that can be operated by anyone. By opening a persistent connection with the server, clients (or apps) can push and pull events in real-time.

Relays are the central element of the nostr protocol, responsible for storing events received from clients.

Crucially, relays do not communicate with each other. Only the relays you're connected to will receive and store your events. This is a key feature of nostr, emphasizing the lack of communication between relays. Therefore, you should connect to as many relays as you wish to share your data with.

Clients should always provide users the flexibility to connect to multiple relays. Users can also decide whether they want to read, write, or do both with the relays they're connected to. This means I can choose to connect to a specific relay to access content without necessarily sharing my own events there, or vice versa.

You can obtain more info about nostr on these additional resources:

austritch.net
awesome-nostr
use-nostr
Nostr.how
gzuuus slideshow
nostr.com

Requirements

Cloudflare tunnel
Others
- PostgreSQL
- Rustup + Cargo

Preparations

Install dependencies

With user admin, make sure that all necessary software packages are installed

{% code overflow="wrap" %}

sudo apt install build-essential cmake protobuf-compiler pkg-config libssl-dev

{% endcode %}

{% hint style="info" %} If you want to use the default SQLite database backend, go to the Use the default SQLite database backend extra section to install the additional SQLite dependency packages {% endhint %}

Install Rustup + Cargo

Check if you already have Rustup installed

rustc --version

Example of expected output:

> rustc 1.71.0 (8ede3aae2 2023-07-12)

Also Cargo

cargo -V

Example of expected output:

> cargo 1.71.0 (cfd3bbd8f 2023-06-08)

{% hint style="info" %} If you obtain "command not found" output, you need to follow the Rustup + Cargo bonus guide to install it and then come back to continue with the guide {% endhint %}

Install PostgreSQL

{% hint style="info" %} Skip this step if you want to use the SQLite database, go directly to the next section {% endhint %}

Check if you already have PostgreSQL installed

psql -V

Example of expected output:

> psql (PostgreSQL) 15.3 (Ubuntu 15.3-1.pgdg22.04+1)

{% hint style="info" %} If you obtain "command not found" outputs, you need to follow the PostgreSQL bonus guide to install it and then come back to continue with the guide {% endhint %}

Create PostgreSQL database

With user admin, create a new database with the postgres user and assign as the owner to the admin user

{% code overflow="wrap" %}

sudo -u postgres createdb -O admin nostrelay

{% endcode %}

Installation

With user admin, go to the temporary folder

cd /tmp

Clone the source code directly from the GitHub repository, and then build a release version of the relay and go to the nostr-rs-relay folder

git clone https://github.com/scsibug/nostr-rs-relay.git && cd nostr-rs-relay

Build a release version of the relay

cargo build --release

Example of expected output ⬇️

    Updating crates.io index
  Downloaded pathdiff v0.2.1
  Downloaded num_cpus v1.16.0
  Downloaded indexmap v2.0.0
  Downloaded parking_lot_core v0.9.8
  Downloaded want v0.3.1
  Downloaded pest v2.7.2
  Downloaded percent-encoding v2.3.0
  Downloaded parse_duration v2.1.1
  Downloaded prost-build v0.11.9
  Downloaded clap_lex v0.5.0
  Downloaded autocfg v0.1.8
  Downloaded fastrand v2.0.0
  Downloaded is-terminal v0.4.9
  Downloaded json5 v0.4.1
  Downloaded num v0.2.1
  Downloaded paste v1.0.14
  Downloaded pin-project-internal v1.1.3
  Downloaded num-iter v0.1.43
  Downloaded fallible-streaming-iterator v0.1.9
  Downloaded md-5 v0.10.5
  Downloaded linked-hash-map v0.5.6
  Downloaded number_prefix v0.4.0
  Downloaded itoa v1.0.9
  Downloaded openssl-sys v0.9.91
  Downloaded async-lock v2.7.0
  Downloaded pest_derive v2.7.2
  Downloaded async-channel v1.9.0
  Downloaded tokio-io-timeout v1.2.0
  Downloaded async-global-executor v2.3.1
  Downloaded sync_wrapper v0.1.2
  Downloaded matchers v0.1.0
  Downloaded no-std-compat v0.4.1
  Downloaded block-padding v0.3.3
  Downloaded pest_generator v2.7.2
  Downloaded atomic-waker v1.1.1
  Downloaded pin-project-lite v0.2.12
  [...]

{% hint style="info" %} If the prompt shows you this error:

error: rustup could not choose a version of cargo to run, because one wasn't specified explicitly, and no default is configured. help: run 'rustup default stable' to download the latest stable release of Rust and set it as your default toolchain.

You need to type rustup default stable and wait for the process to finish, then try again the command before {% endhint %}

Install it

sudo install -m 0755 -o root -g root -t /usr/local/bin /tmp/nostr-rs-relay/target/release/nostr-rs-relay

Check the correct installation

nostr-rs-relay -V

Example of expected output:

> nostr-rs-relay 0.8.9

{% hint style="info" %} If you come to update this is the final step, continue with the indications of the Upgrade section {% endhint %}

Create the nostr user

Create the user nostr with this command

sudo adduser --gecos "" --disabled-password nostr

Expected output:

Adding user `nostr' ...
Adding new group `nostr' (1007) ...
Adding new user `nostr' (1007) with group `nostr' ...
Creating home directory `/home/nostr' ...
Copying files from `/etc/skel' ...

Change to the home nostr user folder

sudo su - nostr

(Optional) If you want to use the MiniBolt favicon.ico file, download it by entering this command, if not, download your own or skip this step to not provide any (remember to leave thefavicon.icocommented on the configuration file)

{% code overflow="wrap" %}

wget https://raw.githubusercontent.com/minibolt-guide/minibolt/main/resources/favicon.ico

{% endcode %}

Create the rs-relay folder

mkdir rs-relay

Exit to the admin user

exit

Configuration

Copy-paste the configuration file template to the before-created folder

sudo cp /tmp/nostr-rs-relay/config.toml /home/nostr/rs-relay/

Assign the owner of the file to the nostr user

sudo chown nostr:nostr /home/nostr/rs-relay/config.toml

(Optional) Delete the nostr-rs-relay folder to be ready for the next update

sudo rm -r /tmp/nostr-rs-relay

Edit the config file, uncomment, and replace the needed information on the next parameters. Save and exit

sudo nano /home/nostr/rs-relay/config.toml

Customize this with your own info (*):

(*) Click on parameter to get an example/explanation

relay_url = "<yourelayurl>"¹

name = "<nametotherelay>"²

description = "<descriptionrelay>"³

pubkey = "<yournostrhexpubkey>"⁴

contact = "<yourcontact>"⁵

relay_icon = "<yourelayiconURL>"⁶

{% hint style="info" %} If you don't have pubkey generated yet, you can follow the Create your nostr key pair section and then continue with this

You can use this tool to convert your "npub" pubkey to hexadecimal format {% endhint %}

{% hint style="info" %} If you want to use the default SQLite database backend, pay attention to not including the next lines (not uncomment):

engine = "postgres"

connection = "postgresql://admin:admin@localhost:5432/nostrelay"

Uncomment and replace only the next line:

data_directory = "/data/nostr/rs-relay/db"

-> More details and additional steps on the exclusive extra section {% endhint %}

Required same as next (*):

(*) click on the parameter to get action to do (<Edit> or <Uncomment>)

favicon = "favicon.ico"⁷

engine = "postgres"⁸

connection = "postgresql://admin:admin@localhost:5432/nostrelay"⁹

address = "127.0.0.1"¹⁰

port = 8880¹¹

remote_ip_header = "cf-connecting-ip"¹²

{% hint style="info" %} If you want, use the same favicon.ico file downloaded before (the relay's icon of MiniBolt) and the value relay_icon parameter (URL -> https://twofaktor.github.io/logo_circle%2BB.png), or replace it with your own info {% endhint %}

Create systemd service

The system needs to run the nostr relay daemon automatically in the background, even when nobody is logged in. We use systemd, a daemon that controls the startup process using configuration files.

As user admin, create the service file

sudo nano /etc/systemd/system/nostr-relay.service

Paste the following configuration. Save and exit

# MiniBolt: systemd unit for nostr relay
# /etc/systemd/system/nostr-relay.service

[Unit]
Description=Nostr relay
Requires=network-online.target postgresql.service
After=network-online.target postgresql.service

[Service]
WorkingDirectory=/home/nostr
ExecStart=/usr/local/bin/nostr-rs-relay -c /home/nostr/rs-relay/config.toml
Environment=RUST_LOG=info,nostr_rs_relay=info

User=nostr
Group=nostr

# Process management
####################
Type=simple
TimeoutStopSec=10
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable autoboot (optional)

sudo systemctl enable nostr-relay

Prepare “nostr-relay” monitoring by the systemd journal and check the logging output. You can exit monitoring at any time with Ctrl-C

journalctl -fu nostr-relay

Run

To keep an eye on the software movements, start your SSH program (eg. PuTTY) a second time, connect to the MiniBolt node, and log in as admin

Start the nostr relay

sudo systemctl start nostr-relay

Example of expected output on the first terminal with journalctl -fu nostr-relay ⬇️

Jun 07 10:49:45 minibolt systemd[1]: Started Nostr relay.
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.130712Z  INFO nostr_rs_relay: Starting up from main
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.150378Z  INFO nostr_rs_relay::server: listening on: 127.0.0.1:8880
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.302830Z  INFO sqlx::postgres::notice: relation "migrations" already exists, skipping
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.337047Z  INFO nostr_rs_relay::db: Postgres migration completed, at v5
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.337902Z  INFO nostr_rs_relay::server: db writer created
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.337945Z  INFO nostr_rs_relay::server: control message listener started
Jun 07 10:49:45 minibolt nostr-rs-relay[2604788]: 2024-06-07T10:49:45.338012Z  INFO nostr_rs_relay::server: reading favicon...
[...]

Ensure the service is working and listening at the default 8880 port

sudo ss -tulpn | grep LISTEN | grep nostr-rs-relay

Expected output:

> tcp   LISTEN 0   128   127.0.0.1:8880   0.0.0.0:*  users:(("nostr-rs-relay",pid=138820,fd=24))

Cloudflare tunnel

Follow the Cloudflare Tunnel bonus guide, when you arrive at the Configuration file section, add the next # Nostr relay lines to ingress the related ingress rule

nano /home/admin/.cloudflared/config.yml

# MiniBolt: cloudflared configuration
# /home/admin/.cloudflared/config.yml

tunnel: <UUID>
credentials-file: /home/admin/.cloudflared/<UUID>.json

ingress:

# Nostr relay
  - hostname: relay.<domain.com>
    service: ws://localhost:8880

  - service: http_status:404

{% hint style="warning" %} Remember to keep - service: http_status:404 line at the end of the file {% endhint %}

Restart the Cloudflared service

sudo systemctl restart cloudflared

Check the Cloudflared logs to ensure all is still OK

journalctl -fu cloudflared

Check relay connection

-> 3 different methods ⬇️

{% tabs %} {% tab title="Method 1" %}

Go to the nostr.watch website to check and test the relay connection
Access to the URL, replacing <relay.domain.com> with your Nostr relay URL: https://nostr.watch/relay/relay.domain.com, example: https://nostr.watch/relay/relay.damus.io

Expected output:

{% endtab %}

{% tab title="Method 2" %} Go to the websocketking.com website, type in the WebSocket URL box your Nostr relay URL e.g. wss://relay.domain.com, and click on the [Connect] button

Example of expected output:

{% endtab %}

{% tab title="Method 3" %} Go to the https://nostrdebug.com/relay website, type in the box your Nostr relay URL e.g. wss://relay.domain.com, and click on the [Connect] button. You should see the status "✅ Connected" on the history

{% endtab %} {% endtabs %}

Extras (optional)

Use the default SQLite database backend

With user admin, install the next additional dependencies

{% code overflow="wrap" %}

sudo apt install sqlite3 libsqlite3-dev

{% endcode %}

Create the rs-relay and db folder

mkdir -p /data/nostr/rs-relay/db

Assign as the owner to the nostr user

sudo chown -R nostr:nostr /data/nostr

Edit the config file

sudo nano /data/nostr/rs-relay/config.toml

Uncomment, and replace the needed information on the next parameters. Save and exit

data_directory = "/data/nostr/rs-relay/db"

{% hint style="info" %} Ignore the next lines related to the PostgreSQL (not uncomment or edit):

engine = "postgres"

connection = "postgresql://admin:admin@localhost:5432/nostrelay"

{% endhint %}

Delete postgres.service of the systemd service lines

Requires=network-online.target
After=network-online.target

{% hint style="info" %} Continue with the guide, the rest of the steps are the same as PostgreSQL use {% endhint %}

Create your nostr key pair

Download and install the Alby Browser extension:
- For Firefox-based browser:
  - Mozilla Firefox
  - Librewolf
  - Tor browser <- Follow this guide to enable the Alby extension using the Tor browser
- For Chromium based-browser:
  - Chrome
  - Brave
After installation, the browser automatically redirects you to choose the password to unlock Alby. Click on the [Next] button

{% hint style="warning" %} Select a strong password for the Alby extension (this password is for encrypting your future Nostr private key and possible funds of the integrated LN wallet) {% endhint %}

Select [Connect with Alby]

Login with your existing account or create a new one

If you selected to create a new one, you need to provide a valid email

If you selected to log in, you need to provide the email and password or select a one-time login code method that you chose

Click on [Start buzzin' with Alby]. Pin the Alby extension to the browser toolbar, if you want

On the Alby dashboard, select the [Nostr section]

Select to create a new one nostr key pairs or import an existing one if you have

If you selected to create a new one, remember to backup the seed shown on the screen, check the verification box, and click on the [Save Master Key] box

{% hint style="info" %} You will see the nostr public & private keys in the property section: {% endhint %}

{% hint style="info" %} Click on the [Nostr Settings] box to obtain your private key and backup on your password manager app, you will need it for mobile clients (e.g. Amethyst) where you will need to enter manually. Example: {% endhint %}

If you selected Import a Nostr account, you can import using the Nostr private key or Recovery phrase

If you selected the Nostr private key, fill in the "Nostr Private key" box with your private key, it will derivate you the "Nostr Public Key", check if correct

{% hint style="info" %} If you see this banner when you enter the "Nostr Settings" section, this means that you should backup carefully the private key, because the existing seeds that you have are not compatible with Alby only the private key {% endhint %}

If you selected the Recovery phrase, fill in the 12-24 words and click on the [Import Master Key] box

{% hint style="info" %} You will see the Nostr Public key in the property section, check if correct: {% endhint %}

{% hint style="info" %} Click on the [Nostr Settings] box to obtain your private key if you don't have yet: {% endhint %}

{% hint style="success" %} Now, you can use Alby to log in to compatible web clients using NIP-07 [Login from extension] {% endhint %}

{% hint style="info" %} If you prefer to generate your key pair, you can mine them using the Rana tool and the Minibolt node.

Be careful when doing this, as it will use all the available resources of the machine and could render other important applications you are running unusable. Gracefully shutdown them before starting this process {% endhint %}

Broadcast the past events to your new relay (optional)

If you want all your past events to be accessible through your new relay, you can back them up by following these instructions:

Go to metadata.nostr.com website, log in [Load My Profile], and click on [Relays]
Add your new Nostr relay [wss://relay.domain.com] address to the list of preferred relays in your profile (in the empty box below), select the read+write option, and click the [Update] button.

You can take the opportunity to add more preferred relays to your profile to also push events to them, selected from this list, or use Nosy to find the top relays of those who follow you or you follow and try to connect to them and don't forget any events of your contact network
Go to nostryfied.amethyst.social webpage and log in [Get from extension] (Alby), or manually enter the [npub...] of your Nostr profile
Click the [Backup & Broadcast] button...

{% hint style="info" %} Please wait patiently until all processes are finished. This might take some time, depending on the number of events you've published on Nostr with that pubkey meaning the interactions you've had on Nostr.

Optionally, you can save a copy of all your events locally as you'll have the download option. {% endhint %}

Nostr clients

{% tabs %} {% tab title="Coracle" %} Coracle is a web client for the Nostr protocol focused on pushing the boundaries of what's unique about Nostr, including relay selection and management, web-of-trust based moderation and content recommendations, and privacy protection.

Web | GitHub {% endtab %}

{% tab title="Snort" %} A nostr UI built with React aiming for speed and efficiency.

Web | Git {% endtab %}

{% tab title="Zap stream" %} Nostr live streaming.

Web | GitHub {% endtab %}

{% tab title="Rana" %} Nostr public key mining tool.

GitHub {% endtab %}

{% tab title="URL Shortener" %} A free URL shortener service enabled by the NOSTR protocol, that is fast and fuss-free, stripped of all bells and whistles, no gimmicks—it just works!

Web | GitHub {% endtab %} {% endtabs %}

{% tabs %} {% tab title="Nostree" %} A Nostr-based application to create, manage, and discover link lists, show notes, and other stuff.

Web | GitHub {% endtab %}

{% tab title="Highlighter" %} Discover and share curated insights by people you trust.

Highlight, share, discover, comment and earn on any text via the nostr network. Books, articles, tweets, anything!

Web {% endtab %}

{% tab title="Pinstr" %} Pinstr is a decentralized, free, and open-source social network built on top of the Nostr Protocol for curating and sharing interests with the world.

Web | GitHub {% endtab %}

{% tab title="Nostr nests" %} Nostr Nests is an audio space for chatting, brainstorming, debating, jamming, micro-conferences, and more.

Web | Git {% endtab %} {% endtabs %}

{% tabs %} {% tab title="Pleb.to" %} Pleb.to does NOSTR things... documents, links, graphs, maps, and more... Pleb.to is a portal to your decentralized data.

Web {% endtab %}

{% tab title="Nostrudel" %} "My half-baked personal nostr client".

Web | GitHub {% endtab %}

{% tab title="Habla.news" %} Habla allows you to read, write, curate and monetize long form content over Nostr, a censorship-resistant protocol for social media that uses long form nostr content.

Web | GitHub {% endtab %}

{% tab title="Amethyst" %} Nostr client for Android.

Amethyst brings the best social network to your Android phone.

GitHub {% endtab %} {% endtabs %}

{% tabs %} {% tab title="Password Manager (Vault)" %} A free, open source, and decentralized password manager, powered by NOSTR.

Chrome-based extension | GitHub {% endtab %}

{% tab title="njump" %} njump is a HTTP Nostr gateway that allows you to browse profiles, notes and relays; it is an easy way to preview a resource and then open it with your preferred client.

Web | GitHub {% endtab %}

{% tab title="exit.pub" %} Tool for migrating your entire past Twitter activity to Nostr.

Web {% endtab %}

{% tab title="Nosy" %} Find the top relays of those who follow you or you follow.

Web {% endtab %} {% endtabs %}

Upgrade

With user admin, stop nostr-rs-relay service

sudo systemctl stop nostr-relay

Follow the complete Installation section
Replace the config.toml file with the new one of the new version (if needed)

{% hint style="warning" %} This step is only necessary if you see changes on the config file template from your current version until the current release (not common), you can display this on this history link. If there are no changes, jump directly to the next "Start nostr-rs-relay service again" >sudo systemctl start nostr-relay {% endhint %}

Backup the config.toml file to keep a copy of your old configuration

sudo cp /data/nostr/rs-relay/config.toml /data/nostr/rs-relay/config.toml.backup

Assign the owner of the backup file to the nostr user

sudo chown nostr:nostr /data/nostr/rs-relay/config.toml.backup

Replace the new config.toml file of the new release

sudo cp /tmp/nostr-rs-relay/config.toml /data/nostr/rs-relay/

Edit the config file and replace it with the same old information as the file you had. Save and exit

sudo nano /data/nostr/rs-relay/config.toml

Start nostr-rs-relay service again

sudo systemctl start nostr-relay

Delete the nostr-rs-relay folder to be ready for the next update

sudo rm -r /tmp/nostr-rs-relay

Uninstall

Uninstall service & user

Ensure you are logged in with the user admin, stop nostr-relay service

sudo systemctl stop nostr-relay

Delete nostr-relay service

sudo rm /etc/systemd/system/nostr-relay.service

Delete the nostr user. Don't worry about userdel: nostr mail spool (/var/mail/nym) not found output, the uninstall has been successful

sudo userdel -rf nostr

Expected output:

> userdel: nostr mail spool (/var/mail/nostr) not found

Delete the nostr relay data folder

sudo rm -r /data/nostr/relay

Uninstall the nostr relay of the Cloudflare tunnel

Staying with user admin, edit config.yml

nano /home/admin/.cloudflared/config.yml

Comment or delete the nostr relay associated ingress rule. Save and exit

# MiniBolt: cloudflared configuration
# /home/admin/.cloudflared/config.yml

tunnel: <UUID>
credentials-file: /home/admin/.cloudflared/<UUID>.json

ingress:

# Nostr relay
#  - hostname: relay.<domain.com>
#    service: ws://localhost:8880

  - service: http_status:404

Restart the Cloudflare tunnel to apply the changes

sudo systemctl restart cloudflared

Uninstall binaries

Staying with user admin, delete the nostr-rs-relay binary of the system

sudo rm /usr/local/bin/nostr-rs-relay

Port reference

Port	Protocol	Use
8880	TCP	Default port

Footnotes

<Edit> ↩
<Edit> ↩
<Edit> ↩
<Uncomment> & <Edit> ↩
<Uncomment> & <Edit> ↩
<Uncomment> & <Edit> with https://twofaktor.github.io/logo_circle%2BB.png if you want ↩
<Uncomment> ↩
<Uncomment> & <Edit> ↩
<Uncomment> & <Edit> ↩
<Edit> ↩
<Edit> ↩
<Uncomment> ↩

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

nostr-relay.md

nostr-relay.md

Nostr relay

What is Nostr?

Requirements

Preparations

Install dependencies

Install Rustup + Cargo

Install PostgreSQL

Create PostgreSQL database

Installation

Create the nostr user

Configuration

Create systemd service

Run

Cloudflare tunnel

Check relay connection

Extras (optional)

Use the default SQLite database backend

Create your nostr key pair

Broadcast the past events to your new relay (optional)

Nostr clients

Upgrade

Uninstall

Uninstall service & user

Uninstall the nostr relay of the Cloudflare tunnel

Uninstall binaries

Port reference

Files

nostr-relay.md

Latest commit

History

nostr-relay.md

File metadata and controls

Nostr relay

What is Nostr?

Requirements

Preparations

Install dependencies

Install Rustup + Cargo

Install PostgreSQL

Create PostgreSQL database

Installation

Create the nostr user

Configuration

Create systemd service

Run

Cloudflare tunnel

Check relay connection

Extras (optional)

Use the default SQLite database backend

Create your nostr key pair

Broadcast the past events to your new relay (optional)

Nostr clients

Upgrade

Uninstall

Uninstall service & user

Uninstall the nostr relay of the Cloudflare tunnel

Uninstall binaries

Port reference

Footnotes