grain is a nostr relay built using Go, currently utilizing MongoDB as its database. Binaries are provided for AMD64 Windows and Linux. grain is Go Relay Architecture for Implementing Nostr

Introduction

grain is a nostr relay built using Go, currently utilizing MongoDB as its database. Binaries are provided for AMD64 Windows and Linux. grain is Go Relay Architecture for Implementing Nostr

Prerequisites

• Grain requires a running MongoDB instance. Please refer to this separate guide for instructions on setting up MongoDB: 📰How to Install and Run MongoDB Community Server

Download Grain

Download the latest release for your system from the GitHub releases page

amd64 binaries provided for Windows and Linux, if you have a different CPU architecture, you can download and install go to build grain from source

Installation and Execution

• Create a new folder on your system where you want to run Grain.
• The downloaded binary comes bundled with a ZIP file containing a folder named "app," which holds the frontend HTML files. Unzip the "app" folder into the same directory as the Grain executable.

Run Grain

• Open your terminal or command prompt and navigate to the Grain directory.
• Execute the Grain binary.

on linux you will first have to make the program executable

chmod +x grain_linux_amd64

Then you can run the program

./grain_linux_amd64

(alternatively on windows, you can just double click the grain_windows_amd64.exe to start the relay)

You should see a terminal window displaying the port on which your relay and frontend are running.

If you get

Failed to copy app/static/examples/config.example.yml to config.yml: open app/static/examples/config.example.yml: no such file or directory

Then you probably forgot to put the app folder in the same directory as your executable or you did not unzip the folder.

Congrats! You're running grain 🌾!

You may want to change your NIP11 relay information document (relay_metadata.json) This informs clients of the capabilities, administrative contacts, and various server attributes. It's located in the same directory as your executable.

Configuration Files

Once Grain has been executed for the first time, it will generate the default configuration files inside the directory where the executable is located. These files are:

config.yml
whitelist.yml
blacklist.yml

Prerequisites:

• Grain requires a running MongoDB instance. Please refer to this separate guide for instructions on setting up MongoDB: [Link to MongoDB setup guide].

Download Grain:

Download the latest release for your system from the GitHub releases page

amd64 binaries provided for Windows and Linux, if you have a different CPU architecture, you can download and install go to build grain from source

Installation and Execution:#

• Create a new folder on your system where you want to run Grain.
• The downloaded binary comes bundled with a ZIP file containing a folder named "app," which holds the frontend HTML files. Unzip the "app" folder into the same directory as the Grain executable.

Run Grain:#

• Open your terminal or command prompt and navigate to the Grain directory.
• Execute the Grain binary.

on linux you will first have to make the program executable

chmod +x grain_linux_amd64

Then you can run the program

./grain_linux_amd64

(alternatively on windows, you can just double click the grain_windows_amd64.exe to start the relay)

You should see a terminal window displaying the port on which your relay and frontend are running.

If you get

Failed to copy app/static/examples/config.example.yml to config.yml: open app/static/examples/config.example.yml: no such file or directory

Then you probably forgot to put the app folder in the same directory as your executable or you did not unzip the folder.

Congrats! You're running grain 🌾!

You may want to change your NIP11 relay information document (relay_metadata.json) This informs clients of the capabilities, administrative contacts, and various server attributes. It's located in the same directory as your executable.

Configuration Files:#

Once Grain has been executed for the first time, it will generate the default configuration files inside the directory where the executable is located. These files are:

config.yml
whitelist.yml
blacklist.yml

Configuration Documentation#

You can always find the latest example configs on my site or in the github repo here: config.yml

• whitelist.ymlgithub.com

blacklist.yml

Config.yml#

This config.yml file is where you customize how your Grain relay operates. Each section controls different aspects of the relay's behavior.

1. mongodb (Database Settings)

