How to Configure Mastodon Instance With Read-Only Maintenance Mode

You need to stop users from posting, editing, or deleting content on your Mastodon instance while keeping the public timeline and profiles accessible. This is called read-only maintenance mode. The mode lets visitors browse existing posts but prevents any write operations such as toots, boosts, follows, or account changes. This article explains how to enable read-only mode on a Mastodon instance using command-line tools and configuration changes.

What Read-Only Maintenance Mode Does on a Mastodon Instance

Read-only maintenance mode prevents any user from performing write operations on the instance. When enabled, the Mastodon API returns a 503 Service Unavailable error for every POST, PUT, PATCH, and DELETE request. This stops new toots, boosts, favorites, follows, account updates, media uploads, and direct messages from being created or modified.

The public timeline, profile pages, and status pages remain fully accessible. Users can view existing content and search public posts. The mode is useful before database migrations, software updates, or file system maintenance that requires a stable data state.

Mastodon provides two built-in commands through the tootctl utility: maintenance mode enable and maintenance mode disable. These commands modify the instance settings in the database and signal the application server to reject write requests.

Prerequisites for using maintenance mode include SSH access to the server, a user account with sudo privileges, and the Mastodon application directory located at /home/mastodon/live by default. The Mastodon services must be running for the tootctl commands to communicate with the database.

Steps to Enable Read-Only Maintenance Mode on Mastodon

Follow these steps exactly in order. Skipping any step may leave the instance in a partially locked state.

1. SSH into your Mastodon server
   Open a terminal and connect to your server using ssh username@your-server-ip. Use the mastodon user account or switch to it with sudo su - mastodon.
2. Navigate to the Mastodon application directory
   Run cd /home/mastodon/live. This is the default installation path. If your instance uses a different directory, adjust the path accordingly.
3. Enable maintenance mode using tootctl
   Run RAILS_ENV=production bin/tootctl maintenance mode enable. The command updates the database setting and returns OK when successful. The mode takes effect immediately for all new API requests.
4. Verify maintenance mode is active
   Run RAILS_ENV=production bin/tootctl maintenance mode status. The output should say Maintenance mode is enabled. You can also test by sending a POST request to your instance API using curl -X POST https://your-instance.example/api/v1/statuses. The response should be a 503 error.
5. Inform users about the maintenance window
   Post an announcement on your instance about page or send a notification via the admin dashboard. Users will see the 503 error if they try to interact, but a proactive message reduces confusion.

After completing the maintenance tasks, run RAILS_ENV=production bin/tootctl maintenance mode disable from the same directory to restore full write access. Verify with the status command again.

Setting Up a Maintenance Page in Nginx

When you stop the Mastodon services entirely for database or file system work, the application server does not respond to any requests. In this case, configure Nginx to serve a static maintenance page for all write endpoints. This provides a friendly message instead of a generic connection refused error.

Create a maintenance HTML file at /usr/share/nginx/html/maintenance.html. The file should explain that the instance is under maintenance and when normal service will resume.

1. Edit the Nginx site configuration file
   Open /etc/nginx/sites-available/mastodon with a text editor as root. Locate the location / block that proxies requests to the Mastodon application server.
2. Add a location block for write endpoints
   Insert the following block inside the server block but before the main location / block:
   location ~ ^/(api|auth|inbox|push|oauth) {
return 503;
error_page 503 /maintenance.html;
}
   This captures all API and authentication paths and returns a 503 status with the custom maintenance page.
3. Test and reload Nginx
   Run nginx -t to check the syntax. If the test passes, run systemctl reload nginx to apply the changes.
4. Stop the Mastodon services
   Run systemctl stop mastodon- to stop all Mastodon processes. The Nginx rules now serve the maintenance page for write requests while static content such as user avatars and CSS files remain accessible.

When maintenance finishes, start the Mastodon services with systemctl start mastodon- and remove the maintenance location block from the Nginx configuration. Reload Nginx to restore normal routing.

Common Mistakes When Configuring Read-Only Maintenance Mode

Maintenance mode enabled but services are stopped

Running the tootctl command while Mastodon services are not running does not set the mode in the database. The command requires a running Sidekiq process to write the setting. Always ensure mastodon-sidekiq and mastodon-web are active before running the enable or disable commands.

Users can still post via third-party clients

Maintenance mode blocks all API write endpoints regardless of the client. If a user can still post, the mode is not enabled. Check the status with RAILS_ENV=production bin/tootctl maintenance mode status. If it shows disabled, re-run the enable command.

Maintenance page does not appear after Nginx configuration

The location block must appear before the main proxy block in the Nginx configuration. If the proxy block matches first, the request never reaches the 503 rule. Place the maintenance location block at the top of the server block.

Maintenance mode persists after disable command

If the disable command fails silently, the database flag remains set. Run the disable command again and verify with the status command. If the issue continues, check the Mastodon logs at /home/mastodon/live/log/production.log for database connection errors.

Item	tootctl Maintenance Mode	Nginx 503 Location Block
Purpose	Blocks write API at application level	Blocks write requests when app server is offline
Requires running services	Yes, Sidekiq and web must be active	No, works with services stopped
User visibility	503 error in client	Custom maintenance HTML page
Static content access	Fully accessible	Fully accessible
Configuration method	Command line tootctl	Nginx configuration file

Read-only maintenance mode for your Mastodon instance is now configured and verified. You can safely perform database schema migrations, software updates, or file system operations without data corruption from concurrent user writes. For future maintenance windows, consider scheduling the mode during low-traffic hours and posting an advance notice on the instance about page. The tootctl status command is the fastest way to confirm the current mode before and after any maintenance session.