Mastodon Relay Sidekiq Worker Count: How to Right-Size

Running a Mastodon relay requires careful tuning of Sidekiq worker counts. If you set the worker count too high, your server runs out of RAM and the relay becomes unresponsive. If you set it too low, incoming activities queue up and federation delays grow. This article explains how to calculate the correct Sidekiq worker count for your Mastodon relay based on available memory and expected traffic volume. You will learn the memory-per-worker formula, the configuration files to edit, and how to monitor queue health after making changes.

Why Sidekiq Worker Count Matters for a Mastodon Relay

A Mastodon relay receives public posts from many instances and redistributes them to all connected servers. This creates a high volume of incoming activities that must be processed quickly. Sidekiq handles these activities as background jobs. Each Sidekiq worker process consumes about 200 MB of RAM at steady state. If the worker count exceeds available memory, the operating system starts swapping and the relay slows down or crashes.

The default Sidekiq concurrency setting in a standard Mastodon installation is 5 workers per queue. For a single-instance server this is usually fine. For a relay, the default queue and the relay queue can accumulate thousands of jobs per minute. A concurrency of 5 means only 5 jobs run at once. The rest wait in line. Queue latency grows from seconds to minutes, and connected instances notice delays in receiving posts.

Memory Budget Planning

Before changing the worker count, calculate your memory budget. Start with total server RAM in megabytes. Subtract 1024 MB for the operating system, the Mastodon web process, and the PostgreSQL database. The remaining memory is available for Sidekiq workers. Divide that number by 200 to get the maximum safe concurrency per queue.

For example, a server with 4 GB of RAM has 4096 MB total. Subtract 1024 MB leaves 3072 MB. Divide by 200 gives 15 workers. That is the maximum concurrency you should set. Starting with 10 workers is safer and leaves room for memory spikes during peak traffic.

Steps to Configure Sidekiq Worker Count for a Mastodon Relay

The configuration method depends on whether you installed Mastodon from source or use Docker. Both methods achieve the same result. Choose the one that matches your setup.

Method 1: Edit mastodon.yml for Source Installations

1. Open the Mastodon configuration file
   Run sudo nano /etc/mastodon/mastodon.yml. If the file does not exist, check /home/mastodon/live/.env.production.
2. Locate or add the Sidekiq concurrency setting
   Find the line concurrency: under the sidekiq: section. If it does not exist, add these lines at the end of the file:
   sidekiq:
concurrency: 10
3. Save the file and restart Sidekiq
   Press Ctrl+O then Ctrl+X to save and exit. Restart the Sidekiq service with sudo systemctl restart mastodon-sidekiq.
4. Verify the new worker count
   Run sudo systemctl status mastodon-sidekiq and look for the line containing concurrency in the process arguments. It should show the new number.

Method 2: Set Environment Variable for Docker Installations

1. Open your Docker Compose file
   Run sudo nano /opt/mastodon/docker-compose.yml or the path where you store your compose file.
2. Add the SIDEKIQ_CONCURRENCY environment variable
   Find the sidekiq service definition. Under the environment: section add:
   - SIDEKIQ_CONCURRENCY=10
3. Recreate the Sidekiq container
   Run sudo docker compose up -d sidekiq from the directory containing the compose file. This restarts the container with the new concurrency.
4. Confirm the change
   Run sudo docker compose logs sidekiq | grep concurrency. The output should show the new concurrency value.

Common Sidekiq Tuning Mistakes and How to Avoid Them

Setting Concurrency Higher Than Available Memory

If you set concurrency to 25 on a 4 GB server, the system runs out of RAM. The kernel kills the Sidekiq process or starts heavy swapping. Monitor memory usage with htop or free -m after changing the count. If memory usage exceeds 90 percent, reduce the concurrency by 2 and test again.

Ignoring Queue-Specific Worker Limits

Mastodon runs multiple Sidekiq queues: default, push, mailers, pull, and relay. The concurrency setting applies to all queues equally. If the relay queue alone is saturated, consider running a separate Sidekiq process dedicated to the relay queue. In mastodon.yml add a new sidekiq process with queues: [relay] and its own concurrency. This prevents relay jobs from blocking email delivery or push notifications.

Not Monitoring Queue Latency After Changes

Changing the worker count without checking queue latency can hide problems. Go to the Mastodon admin interface at https://your-relay-domain/admin/sidekiq/queues. Look at the latency column for the default and relay queues. If latency stays above 30 seconds after 10 minutes, increase concurrency by 2 more workers. If latency is zero but CPU usage is below 50 percent, you can reduce concurrency slightly to save memory.

Sidekiq Worker Count Comparison: Small Relay vs Large Relay

Item	Small Relay (2-4 GB RAM)	Large Relay (8-16 GB RAM)
Recommended concurrency	5 to 10	15 to 30
RAM reserved for OS and web	1024 MB	2048 MB
RAM per worker estimate	200 MB	200 MB
Typical queue latency target	Under 30 seconds	Under 10 seconds
Sidekiq processes	1 shared process	2 processes: one for default+push, one for relay

Right-sizing Sidekiq workers for your Mastodon relay keeps federation fast and server resources stable. Start with the memory formula to find a safe maximum concurrency. Apply the change through mastodon.yml or the Docker environment variable. Monitor queue latency and memory usage after the change and adjust in small increments. For a high-traffic relay, consider splitting the relay queue into its own Sidekiq process to prevent bottlenecks in other queues. This approach gives you a reliable relay that handles high volumes without crashing.