• uri: mongodb://localhost:27017/:
  • This is the connection string for your MongoDB database.
  • mongodb://localhost:27017/ indicates that your MongoDB server is running on the same computer as your Grain relay (localhost) and listening on port 27017 (the default MongoDB port).
  • If your MongoDB server is on a different machine, you'll need to change localhost to the server's IP address or hostname.
  • The trailing / indicates the root of the mongodb server. You will define the database in the next line.
• database: grain:
  • This specifies the name of the MongoDB database that Grain will use to store Nostr events. Grain will create this database if it doesn't already exist.
  • You can name the database whatever you want. If you want to run multiple grain relays, you can and they can have different databases running on the same mongo server.

2. server (Relay Server Settings)

• port: :8181:
  • This sets the port on which your Grain relay will listen for incoming nostr websocket connections and what port the frontend will be available at.
• read_timeout: 10 # in seconds:
  • This is the maximum time (in seconds) that the relay will wait for a client to send data before closing the connection.
• write_timeout: 10 # in seconds:
  • This is the maximum time (in seconds) that the relay will wait for a client to receive data before closing the connection.
• idle_timeout: 120 # in seconds:
  • This is the maximum time (in seconds) that the relay will keep a connection open if there's no activity.
• max_connections: 100:
  • This sets the maximum number of simultaneous client connections that the relay will allow.
• max_subscriptions_per_client: 10:
  • This sets the maximum amount of subscriptions a single client can request from the relay.

3. resource_limits (System Resource Limits)

• cpu_cores: 2 # Limit the number of CPU cores the application can use:
  • This restricts the number of CPU cores that Grain can use. Useful for controlling resource usage on your server.
• memory_mb: 1024 # Cap the maximum amount of RAM in MB the application can use:
  • This limits the maximum amount of RAM (in megabytes) that Grain can use.
• heap_size_mb: 512 # Set a limit on the Go garbage collector's heap size in MB:
  • This sets a limit on the amount of memory that the Go programming language's garbage collector can use.

4. auth (Authentication Settings)

• enabled: false # Enable or disable AUTH handling:
  • If set to true, this enables authentication handling, requiring clients to authenticate before using the relay.
• relay_url: "wss://relay.example.com/" # Specify the relay URL:
  • If authentication is enabled, this is the url that clients will use to authenticate.

5. UserSync (User Synchronization)

• user_sync: false:
  • If set to true, the relay will attempt to sync user data from other relays.
• disable_at_startup: true:
  • If user sync is enabled, this will prevent the sync from starting when the relay starts.
• initial_sync_relays: [...]:
  • A list of other relays to pull user data from.
• kinds: []:
  • A list of event kinds to pull from the other relays. Leaving this empty will pull all event kinds.
• limit: 100:
  • The limit of events to pull from the other relays.
• exclude_non_whitelisted: true:
  • If set to true, only users on the whitelist will have their data synced.
• interval: 360:
  • The interval in minutes that the relay will resync user data.

6. backup_relay (Backup Relay)

• enabled: false:
  • If set to true, the relay will send copies of received events to the backup relay.
• url: "wss://some-relay.com":
  • The url of the backup relay.

7. event_purge (Event Purging)

• enabled: false:
  • If set to true, the relay will automatically delete old events.
• keep_interval_hours: 24:
  • The number of hours to keep events before purging them.
• purge_interval_minutes: 240:
  • How often (in minutes) the purging process runs.
• purge_by_category: ...:
  • Allows you to specify which categories of events (regular, replaceable, addressable, deprecated) to purge.
• purge_by_kind_enabled: false:
  • If set to true, events will be purged based on the kinds listed below.
• kinds_to_purge: ...:
  • A list of event kinds to purge.
• exclude_whitelisted: true:
  • If set to true, events from whitelisted users will not be purged.

8. event_time_constraints (Event Time Constraints)

• min_created_at: 1577836800:
  • The minimum created_at timestamp (Unix timestamp) that events must have to be accepted by the relay.
