Backups & Restore

CompassDocs can take full-database backups (a pg_dump of everything — users, documents, versions, settings) on a schedule or on demand, keep a rolling set, restore from any of them, and mirror copies off-site. It’s all in Settings → Backups (admins only).

This is different from Import & export, which handles document content as Markdown — backups are a complete database snapshot for disaster recovery.

Where backups live

Backups are written to a local volume (mounted at /backups in Docker). The included compose files create a compassdocs_backups volume for this — no setup needed.

Automatic backups

In Settings → Backups, set a frequency (Daily or Weekly) and how many to keep. The app checks hourly and runs a backup when one is due, pruning the oldest beyond your retention count. Leave it Off to only back up manually.

Encryption

Since 0.41, every new backup is encrypted (AES-256-GCM) with the workspace’s master key before it touches disk or an off-site bucket — files are named .dump.enc. Restores handle both encrypted and older plaintext .dump files automatically.

Caution

Restoring an encrypted backup on a new host requires the same master key (COMPASSDOCS_SECRET_KEY or the key file). Keep a copy of the key somewhere that is not the backup bucket — without it, encrypted backups are unrecoverable.

On-demand & restore

• Back up now creates a backup immediately.
• Download pulls the (encrypted) dump file to your machine.
• Restore replaces the entire database with a backup’s contents. This is destructive and irreversible — it’s behind a double confirmation, and everyone will need to sign in again afterward.
• Delete removes a backup (locally and from remote destinations).

Off-site copies (optional)

Every backup can be mirrored to S3 or Azure Blob Storage so it survives losing the server.

Configure it in the UI (recommended)

Under Settings → Backups → Off-site destinations, fill in the S3 or Azure card and click Save, or Save & test to verify the credentials with a real upload/delete round-trip. Credentials are stored securely and never shown again. This is the easiest path — no restart needed.

S3-compatible (AWS S3, Cloudflare R2, MinIO): bucket, region, optional endpoint (for R2/MinIO), optional key prefix, access key ID, and secret access key.

Azure Blob Storage: container name and a connection string.

Configure it with environment variables

Prefer config-as-code? Set these instead (a destination configured in the UI takes precedence):

# S3-compatible
BACKUP_S3_BUCKET=my-compassdocs-backups
BACKUP_S3_REGION=us-east-1
BACKUP_S3_ACCESS_KEY_ID=...
BACKUP_S3_SECRET_ACCESS_KEY=...
BACKUP_S3_ENDPOINT=            # set for R2/MinIO
BACKUP_S3_PREFIX=              # optional key prefix

# Azure Blob Storage
BACKUP_AZURE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...
BACKUP_AZURE_CONTAINER=compassdocs-backups

Configured destinations show a green badge on the Backups page and on the System info page. A destination being unreachable never fails the local backup — it’s just reported.

Restoring off-site backups

Restore runs from a local backup file. If you’re recovering onto a fresh server, download the backup from your S3/Azure bucket into the /backups volume first, then restore it from the UI.