Mastodon Export Cron Job for Admin Backup: Setup

As a Mastodon server administrator, you need a reliable backup strategy to protect user data, media files, and configurations. Manual exports are time-consuming and prone to human error, especially when managing a growing instance. This article explains how to set up an automated cron job that runs a Mastodon export on a schedule, creating regular backups without manual intervention. You will learn the specific commands, scripts, and scheduling steps required to automate the export process on a Linux server.

1. Create the backup directory
   Log into your Mastodon server. Switch to the mastodon user with sudo -i -u mastodon. Create a directory to store the backup scripts and output: mkdir -p ~/backups. This directory will hold both the shell script and the compressed backup files.
2. Write the backup shell script
   Create a new file named ~/backups/mastodon-backup.sh using a text editor like nano: nano ~/backups/mastodon-backup.sh. Paste the following script content, adjusting the paths and database name as needed for your instance:

   #!/bin/bash
   
   # Variables
   BACKUP_DIR="/home/mastodon/backups"
   TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
   DB_NAME="mastodon_production"
   DB_USER="mastodon"
   MEDIA_DIR="/home/mastodon/live/public/system"
   
   # Create backup directory if it does not exist
   mkdir -p "$BACKUP_DIR"
   
   # Dump the PostgreSQL database
   pg_dump -U "$DB_USER" -d "$DB_NAME" --format=custom --file="$BACKUP_DIR/mastodon_db_$TIMESTAMP.dump"
   
   # Compress media files
   tar -czf "$BACKUP_DIR/mastodon_media_$TIMESTAMP.tar.gz" -C "$MEDIA_DIR" .
   
   # Compress configuration files
   tar -czf "$BACKUP_DIR/mastodon_config_$TIMESTAMP.tar.gz" -C /home/mastodon/live .env.production
   
   # Remove backups older than 7 days
   find "$BACKUP_DIR" -name "mastodon_" -type f -mtime +7 -delete
   
   echo "Backup completed at $TIMESTAMP"
   

   Save the file and exit nano.

3. Make the script executable
   Run chmod +x ~/backups/mastodon-backup.sh to allow the script to be executed.
4. Test the script manually
   Run bash ~/backups/mastodon-backup.sh to verify it executes without errors. Check the ~/backups directory for the generated files: ls -la ~/backups. You should see three files with timestamps in their names.
5. Open the cron table for the mastodon user
   Still as the mastodon user, run crontab -e. If prompted, select your preferred text editor (nano is recommended).
6. Add the cron job entry
   Add the following line to the end of the crontab file to run the backup daily at 3:00 AM:
   0 3 /bin/bash /home/mastodon/backups/mastodon-backup.sh
   Save the file and exit. The cron daemon will automatically load the new schedule.
7. Verify the cron job is active
   Run crontab -l to list the active cron jobs. You should see the line you just added. Check the system logs with grep CRON /var/log/syslog after the scheduled time to confirm the job ran successfully.

Common Mistakes and Limitations When Automating Backups

Backup script fails with permission denied to PostgreSQL database

The mastodon user must have proper PostgreSQL permissions to run pg_dump. By default, the mastodon user is created as a PostgreSQL superuser during installation. If you changed the database user, update the DB_USER variable in the script and ensure that user has read access to the database. Test the command pg_dump -U mastodon -d mastodon_production --format=custom --file=/tmp/test.dump manually to verify.

Cron job runs but no backup files appear

This usually means the script encountered an error that was not captured in the output. Modify the cron job line to redirect output to a log file for debugging. Change the line to:
0 3 /bin/bash /home/mastodon/backups/mastodon-backup.sh >> /home/mastodon/backups/cron.log 2>&1
Wait for the next run or trigger it manually, then check cron.log for error messages.

Backups consume too much disk space

The script includes a cleanup command that deletes backups older than 7 days. Adjust the +7 value to a different number of days if you need longer retention. For example, +14 keeps backups for two weeks. Monitor disk usage with df -h to ensure the backup directory does not fill the filesystem.

Media directory backup is too large

Mastodon media files can consume gigabytes of disk space. Before running the backup script, consider running tootctl media remove --days=30 to delete cached media older than 30 days. This command is safe to run before the backup because it only removes media that has been cached by remote instances, not user-uploaded content. Add this command to the backup script before the media compression line to reduce backup size.

Manual Export vs Automated Cron Backup

With the cron job running daily, your Mastodon instance now has a consistent, automated backup routine. You can extend the script to upload the backup files to a remote server or cloud storage using rsync or aws s3 cp. For added security, encrypt the database dump with gpg before transferring it off the server. Test a full restore process at least once by importing a backup into a test instance to confirm the data is recoverable.