• max_created_at_string: now+5m:
  • The maximum created at time that an event can have. This example shows that the max created at time is 5 minutes in the future from the time the event is received.
  • min_created_at_string and max_created_at work the same way.

9. rate_limit (Rate Limiting)

• ws_limit: 100:
  • The maximum number of WebSocket messages per second that the relay will accept.
• ws_burst: 200:
  • Allows a temporary burst of WebSocket messages.
• event_limit: 50:
  • The maximum number of Nostr events per second that the relay will accept.
• event_burst: 100:
  • Allows a temporary burst of Nostr events.
• req_limit: 50:
  • The limit of http requests per second.
• req_burst: 100:
  • The allowed burst of http requests.
• max_event_size: 51200:
  • The maximum size (in bytes) of a Nostr event that the relay will accept.
• kind_size_limits: ...:
  • Allows you to set size limits for specific event kinds.
• category_limits: ...:
  • Allows you to set rate limits for different event categories (ephemeral, addressable, regular, replaceable).
• kind_limits: ...:
  • Allows you to set rate limits for specific event kinds.

By understanding these settings, you can tailor your Grain Nostr relay to meet your specific needs and resource constraints.

whitelist.yml#

The whitelist.yml file is used to control which users, event kinds, and domains are allowed to interact with your Grain relay. Here's a breakdown of the settings:

1. pubkey_whitelist (Public Key Whitelist)

• enabled: false:
  • If set to true, this enables the public key whitelist. Only users whose public keys are listed will be allowed to publish events to your relay.
• pubkeys::
  • A list of hexadecimal public keys that are allowed to publish events.
  • pubkey1 and pubkey2 are placeholders, you will replace these with actual hexadecimal public keys.
• npubs::
  • A list of npubs that are allowed to publish events.
  • npub18ls2km9aklhzw9yzqgjfu0anhz2z83hkeknw7sl22ptu8kfs3rjq54am44 and npub2 are placeholders, replace them with actual npubs.
  • npubs are bech32 encoded public keys.

2. kind_whitelist (Event Kind Whitelist)

• enabled: false:
  • If set to true, this enables the event kind whitelist. Only events with the specified kinds will be allowed.
• kinds::
  • A list of event kinds (as strings) that are allowed.
  • "1" and "2" are example kinds. Replace these with the kinds you want to allow.
  • Example kinds are 0 for metadata, 1 for short text notes, and 2 for recommend server.

3. domain_whitelist (Domain Whitelist)

• enabled: false:
  • If set to true, this enables the domain whitelist. This checks the domains .well-known folder for their nostr.json. This file contains a list of pubkeys. They will be considered whitelisted if on this list.
• domains::
  • A list of domains that are allowed.
  • "example.com" and "anotherdomain.com" are example domains. Replace these with the domains you want to allow.

blacklist.yml#

The blacklist.yml file allows you to block specific content, users, and words from your Grain relay. Here's a breakdown of the settings:

1. enabled: true

• This setting enables the blacklist functionality. If set to true, the relay will actively block content and users based on the rules defined in this file.

2. permanent_ban_words:

• This section lists words that, if found in an event, will result in a permanent ban for the event's author.
• - really bad word is a placeholder. Replace it with any words you want to permanently block.

3. temp_ban_words:

• This section lists words that, if found in an event, will result in a temporary ban for the event's author.
• - crypto, - web3, and - airdrop are examples. Replace them with the words you want to temporarily block.

4. max_temp_bans: 3

• This sets the maximum number of temporary bans a user can receive before they are permanently banned.

5. temp_ban_duration: 3600

• This sets the duration of a temporary ban in seconds. 3600 seconds equals one hour.

6. permanent_blacklist_pubkeys:

• This section lists hexadecimal public keys that are permanently blocked from using the relay.
• - db0c9b8acd6101adb9b281c5321f98f6eebb33c5719d230ed1870997538a9765 is an example. Replace it with the public keys you want to block.

