How to Run a Self-Hosted Mastodon Relay With ActivityRelay

Running a Mastodon relay helps instances discover public posts from other instances without each user manually searching for remote accounts. A relay acts as a central hub that receives public posts from subscribing instances and redistributes them to all other subscribers. This guide explains how to set up your own relay using the ActivityRelay software on a Linux server. You will learn the installation steps, configuration, and how to connect your Mastodon instance to the relay.

What a Mastodon Relay Does and Why You Might Want One

A Mastodon relay is a service that collects public posts from all subscribed instances and forwards them to every other subscriber. Without a relay, an instance only sees public posts from instances that its users explicitly follow. This can make the federated timeline feel empty for small or new instances.

ActivityRelay is an open-source relay implementation written in Ruby. It uses the same ActivityPub protocol that Mastodon uses. The relay itself does not store posts permanently. It only passes them along in real time. This means the relay server can be relatively lightweight as long as it has enough bandwidth to handle the traffic from all subscribers.

How the Relay Improves Federation

When your instance subscribes to a relay, the relay sends your instance every public post it receives from other subscribers. In return, your instance sends its public posts to the relay. This creates a bidirectional flow of content. The result is that your federated timeline fills with posts from many instances, not just the ones your users follow manually.

Prerequisites for Self-Hosting a Relay

You need a Linux server running Ubuntu 20.04 or later, or Debian 11 or later. The server must have at least 2 GB of RAM and a public IP address with ports 80 and 443 open. You also need a domain name pointed to the server. Mastodon itself does not need to be installed on the relay server. The relay runs as an independent service.

Installing ActivityRelay with Docker

The easiest way to run ActivityRelay is with Docker and Docker Compose. This method packages the relay and its dependencies into containers. You avoid installing Ruby, PostgreSQL, and Redis directly on the host system.

1. Install Docker and Docker Compose
   Run the official Docker installation script for Ubuntu or Debian. After installation, verify with docker --version and docker compose version.
2. Clone the ActivityRelay repository
   Run git clone https://github.com/breunigs/activityrelay.git and change into the directory with cd activityrelay.
3. Create the environment file
   Copy .env.production.sample to .env. Edit the file and set LOCAL_DOMAIN to your relay domain. Set SECRET_KEY_BASE to a long random string generated with openssl rand -hex 64. Set POSTGRES_PASSWORD and REDIS_PASSWORD to secure values.
4. Start the containers
   Run docker compose up -d. This starts PostgreSQL, Redis, and the relay web service. Wait about 30 seconds for the database to initialize.
5. Run the database migration
   Run docker compose exec web bundle exec rails db:migrate. This creates the tables needed by the relay.
6. Set up a reverse proxy with Nginx or Caddy
   Point your domain to the server and proxy requests to http://localhost:3000. Use Let’s Encrypt for TLS. The relay requires HTTPS to function.
7. Verify the relay is running
   Visit https://your-relay-domain/.well-known/nodeinfo in a browser. You should see a JSON response with relay metadata.

Configuring the Relay for Public or Private Use

ActivityRelay supports two modes: open and closed. In open mode, any Mastodon instance can subscribe without approval. In closed mode, you must manually approve each subscription request. You control this through the environment variable OPEN_REGISTRATION in the .env file.

1. Set OPEN_REGISTRATION to true for open mode
   Open .env and add or edit the line OPEN_REGISTRATION=true. Restart the containers with docker compose restart.
2. Set OPEN_REGISTRATION to false for closed mode
   Change the value to false. In this mode, you must approve subscriptions via the relay’s admin interface. Access the admin panel at https://your-relay-domain/admin. Log in with the credentials you set in .env.
3. Limit the relay to specific instances
   In closed mode, you can block or allow instances manually from the admin panel. This prevents unwanted content from entering your relay.

Connecting a Mastodon Instance to Your Relay

Once your relay is running, Mastodon instance admins can subscribe to it. The process is the same for any Mastodon instance, including your own.

1. Log in as admin on the Mastodon instance
   Go to https://your-instance-domain/admin/settings/relays.
2. Enter the relay URL
   Type https://your-relay-domain in the field and click Add Relay. Mastodon will send a subscription request to the relay.
3. Approve the subscription if using closed mode
   In the relay admin panel, go to the Pending tab and click Approve for the requesting instance.
4. Verify the connection
   Back in Mastodon admin, the relay status should show Enabled. Public posts from other subscribed instances should start appearing in the federated timeline within minutes.

Common Issues When Running a Mastodon Relay

Relay Does Not Forward Posts

If posts are not flowing, check the relay logs with docker compose logs web. Look for errors related to SSL certificate validation. The relay must have a valid TLS certificate. Also verify that the relay domain resolves correctly from the subscribing instance’s server.

Instance Cannot Subscribe to the Relay

The subscribing instance must have outbound HTTPS access to the relay domain. Check that no firewall blocks port 443. Also ensure the relay’s LOCAL_DOMAIN matches the domain in the subscription URL. If the domain does not match, the handshake fails.

Relay Consumes Too Much Bandwidth

A public relay with many subscribers can transfer large amounts of data. Consider limiting the relay to a small group of trusted instances. You can also reduce the relay’s workload by setting MAX_THREADS in .env to a lower number, such as 5. This limits the number of concurrent outbound deliveries.

ActivityRelay vs Other Relay Solutions

Item	ActivityRelay	Manual Peering
Setup complexity	Requires Docker and reverse proxy	No extra software needed
Content distribution	Automatic bidirectional forwarding	Only posts from followed accounts
Server resources	2 GB RAM minimum	None beyond Mastodon itself
Control over subscribers	Open or closed registration	Not applicable

You now have a self-hosted Mastodon relay using ActivityRelay. The relay will automatically distribute public posts among all subscribed instances. Start by subscribing your own instance to the relay and verify that posts appear. For better performance, monitor the relay logs weekly and adjust MAX_THREADS if the server CPU stays above 80 percent.