Introduction
If you’re running a Mastodon instance, whether on a server, a personal NAS, or in a containerized environment like Docker, one of the most common issues you may encounter is the rapid accumulation of data. As your instance grows, storage usage can quickly spiral out of control, especially if you don’t regularly clean up unnecessary data.
Mastodon stores a variety of data: statuses, media files, headers (which include metadata about people you follow), preview cards, and even unused media. Over time, this data can take up significant space, potentially slowing down your instance and eating into your storage resources. However, you can automate the process of cleaning up old data to keep your Mastodon instance efficient and your storage usage in check.
In this guide, I’ll show you how to automate the cleanup of various types of data in Mastodon, including statuses, media files, and headers. I’ll also explain how you can use Synology’s Task Scheduler to run these cleanup tasks automatically at regular intervals.
Why Cleanup Is Essential for Your Mastodon Instance
Mastodon generates a lot of data. While much of it is important for keeping your instance running smoothly, not all of it is necessary in the long term. Regular cleanup helps you avoid:
Excessive storage usage: As old posts, media, and metadata accumulate, they can fill up your disk and cause performance issues.
Slower performance: Large amounts of unnecessary data can slow down your Mastodon instance, particularly if your instance is running on limited hardware.
Security concerns: Old data can sometimes lead to potential security issues, especially when dealing with orphaned accounts or unused media files.
By regularly cleaning up old and unused data, you can keep your Mastodon instance lean, fast, and responsive.
What Can Be Cleaned Up?
Here’s a quick overview of the key data types that can be cleaned up to save space and improve performance:
Orphaned Accounts: Accounts that have never interacted with your local users can be removed to free up space.
Old Statuses: Posts that haven’t been interacted with for a certain period (e.g., 7 days) can be deleted.
Old Media Files: Media attachments (images, videos, etc.) older than a certain period (e.g., 7 days) can be cleaned up.
Headers: Metadata related to users you follow, which can be removed after a period (e.g., immediately for unfollowed users, or after 7 days for followed users).
Unused Preview Cards: Link previews (metadata for URLs) that are older than a certain number of days can be deleted.
Orphaned Media Files: Any media files that are not linked to posts (or have been orphaned) can be removed to save space.
The Cleanup Script
Here’s a script that automates the cleanup of all these data types. The script uses Mastodon’s built-in CLI tool (tootctl) to handle the cleanup tasks. Please name the script as follows: “mastodon-cleanup.sh“. We will reference the name when executing it via synology task scheduler or cronjob (see below).
#!/bin/bash # Prune remote accounts that never interacted with a local user docker exec Mastodon /app/www/bin/tootctl accounts prune # Remove remote statuses that local users never interacted with, older than 7 days docker exec Mastodon /app/www/bin/tootctl statuses remove --days 7 # Remove media attachments older than 7 days docker exec Mastodon /app/www/bin/tootctl media remove --days 7 # Remove all headers for unfollowed users immediately docker exec Mastodon /app/www/bin/tootctl media remove --remove-headers --exclude-follows --days 0 # Remove headers for followed users after 7 days docker exec Mastodon /app/www/bin/tootctl media remove --remove-headers --include-follows --days 7 # Remove link previews older than 7 days docker exec Mastodon /app/www/bin/tootctl preview_cards remove --days 7 # Remove media files not linked to any posts docker exec Mastodon /app/www/bin/tootctl media remove-orphans
Note: Please adjust your script according to the directory of the CLI tool (tootctl). If you don’t know the exact path of your Mastodon directories you can run the following commands to determine where it is (at least when running Mastodon in Docker).
Connect to your host environment via ssh and execute the following command whereby “Mastodon” is the name of my container in the example below:
docker exec -it Mastodon /bin/bash
Inside the container, search for tootctl with the following command:
find / -name tootctl
Once it’s found, the output will show you the exact path of tootctl. It might look like:
/opt/mastodon/bin/tootctl /usr/local/bin/tootctl /app/www/bin/tootctl
Or something else.
Apply the path to the script accordingly.
Task Scheduling: Automating the Cleanup Process
Now that we have the cleanup script ready, we can automate it to run on a regular basis. There are two primary ways to schedule this task:
Synology’s Task Scheduler: If you’re using a Synology NAS to run your Mastodon instance, you can use Synology’s built-in Task Scheduler to schedule this script to run at specific intervals (e.g., daily at 3 AM). This is an easy-to-use graphical interface that allows you to set up tasks without any command-line knowledge.
To do so, log into your DSM (DiskStation Manager) interface with your user credentials. Once logged in, go to the Control Panel and find Task Scheduler under the System section. Inside Task Scheduler, click Create at the top-left corner, then select Scheduled Task followed by User-defined Script.
In the General tab, give your task a name (for example, “Mastodon Cleanup“) and set the User to root or another privileged user. Next, in the Schedule tab, choose how frequently you want the task to run, such as daily at 3 AM. Under the Task Settings tab, enter the full command to execute your script in the Run Command field, like:
/volume1/docker/mastodon/scripts/mastodon-cleanup.sh >> /volume1/docker/mastodon/scripts/cleanup.log 2>&1
Make sure to use the correct script path and direct output to a log file for monitoring purposes. Once the command is set, click OK to save the task.
After creating the task, you can manually run it to test that it works as expected by selecting the task and clicking Run. This will ensure that your Mastodon cleanup is scheduled correctly.
Note: Please ensure that the directory is setup and the script was uploaded before executing it. Moreover you should ensure that the file can be executed. If you have permission issues just run the following command while beeing at your host via ssh (see above):
chmod +x /volume1/docker/mastodon/scripts/mastodon-cleanup.sh
Cron Jobs: If you’re not using Synology’s Task Scheduler or prefer a more flexible option, you can use cron jobs. Cron is a powerful Linux tool that allows you to schedule tasks at specific times or intervals. You can set up a cron job to run the cleanup script at a set time, such as once a day, once a week, or however frequently you need.
Here’s an example of how you would set up a cron job to run the cleanup script every day at 3 AM:
0 3 * * * /path/to/mastodon-cleanup.sh >> /path/to/cleanup.log 2>&1
This cron job will execute the cleanup script daily at 3 AM and save the output to a log file for monitoring purposes.
Note: I will not go into the details how to apply the cronjob since I am prefering the synology implementation anyways. However as always there are plenty methods to finish the job and I wanted to give you at least an alternative if synology is not your system of choice.
Monitoring and Logging
It’s always a good idea to log the output of your automated tasks, especially when it involves deleting data. In the script above, I’ve included logging that will append any output (both standard output and errors) to a log file. This way, you can review the cleanup process, check for any issues, and ensure that everything is working as expected. The log file will be stored in the same location we uploaded our script.
Additional Considerations
Backup Your Data: Before automating the cleanup process, ensure you have backups of your Mastodon data. While the cleanup script is designed to only remove unnecessary data, it’s always a good practice to have a backup in case something goes wrong.
Script Customization: Depending on your needs, you may want to adjust the script. For example, you might want to keep media files longer than 7 days or tweak the number of days for which statuses are kept. The script is flexible and can be easily customized.
Resources: If your Mastodon instance is under heavy load, consider running the cleanup script during off-peak hours to minimize the impact on users.
Timing: Please keep in mind that the script will take some time (especially for its first run). You can always check the logfile for errors or look into the action –> show results tab under synology task scheduler to check if the skript is still running.
Conclusion
Automating Mastodon cleanup is a great way to keep your instance running smoothly while saving space on your server or NAS. By regularly cleaning up orphaned accounts, old statuses, media files, and headers, you ensure that your instance remains lean and efficient.
Whether you’re using Synology’s Task Scheduler for an easy setup or cron jobs for a more flexible approach, automating the cleanup process ensures your Mastodon instance won’t be bogged down by unnecessary data.
Regular maintenance tasks like this can help you focus on enjoying the platform without worrying about running out of storage or performance degradation. I hope this guide helps you get your Mastodon instance optimized and running smoothly!