7. permanent_blacklist_npubs:

• This section lists npubs that are permanently blocked from using the relay.
• - npub1x0r5gflnk2mn6h3c70nvnywpy2j46gzqwg6k7uw6fxswyz0md9qqnhshtn is an example. Replace it with the npubs you want to block.
• npubs are the human readable version of public keys.

8. mutelist_authors:

• This section lists hexadecimal public keys of author of a kind1000 mutelist. Pubkey authors on this mutelist will be considered on the permanent blacklist. This provides a nostr native way to handle the backlist of your relay
• - 3fe0ab6cbdb7ee27148202249e3fb3b89423c6f6cda6ef43ea5057c3d93088e4 is an example. Replace it with the public keys of authors that have a mutelist you would like to use as a blacklist. Consider using your own.
• Important Note: The mutelist Event MUST be stored in this relay for it to be retrieved. This means your relay must have a copy of the authors kind10000 mutelist to consider them for the blacklist.

Running Grain as a Service:#

Windows Service:#

To run Grain as a Windows service, you can use tools like NSSM (Non-Sucking Service Manager). NSSM allows you to easily install and manage any application as a Windows service.

* For instructions on how to install NSSM, please refer to this article: [Link to NSSM install guide coming soon].

1. Open Command Prompt as Administrator:

   • Open the Windows Start menu, type "cmd," right-click on "Command Prompt," and select "Run as administrator."

2. Navigate to NSSM Directory:

   • Use the cd command to navigate to the directory where you extracted NSSM. For example, if you extracted it to C:\nssm, you would type cd C:\nssm and press Enter.

3. Install the Grain Service:

   • Run the command nssm install grain.
   • A GUI will appear, allowing you to configure the service.

4. Configure Service Details:

   • In the "Path" field, enter the full path to your Grain executable (e.g., C:\grain\grain_windows_amd64.exe).
   • In the "Startup directory" field, enter the directory where your Grain executable is located (e.g., C:\grain).

5. Install the Service:

   • Click the "Install service" button.

6. Manage the Service:

   • You can now manage the Grain service using the Windows Services manager. Open the Start menu, type "services.msc," and press Enter. You can start, stop, pause, or restart the Grain service from there.

Linux Service (systemd):#

To run Grain as a Linux service, you can use systemd, the standard service manager for most modern Linux distributions.

1. Create a Systemd Service File:

   • Open a text editor with root privileges (e.g., sudo nano /etc/systemd/system/grain.service).

2. Add Service Configuration:

   • Add the following content to the grain.service file, replacing the placeholders with your actual paths and user information:

   [Unit]
   Description=Grain Nostr Relay
   After=network.target
   
   [Service]
   ExecStart=/path/to/grain_linux_amd64
   WorkingDirectory=/path/to/grain/directory
   Restart=always
   User=your_user #replace your_user
   Group=your_group #replace your_group
   
   [Install]
   WantedBy=multi-user.target
   

   • Replace /path/to/grain/executable with the full path to your Grain executable.
   • Replace /path/to/grain/directory with the directory containing your Grain executable.
   • Replace your_user and your_group with the username and group that will run the Grain service.

3. Reload Systemd:

   • Run the command sudo systemctl daemon-reload to reload the systemd configuration.

4. Enable the Service:

   • Run the command sudo systemctl enable grain.service to enable the service to start automatically on boot.

5. Start the Service:

   • Run the command sudo systemctl start grain.service to start the service immediately.

6. Check Service Status:

   • Run the command sudo systemctl status grain.service to check the status of the Grain service. This will show you if the service is running and any recent logs.
   • You can run sudo journalctl -f -u grain.service to watch the logs

More guides are in the works for setting up tailscale to access your relay from anywhere over a private network and for setting up a cloudflare tunnel to your domain to deploy a grain relay accessible on a subdomain of your site eg wss://relay.yourdomain.com