Backup & Recovery

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

What to Back Up

Three things make up a complete backup:

  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 master secret and keys

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"

echo "Backup complete: $BACKUP_DIR"

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. 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