Mastodon Environment Audit Checklist: Queues and Email Delivery

By 4FreeForums Editors · Published October 29, 2026 · Sources linked below

Running a responsive Mastodon instance requires balanced background processing. When federation updates stall, notifications arrive late, or confirmation emails sit unsent, configuration mismatches between environment settings and background workers are often the primary cause. Mastodon delegates intensive operations away from web requests to keep interactions smooth, but unoptimized settings can quickly overwhelm hardware resources. Use this checklist to audit your environment files, streamline Sidekiq queue processing, and maintain reliable mail delivery.

1. Verify Environment File Hierarchy and Execution Modes

Mastodon primarily reads configuration values from a flat dotenv file named .env.production placed within the application directory. However, values defined in that file are not absolute and can be superseded depending on how services launch. According to the Mastodon environment configuration documentation, process-specific definitions take precedence. Systemd unit files can specify overrides using an EnvironmentFile directive or declare variables directly with Environment entries.

When auditing your server configuration, check these foundational environmental constraints:

RAILS_ENV definition: The RAILS_ENV setting determines configuration defaults and must be set to production on live instances. Because this variable is evaluated before dotenv files are parsed, it cannot be defined inside .env.production and must be set via process environments or systemd files.
Service isolation: Ensure that parameters like PORT and SOCKET are set individually per process rather than inside the shared dotenv file, as web processes default to port 3000 while streaming processes listen on port 4000.

2. Match Database Connection Pools to Worker Threads

Background tasks in Mastodon run through Sidekiq, which operates as a single process utilizing multiple threads. The concurrency of this process is not set within an environment variable; instead, administrators define the thread count via the -c command-line argument when executing Sidekiq (such as bundle exec sidekiq -c 15).

Every active worker thread requires a dedicated PostgreSQL connection to process incoming federated posts, outgoing notifications, and account events. You must audit the DB_POOL environment variable to ensure it is set to a number at least equal to the thread count specified in your Sidekiq launch commands. If DB_POOL is configured below the thread allocation, background jobs will stall while waiting for available database handles. To explore broader concurrency tuning across web and worker services, review our Scaling Mastodon Concurrency: Puma, Sidekiq, and PgBouncer Guide.

3. Optimize Disk I/O with RAILS_LOG_LEVEL Adjustments

Background job throughput is heavily influenced by disk input and output speeds. By default, the RAILS_LOG_LEVEL variable is configured to info. Under this setting, Mastodon generates a dedicated log entry for every HTTP request handled and every single background job executed by Sidekiq.

On active servers with high federation traffic, recording every completed background task produces significant log volume that strains storage I/O and drags down worker performance. As detailed in the Mastodon environment configuration documentation, changing RAILS_LOG_LEVEL to warn is recommended when traffic increases. In warn mode, the system outputs details only when issues arise while remaining silent during regular operation. Other valid log levels include debug, error, fatal, and unknown.

4. Audit Sidekiq Queues to Prevent Mail Delivery Bottlenecks

Sidekiq categorizes background work into distinct queues arranged in descending order of priority. Because workers inspect queues sequentially, an overfilled high-priority queue forces subsequent queues to wait. The standard hierarchy includes:

default: Manages operations directly affecting local community members.
push: Handles federation payloads destined for remote instances.
ingress: Ingests incoming remote federation activities.
mailers: Processes and delivers outbound server emails.
pull: Executes lower-priority background tasks, such as account imports, backups, thread resolution, user deletion, and reply forwarding.
scheduler: Runs recurring cron tasks, including trend recalculations and log maintenance.
fasp: Governs interactions with external service integrations.

Because the mailers queue sits fourth in priority, a massive influx of local posts or external federated updates can delay password resets, sign-up verifications, and email notifications. To prevent this, administrators can run separate Sidekiq processes pinned to specific queues using the -q CLI flag (such as bundle exec sidekiq -q default). When splitting processes across systemd services, note that the scheduler queue must never run in more than one process at the same time. For general email infrastructure advice, see our checklist on Forum Email Deliverability: Get Notifications Out of the Spam Folder.

5. Verify Trusted Reverse Proxies and Internal Network Access

Audit network-level environment variables to ensure outbound requests and rate limits function correctly without unintended interruptions:

TRUSTED_PROXY_IP: Mastodon defaults to trusting private address blocks, including 127.0.0.1/8, ::1/128, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and fc00::/7. If you route traffic through an external reverse proxy over a public IP, you must supply its IP addresses in CIDR format. Be aware that assigning custom proxy addresses replaces the default private ranges, requiring localhost entries to be explicitly included if local reverse proxies also operate.
ALLOWED_PRIVATE_ADDRESSES: To defend against server-side request forgery, Mastodon automatically blocks outgoing HTTP calls targeting private subnets such as 127.0.0.1 or 192.168.1.1/16. If your mail relay, object storage, or internal services reside on private local addresses, define them in a comma-separated list under ALLOWED_PRIVATE_ADDRESSES to bypass the default blocks.

Editor's follow-up — 4FreeForums Admin Desk (staff)

When scaling background Sidekiq workers to clear backed-up queues, keep an eye on your database server's connection limits. PostgreSQL defaults to a limit of 100 connections, which can be quickly exhausted if Puma threads, streaming servers, and Sidekiq workers all scale up simultaneously. Server staff with DevOps permissions can monitor current database connection load directly through the PgHero dashboard in the Mastodon administration interface.

If your instance regularly approaches this threshold, install connection pooling tools on Debian or Ubuntu using sudo apt install pgbouncer. Note that if your database user was initially created without a password, you must configure one using ALTER USER mastodon WITH PASSWORD before implementing PgBouncer, as explained in the Mastodon scaling documentation.

Sources

Published October 29, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.