Backups & Recovery

📦v1.0.0📅2026-04-28🔄Updated 2026-04-28👤Admin Team
administrationoperationsbackupsrecovery

Backups & Recovery

Message Center's state lives entirely in MongoDB. Certificates are injected at runtime. There is no other stateful storage to back up — with one exception: the audit fallback file, which accumulates events when MongoDB is temporarily unreachable.

What to Back Up

DataLocationHow to back up
All application dataMongoDB database (MONGODB_DB)mongodump or Atlas backup
Audit fallback (if non-empty)$TMPDIR/core-admin-audit-fallback.jsonlCopy file before restoring DB
mTLS certificatescerts/ (git-ignored)Secure external storage
Environment secrets.env / Kubernetes SecretsSecrets manager / vault

MongoDB Backup Strategy

If you use MongoDB Atlas, enable Continuous Cloud Backup. This provides point-in-time restore (PITR) with a granularity of minutes and is the lowest-effort option.

Self-hosted: mongodump

# Full database dump
mongodump \
  --uri="$MONGODB_URI" \
  --db="$MONGODB_DB" \
  --out=/backups/$(date +%Y%m%d_%H%M%S)

# Compressed archive
mongodump \
  --uri="$MONGODB_URI" \
  --db="$MONGODB_DB" \
  --archive=/backups/message-center-$(date +%Y%m%d).gz \
  --gzip

Backup schedule

Take a backup:

  • Before every deploy (especially before running migrations — migrations have no rollback)
  • Daily via cron, retaining at minimum the last 7 days
  • Before seeding if re-seeding on an existing database

Restoring from Backup

mongorestore

# Restore from archive
mongorestore \
  --uri="$MONGODB_URI" \
  --db="$MONGODB_DB" \
  --archive=/backups/message-center-20260428.gz \
  --gzip \
  --drop   # Drop existing collections before restoring

--drop replaces all existing data. Confirm the backup is correct before using it.

After restore

  1. Verify the schema version matches the expected value:
# Connect to MongoDB and check
mongosh "$MONGODB_URI" --eval 'db.meta.findOne({_id:"schema"})'
  1. If the backup predates a migration, re-run migrations:
make migrate
  1. Verify the application health via the Diagnostics page.

Audit Fallback Recovery

The audit fallback file ($TMPDIR/core-admin-audit-fallback.jsonl) accumulates compliance events when MongoDB is down. Events are replayed into MongoDB automatically on the next write.

Manual drain

If you need to force a drain after MongoDB recovers:

  1. Open any auditable action in the UI (e.g., load a campaign, invite a member) — this triggers logAuditEvent, which calls the drain automatically.
  2. Check GET /api/diagnostics/audit to confirm fallbackFileSize returns to 0.

Manual import (last resort)

If the BFF cannot drain automatically (e.g., the file is too large or the process is being replaced):

# Each line is a valid JSON audit event. Import directly:
mongoimport \
  --uri="$MONGODB_URI" \
  --db="$MONGODB_DB" \
  --collection=audit_logs \
  --file=$TMPDIR/core-admin-audit-fallback.jsonl \
  --mode=insert

# After successful import, remove the fallback file
rm $TMPDIR/core-admin-audit-fallback.jsonl

The fallback file uses the same schema as audit_logs — mongoimport accepts it directly.

Certificate Recovery

mTLS certificates are not managed by Message Center. Recover them from your PKI/CA or the secure external storage where you archived them. After restoring, update the Kubernetes Secret (see mTLS Certificates).

Recovery Checklist

After any restore:

  • Schema version matches the application version (GET /api/diagnostics → DB schema tile)
  • Super admin account exists and is accessible (run make seed if missing)
  • Audit fallback file is empty (fallbackFileSize: 0)
  • Core API shows OK in Diagnostics
  • mTLS certificates are mounted and valid

Next Steps