Mastodon Relay Aode Setup for Self-Hosting: Walkthrough

If you self-host a Mastodon server, your local timeline may feel empty when your instance is new or small. A Mastodon relay node solves this by automatically sharing public posts among all servers connected to it. This walkthrough covers installing and configuring a relay node on your own Linux server so you can boost content flow for your community. You will learn the exact commands and settings needed to get a relay running and connected to your Mastodon instance.

What a Mastodon Relay Node Does and Why You Need One

A Mastodon relay is a lightweight server that forwards public posts from one connected instance to all other connected instances. When you join a relay, your server sends its local public posts to the relay, and the relay redistributes those posts to every other server in the relay pool. This increases the amount of content visible on your federated timeline without requiring manual follows from your users.

The official Mastodon relay software is called mastodon-relay and is maintained by the Mastodon development team. It is written in Node.js and uses ActivityPub to communicate with Mastodon servers. You do not need a full Mastodon installation to run a relay. The relay only stores post references temporarily and does not host user accounts or media files.

Prerequisites for Self-Hosting a Relay

Before you begin, confirm that your server meets these requirements:

• A Linux server running Ubuntu 20.04 or later, Debian 11, or a compatible distribution.
• Node.js version 16 or higher. You can check with node --version.
• npm package manager version 8 or higher.
• A domain name or subdomain pointed to the server IP address. Example: relay.yourdomain.com.
• Port 80 and 443 open in your firewall. The relay uses HTTPS.
• Reverse proxy software such as Nginx or Caddy to handle TLS certificates.

Steps to Install and Configure a Mastodon Relay Node

Follow these instructions in order. Each step builds on the previous one.

1. Update the server and install Node.js
   Run sudo apt update && sudo apt upgrade -y. Then install Node.js using the NodeSource repository: curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - followed by sudo apt install -y nodejs. Verify with node --version.
2. Clone the mastodon-relay repository
   Move to your home directory: cd ~. Clone the official repository: git clone https://github.com/mastodon/mastodon-relay.git. Then enter the directory: cd mastodon-relay.
3. Install npm dependencies
   Run npm install. This downloads all required packages. The process may take one to two minutes. Do not proceed until the command finishes without errors.
4. Create the configuration file
   Copy the example configuration: cp config.json.example config.json. Open the file with a text editor: nano config.json. Edit the following values:
   
   "domain": "relay.yourdomain.com" — replace with your actual domain
   "port": 3000 — the port the relay listens on internally
   "admin_email": "admin@yourdomain.com" — used for Let’s Encrypt certificate registration
   "registration_mode": "open" — allows any Mastodon admin to join the relay
   Save the file and exit the editor.
5. Set up a reverse proxy with Nginx
   Install Nginx: sudo apt install nginx -y. Create a new site configuration: sudo nano /etc/nginx/sites-available/relay. Add the following content (replace relay.yourdomain.com with your actual domain):

   server {
       listen 80;
       server_name relay.yourdomain.com;
       location / {
           proxy_pass http://127.0.0.1:3000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }

   Enable the site: sudo ln -s /etc/nginx/sites-available/relay /etc/nginx/sites-enabled/. Test the configuration: sudo nginx -t. Reload Nginx: sudo systemctl reload nginx.

6. Obtain a TLS certificate with Certbot
   Install Certbot: sudo apt install certbot python3-certbot-nginx -y. Run Certbot: sudo certbot --nginx -d relay.yourdomain.com. Follow the prompts to enter your admin email and agree to the terms. Certbot automatically configures HTTPS for your relay domain.
7. Create a systemd service for the relay
   Create a service file: sudo nano /etc/systemd/system/mastodon-relay.service. Add the following content (adjust the path if your username differs):

   [Unit]
   Description=Mastodon Relay Service
   After=network.target
   
   [Service]
   Type=simple
   User=yourusername
   WorkingDirectory=/home/yourusername/mastodon-relay
   ExecStart=/usr/bin/node index.js
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target

   Replace yourusername with your actual Linux username. Save the file. Reload systemd: sudo systemctl daemon-reload. Enable the service to start on boot: sudo systemctl enable mastodon-relay. Start the service: sudo systemctl start mastodon-relay. Check its status: sudo systemctl status mastodon-relay. You should see active (running).

8. Connect your Mastodon instance to the relay
   Log in to your Mastodon instance as an admin. Go to Preferences > Administration > Relays. Enter the relay URL: https://relay.yourdomain.com. Click Enable relay. The instance sends a follow request to the relay. The relay automatically accepts and begins forwarding public posts.

Common Relay Setup Problems and How to Solve Them

Relay shows as inactive or unreachable in Mastodon admin panel

Check that the relay service is running: sudo systemctl status mastodon-relay. If it is not running, view the logs: sudo journalctl -u mastodon-relay -n 50. Common causes include a missing config.json file, incorrect domain or port values, or a firewall blocking port 443. Verify that Nginx is listening on the correct domain and that the proxy target matches the port in config.json.

Certificate renewal failure for the relay domain

Certbot renews certificates automatically via a systemd timer. If renewal fails, the relay may become unreachable over HTTPS. Run sudo certbot renew --dry-run to test renewal. Ensure port 80 is open for the ACME challenge. If the domain has changed, reconfigure Certbot with sudo certbot --nginx -d newdomain.com.

Relay consumes too much memory on a small server

The relay stores post references in memory for a limited time. On servers with less than 1 GB of RAM, consider reducing the max_queue_size value in config.json. A value of 1000 instead of the default 5000 reduces memory usage. Restart the relay after changing the value: sudo systemctl restart mastodon-relay.

Mastodon Relay vs Manual Following: Content Distribution Comparison

Item	Mastodon Relay	Manual Following
Setup effort	One-time server configuration	Each user follows accounts individually
Content reach	All public posts from all connected instances	Only posts from followed accounts
Server resource usage	Low to moderate memory and CPU	Minimal for the server; high for users
User control	Admin-controlled; users cannot opt out	Each user controls their own timeline
Reliability	Depends on relay uptime	Depends on remote instance availability

After completing this walkthrough, you have a working Mastodon relay node that distributes public posts among all connected instances. Try connecting a second instance to the same relay to verify cross-instance content flow. For advanced tuning, adjust the max_queue_size and max_connections values in config.json to match your server capacity.