Mastodon Instance Backups: What an Admin Should Run Daily

Running a Mastodon instance means you are responsible for user data, media files, and database integrity. A single server failure or corruption event can erase months of posts, accounts, and relationships if you have no backup. Many admins rely only on database dumps and forget about media or configuration files. This article explains exactly which components need daily backups, the tools to automate them, and how to verify your backups actually work.

Why Mastodon Requires Separate Backups for Database, Media, and Config

Mastodon stores data in three separate locations on the server. The PostgreSQL database holds structured data: accounts, statuses, followers, blocks, and settings. Media files like images and videos reside on the filesystem under /opt/mastodon/public/system. Configuration secrets live in the .env.production file. A backup strategy must cover all three because losing any one makes full recovery impossible.

The database is the most critical component. Without it, you have no records of who signed up, what they posted, or who they follow. A PostgreSQL dump using pg_dump creates a plain-text SQL file that can be restored on any PostgreSQL server of the same major version. Media files are less critical for basic functionality, but users expect their avatars and uploaded images to survive a restore.

Configuration files contain secrets that Mastodon uses to encrypt sessions and communicate with external services like object storage. If you lose .env.production, you must regenerate all secrets, which invalidates existing user sessions and federation keys. Daily backups of all three components are the minimum standard for a production Mastodon instance.

Daily Backup Procedure for Mastodon Instance

The following procedure assumes a standard Mastodon installation on Ubuntu or Debian with PostgreSQL and systemd. Adjust paths if your instance uses a different directory or containerized setup.

1. Stop Mastodon services to prevent data changes during backup
   Run sudo systemctl stop mastodon-web mastodon-sidekiq mastodon-streaming. This ensures no new toots, follows, or media uploads occur while the backup runs.
2. Create the database dump using pg_dump
   Run sudo -u postgres pg_dump -Fc mastodon_production > /backup/mastodon_db_$(date +%Y%m%d).dump. The -Fc flag creates a compressed custom format that is faster to restore and smaller than plain SQL.
3. Archive configuration files
   Run sudo tar -czf /backup/mastodon_config_$(date +%Y%m%d).tar.gz /opt/mastodon/.env.production /opt/mastodon/nginx.conf. Include any custom nginx or systemd override files.
4. Back up media files
   Run sudo tar -czf /backup/mastodon_media_$(date +%Y%m%d).tar.gz /opt/mastodon/public/system. For large instances, consider using rsync instead of tar to save bandwidth on incremental backups.
5. Restart Mastodon services
   Run sudo systemctl start mastodon-web mastodon-sidekiq mastodon-streaming. Verify with sudo systemctl status mastodon-web that all services are active.
6. Copy backups to an off-site location
   Use rclone copy /backup remote:backup-bucket/mastodon/ or rsync -avz /backup/ user@backup-server:/backup/mastodon/. Off-site storage protects against server hardware failure or data center outages.

Common Backup Mistakes and How to Avoid Them

Backing up the database while services are running

A live database dump can capture a transaction that is partially committed. This creates a backup that restores correctly but contains inconsistent data, such as a toot that references a nonexistent account. Always stop Mastodon services before the dump, or use pg_dump --lock-wait-timeout=10 to enforce a wait time on locks.

Forgetting to back up the .env.production file

Without the secret key base, Mastodon cannot decrypt user sessions. Users must log in again, and federation keys are invalidated. Store the .env.production file in a separate backup archive from the database so you can restore it without restoring the entire filesystem.

Not testing backup restoration

A backup that has never been restored is a backup you cannot trust. Set up a test environment on a separate server or virtual machine. Restore the database, config, and media files, then verify that the instance starts and user accounts appear correctly. Run this test monthly.

Database Dump vs Filesystem Backup: What Each Covers

Item	pg_dump (Database)	Filesystem Backup (tar/rsync)
Accounts and profiles	Yes	No
Statuses and replies	Yes	No
Followers and follow requests	Yes	No
Media files (avatars, headers, attachments)	No	Yes
Configuration secrets	No	Yes
Nginx or reverse proxy config	No	Yes

The table shows that neither method alone is sufficient. A complete backup strategy uses both: pg_dump for the database and filesystem backup for media and config.

You now know the three components that require daily backups: the PostgreSQL database, the media directory, and the .env.production configuration file. Automate this process with a cron job that runs the steps above every 24 hours. Next, set up a monthly restoration test on a staging server to confirm your backups are valid. Use rclone with encryption to store backups on a separate cloud provider for maximum safety.