How to Set Up a Mastodon Relay for a Niche Community

If you run a Mastodon instance for a niche community such as vintage computer collectors, bird watchers, or indie game developers, your users may feel isolated. The local timeline shows only posts from your instance, and the federated timeline can be overwhelming or irrelevant. A Mastodon relay solves this by automatically pulling in public posts from other instances that share your community’s interests. This article explains what a relay is, how to set one up on your instance, and how to configure it so your niche community stays engaged with relevant content from across the fediverse.

What a Mastodon Relay Does for a Niche Community

A Mastodon relay is a separate server that runs relay software such as Relayator or Pub-Relay. When you subscribe your instance to a relay, your instance sends all its public posts to the relay. The relay then forwards those posts to every other instance subscribed to the same relay. In return, your instance receives public posts from all those other instances. This creates a two-way flow of content without requiring your users to manually follow accounts on each remote instance.

For a niche community, a relay is far more efficient than asking every member to follow dozens of relevant accounts. Instead of the default federated timeline which shows posts from any instance your users have interacted with, the relay ensures that only posts from instances that share your niche topic appear. For example, a relay for “vintage computer enthusiasts” would connect instances focused on retro computing, vintage hardware, and emulation. Posts about unrelated topics such as sports or politics would not appear because those instances are not part of the relay.

Prerequisites Before Setting Up a Relay

Before you set up a relay, confirm that you have full administrative access to your Mastodon instance. You need to be able to modify configuration files and restart Mastodon services. You also need access to a separate server to host the relay software. This server must have a public IP address and a domain name. A small virtual private server with 1 CPU core and 2 GB of RAM is sufficient for most niche communities. The relay server does not need a database; it only needs to run the relay software and have a web server like Nginx or Caddy for TLS termination.

Steps to Set Up a Mastodon Relay for Your Niche Community

Follow these steps to install relay software, configure it, and subscribe your Mastodon instance to the relay. This guide uses Pub-Relay because it is actively maintained and supports Mastodon 4.x.

1. Create a DNS record for the relay server
   On your domain registrar or DNS provider, create an A record that points a subdomain such as relay.yourcommunity.org to the IP address of your relay server. Wait for DNS propagation, which may take a few minutes to a couple of hours.
2. Install Pub-Relay on the relay server
   SSH into the relay server. Install Node.js version 18 or newer using your distribution’s package manager or NodeSource. Clone the Pub-Relay repository: git clone https://github.com/umonaca/pub-relay.git. Change to the directory: cd pub-relay. Run npm install to install dependencies.
3. Configure the relay
   Copy the example configuration: cp config/default.toml config/production.toml. Edit the file with a text editor. Set server_name to your relay subdomain, for example relay.yourcommunity.org. Set allowed_instances to an empty list to allow all instances. If you want to restrict the relay to only specific instances, list their domain names. Set max_connections to 100 or higher depending on expected traffic. Save the file.
4. Start Pub-Relay
   Run NODE_ENV=production node index.js to start the relay. Confirm that it listens on port 8080 by default. Use a process manager like pm2 or systemd to keep the relay running after you log out. For pm2, run npm install -g pm2 and then pm2 start index.js --name pub-relay.
5. Set up TLS with a reverse proxy
   Install Nginx on the relay server. Create a server block that proxies requests from port 443 to localhost:8080. Use Certbot to obtain a free TLS certificate from Let’s Encrypt for your relay subdomain. After setup, test that https://relay.yourcommunity.org returns a JSON response.
6. Subscribe your Mastodon instance to the relay
   Log in to your Mastodon instance as an admin. Go to Preferences > Administration > Relays. Click “Add new relay”. In the field, paste the relay URL: https://relay.yourcommunity.org. Click “Save”. Mastodon will send a subscription request to the relay. After a few seconds, the relay status should show “Enabled”.
7. Verify relay activity
   Open your Mastodon instance’s federated timeline. You should see public posts from other instances that are subscribed to the same relay. If you see no new posts after 10 minutes, check the Mastodon sidekiq logs for errors. Common causes include DNS misconfiguration or firewall rules blocking port 443.

Common Issues When Setting Up a Mastodon Relay

Relay subscription fails with HTTP 400 or 500 errors

This usually happens when the relay server is not reachable from the Mastodon instance. Verify that the relay subdomain resolves to the correct IP address. Check that Nginx is running and that port 443 is open on the relay server’s firewall. On the Mastodon instance, run curl -I https://relay.yourcommunity.org to test connectivity. If the response includes a 200 status, the issue is likely in the Pub-Relay configuration. Double-check the server_name value in production.toml; it must match the relay subdomain exactly.

Posts from the relay do not appear in the federated timeline

If the relay subscription shows “Enabled” but no new posts appear, the relay may not have any other subscribed instances. A relay only distributes posts when at least two instances are subscribed. Ask another instance admin in your niche community to subscribe to the same relay. Alternatively, check the relay’s log file for errors. On the relay server, run pm2 logs pub-relay to see real-time output. Look for lines containing “error” or “rejected”.

Relay causes high server load on the Mastodon instance

A relay can increase the number of incoming posts significantly. If your instance runs on a small server, it may struggle. Limit the relay to only relevant instances by setting allowed_instances in the Pub-Relay configuration. You can also reduce the relay’s max_connections to 50. On the Mastodon side, increase the sidekiq concurrency settings in .env.production if you have CPU headroom. Monitor server load with htop and adjust as needed.

Item	Self-Hosted Relay (Pub-Relay)	Third-Party Relay Service
Description	You run the relay software on your own server	You subscribe to a relay operated by someone else
Control	Full control over which instances are allowed	Limited to the relay operator’s rules
Cost	Server rental fee, typically $5–$10 per month	Usually free
Privacy	All post data stays on your relay server	Posts pass through an external server
Setup effort	Medium: requires server administration skills	Low: just paste a subscription URL
Best for	Niche communities that need strict topic control	General communities that want quick federation

After setting up the relay, your niche community will see a steady stream of relevant posts from other instances. Encourage your members to follow specific remote accounts they discover through the relay. This further strengthens the federation between instances. As a next step, consider creating a public directory of instances that participate in your relay so new members can easily find and join them. One advanced tip: configure the relay to reject media-heavy posts by setting a maximum attachment size in the Pub-Relay configuration, which keeps the relay fast for text-focused communities.