Backup & Recovery

Regular backups protect your data from hardware failure, accidental deletion, and other disasters. Freedom Messenger makes it easy.

What to Back Up

A complete backup includes:

  1. Database — the SQLite file containing all messages, users, and metadata
  2. Uploaded files — the data/files/ directory with all user uploads
  3. Configuration — config.toml with your plaintext or encrypted master secret
  4. Unlock passphrase — required separately if you use freedom-mess protect-secret

Database Backup

Use the built-in backup command for a consistent database snapshot:

freedom-mess backup -o /path/to/backup.db

This uses SQLite's VACUUM INTO which is safe to run while the server is running. The backup is a complete, consistent copy of the database at the moment the command runs.

Do not simply copy the SQLite file while the server is running. This can result in a corrupted backup. Always use the backup command.

Full Backup Script

Here is an example script that backs up everything:

#!/bin/bash
BACKUP_DIR="/backups/freedom-mess/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Database (safe while running)
freedom-mess backup -o "$BACKUP_DIR/database.db"

# Uploaded files
cp -r /opt/freedom-mess/data/files/ "$BACKUP_DIR/files/"

# Configuration
cp /opt/freedom-mess/config.toml "$BACKUP_DIR/config.toml"

# Config unlock passphrase, if protect-secret is enabled
if [ -f /etc/freedom-mess/config-passphrase ]; then
  cp /etc/freedom-mess/config-passphrase "$BACKUP_DIR/config-passphrase"
fi

echo "Backup complete: $BACKUP_DIR"

If you copy the unlock passphrase into the same backup bundle, encrypt that bundle or move the passphrase into a separate password manager entry before storing it offsite.

Automated Backups

Set up a cron job to run the backup script daily:

# Edit crontab
crontab -e

# Add this line (runs daily at 3 AM)
0 3 * * * /opt/freedom-mess/backup.sh

Consider copying backups to a remote location (another server, cloud storage, or an external drive) for disaster recovery.

Recovery

To restore from a backup:

  1. Stop the server: sudo systemctl stop freedom-mess
  2. Replace the database: cp backup.db /opt/freedom-mess/data/freedom-mess.db
  3. Restore uploaded files: cp -r files/ /opt/freedom-mess/data/files/
  4. Restore config (if needed): cp config.toml /opt/freedom-mess/config.toml
  5. If the config contains [encrypted_secret], restore the passphrase file with mode 0600 or configure a systemd credential
  6. Start the server: sudo systemctl start freedom-mess
The server runs an integrity check on the database at startup. If the restored database passes the check, the server starts normally. If it fails, check your backup or try an older one.

SQLite Maintenance

Freedom Messenger handles database maintenance automatically:

  • WAL mode — Write-Ahead Logging for concurrent read/write performance
  • Busy timeout — 5 seconds to handle lock contention
  • Hourly WAL checkpoint — keeps the WAL file from growing indefinitely
  • Incremental auto-vacuum — reclaims disk space as data is deleted
  • Integrity check on startup — verifies database consistency