Skip to content

FirmFlow Backup & Recovery Operations

This guide covers how to safeguard an on-premise FirmFlow environment and restore it during a disaster. Because FirmFlow manages sovereign document vaults and cryptographically signed audit trails, daily backups are mandatory.

1. Components to Backup

A FirmFlow installation consists of two critical data zones:

  1. The Vault Filesystem (/opt/firmflow/uploads)
    • Contains all AES-256 encrypted client documents.
    • If lost, the database metadata will point to missing blobs, causing 404 access errors.
  2. The PostgreSQL Database (firmflow dump)
    • Contains the hash chains, user accounts, licenses, compliance tables, and document metadata.
    • If lost, you lose the mapping and decryption keys to the encrypted documents.

Both must be backed up simultaneously (or near-simultaneously) to ensure referential integrity.

2. Backup Procedure (Automated Script)

Write a cron script on the Docker host that executes nightly:

#!/bin/bash
DATE=$(date +%Y-%m-%d)
BACKUP_DIR="/mnt/nfs/backups/firmflow"

# 1. Back up the Postgres DB
docker compose exec -t db pg_dump -U firmflow -Fc firmflow > $BACKUP_DIR/db_$DATE.dump

# 2. Back up the Vault (rsync for incremental updates)
rsync -aP --delete /opt/firmflow/uploads/ $BACKUP_DIR/vault_sync/

# 3. Compress current vault state 
tar -czf $BACKUP_DIR/vault_snapshot_$DATE.tar.gz -C $BACKUP_DIR/vault_sync .

# 4. Clean up old backups (keep last 30 days)
find $BACKUP_DIR -name "db_*.dump" -type f -mtime +30 -delete
find $BACKUP_DIR -name "vault_snapshot_*.tar.gz" -type f -mtime +30 -delete

Ensure $BACKUP_DIR is on a separate disk array or pushed to an off-site NAS/Cloud Bucket (e.g. AWS S3 via AWS CLI).

3. Recovery Procedure

To recover from a catastrophic failure:

  1. Prepare Fresh Environment: Install Docker Compose and ensure your .env file uses the exact same AUTH_SECRET and LICENSE_KEY as your original server (crucial for JWTs and licensing).
  2. Restore the Vault: 
    mkdir -p /opt/firmflow/uploads
tar -xzf vault_snapshot_YYYY-MM-DD.tar.gz -C /opt/firmflow/uploads
  3. Start Database & Next.js: 
    docker compose up -d
  4. Restore DB Dump: 
    # Drop and recreate if needed
docker compose exec -T db dropdb -U firmflow firmflow
docker compose exec -T db createdb -U firmflow firmflow
# Restore using pg_restore
cat db_YYYY-MM-DD.dump | docker compose exec -T db pg_restore -U firmflow -d firmflow
  5. Restart the Stack: 
    docker compose restart web

4. Encryption Keys

Your AES-256 storage keys and HMAC audit chain keys are bound to your AUTH_SECRET in .env. You must back up your .env file securely. If you lose the AUTH_SECRET, the Postgres database and uploaded documents will become permanently undecryptable.