How to Run Your Own Mastodon Relay With Lite-Relay

Mastodon relays help federate content across instances without requiring direct follows. If you run a small or medium-sized instance, manually following accounts to populate timelines is impractical. A relay subscribes to public posts from connected instances and redistributes them to all peers. This article explains how to deploy Lite-Relay, a lightweight relay server, on your own infrastructure.

What Lite-Relay Does and Why You Need It

Lite-Relay is a standalone relay server that implements the Mastodon relay API. When you add a relay to your Mastodon instance, your server sends public posts to the relay. The relay then forwards those posts to all other instances subscribed to the same relay. This process is called relay-based federation.

Running your own relay gives you control over which instances can subscribe. You can whitelist or blacklist domains, monitor traffic, and avoid depending on public relays that may be unreliable or shut down. Lite-Relay is written in Node.js and uses PostgreSQL for storage and Redis for job queues.

The relay does not store posts permanently. It only caches them briefly for redistribution. This keeps resource usage low. A relay handling 50 instances uses roughly 2 GB of RAM and minimal CPU.

Prerequisites for Deploying Lite-Relay

Before you start, ensure you have the following:

• A Linux server with at least 2 GB RAM and 20 GB disk space. Ubuntu 22.04 or Debian 12 is recommended.
• Docker and Docker Compose installed. Version 20.10 or later for Docker, version 2.x for Compose.
• A domain name pointing to your server. Example: relay.yourdomain.com. The relay must run on port 80 or 443.
• SSL certificate. Use Let’s Encrypt with Certbot or a reverse proxy like Nginx with SSL termination.
• Mastodon instance with admin access. You need the ability to add a relay URL in the admin panel.

Steps to Install and Run Lite-Relay

1. Clone the Lite-Relay repository
   Open a terminal on your server. Run git clone https://github.com/kaniini/lite-relay.git. Then change into the directory with cd lite-relay.
2. Create the environment configuration file
   Copy the example file: cp .env.example .env. Open .env in a text editor. Set RELAY_DOMAIN to your relay domain. Set POSTGRES_PASSWORD to a strong random string. Set REDIS_PASSWORD similarly. Optionally set ADMIN_EMAIL for admin notifications. Save the file.
3. Start the relay services with Docker Compose
   Run docker compose up -d. This pulls the necessary images and starts PostgreSQL, Redis, and the Lite-Relay container. Check that all containers are running with docker compose ps.
4. Configure SSL with a reverse proxy
   Install Nginx: sudo apt install nginx. Create a new configuration file at /etc/nginx/sites-available/relay. Set the server_name to your relay domain. Proxy requests to http://127.0.0.1:3000. Obtain an SSL certificate with Certbot: sudo certbot --nginx -d relay.yourdomain.com. Enable the site with sudo ln -s /etc/nginx/sites-available/relay /etc/nginx/sites-enabled/ and reload Nginx: sudo systemctl reload nginx.
5. Test the relay endpoint
   Open a web browser and go to https://relay.yourdomain.com/api/v1/instance. You should see a JSON response with the relay version and contact info. If you see an error, check the logs with docker compose logs.
6. Add the relay to your Mastodon instance
   Log in to your Mastodon admin panel. Navigate to Preferences > Administration > Relays. Click the Add New Relay button. Paste your relay URL: https://relay.yourdomain.com. Click Save and then Enable. Your instance now starts sending public posts to the relay.
7. Invite other instance admins to subscribe
   Share your relay URL with other Mastodon admins. They can add it the same way. The relay begins distributing posts among all subscribed instances within a few minutes.

Managing and Monitoring Your Relay

Lite-Relay includes a basic admin interface. Access it at https://relay.yourdomain.com/admin. Log in using the email and password set in the .env file. From the admin panel you can:

• View a list of subscribed instances and their status.
• Block or unblock instances by domain.
• Monitor relay throughput and recent activity.

To update Lite-Relay, pull the latest code with git pull and restart the containers with docker compose up -d --build. Always back up your .env file and database before updating.

Common Problems and How to Fix Them

Relay returns 404 or 502 errors when accessed

This usually means the reverse proxy is not correctly forwarding to port 3000. Verify your Nginx proxy_pass directive points to http://127.0.0.1:3000. Check that the Lite-Relay container is running with docker compose ps. If the container exited, view logs with docker compose logs relay to see startup errors.

Mastodon instance shows relay as offline

The instance sends a test request to the relay every few minutes. If the relay domain is unreachable, check DNS resolution from the instance server. Also ensure port 443 is open in your firewall. Run sudo ufw status to check. Add a rule with sudo ufw allow 443/tcp if needed.

Relay consumes too much memory

Lite-Relay uses Redis as a job queue. If many instances subscribe, the queue can grow. Reduce the QUEUE_CONCURRENCY value in .env to limit parallel jobs. Restart the relay with docker compose restart. Also consider increasing server RAM to 4 GB if you have more than 100 instances.

Lite-Relay vs Public Relays: Key Differences

Item	Lite-Relay (Self-Hosted)	Public Relays (e.g., relay.fedifriends.com)
Control	Full control over instance whitelisting and blacklisting	No control; relay operator decides policies
Privacy	Posts stay within your trusted network	Posts go to unknown third-party instances
Reliability	Depends on your server uptime	Depends on public relay operator’s uptime
Cost	Server hosting costs (approx $5–$15/month)	Free to use
Setup effort	Requires server administration skills	No setup; just add the URL

Running your own relay gives you independence and privacy. Public relays are easier but offer no guarantees. Choose based on your instance size and trust requirements.

You can now run a Mastodon relay using Lite-Relay. Start by cloning the repository and configuring the .env file. The admin panel lets you manage subscriptions and block unwanted domains. For advanced control, consider setting up a whitelist-only relay. Edit the .env variable RELAY_OPEN_REGISTRATION=false and manually add allowed instances through the admin interface.