Skip to main content

Backup & Recovery

Surface Security provides automated and manual backup capabilities for both PostgreSQL (transactional data) and ClickHouse (analytics data).

Automated Backups​

Backups run automatically via cron jobs in the backup containers.

DatabaseScheduleContent
PostgreSQLDaily at 2 AM UTCFull database dump including tenants, users, devices, policies, audit logs
ClickHouseDaily at 3 AM UTCFull database backup including navigation events, credential attempts, alerts

Manual Backup​

PostgreSQL​

# Full backup
docker compose exec postgres-backup /backup.sh full

# Export specific tenant
docker compose exec postgres-backup /backup.sh tenant YOUR_TENANT_ID

ClickHouse​

ClickHouse backups are handled by the automated backup schedule. Manual ClickHouse backups can be performed using the ClickHouse built-in backup commands:

# Full backup using ClickHouse native backup
docker compose exec clickhouse clickhouse-client \
  --query "BACKUP DATABASE surfacesec TO Disk('backups', 'manual_$(date +%Y%m%d_%H%M%S)')"

Restore from Backup​

List Available Backups​

ls -la /backup/

Restore PostgreSQL​

docker compose exec postgres pg_restore -U surfacesec -d surfacesec /backup/full_20240115_020000.sql.gz

Restore ClickHouse​

docker compose exec clickhouse clickhouse-client \
  --query "RESTORE TABLE surfacesec.* FROM Disk('backups', 'full_20240115')"

Export Data for Transfer​

To export all tenant data for migration to a new environment:

# Export all tenant data
./scripts/export-tenant.sh YOUR_TENANT_ID /path/to/export

This creates:

  • tenant_data.json -- PostgreSQL data (users, devices, policies, settings)
  • events.parquet -- ClickHouse events (navigation, credentials, alerts)
  • manifest.json -- Export metadata (timestamp, version, record counts)

Backup Best Practices​

  • Verify backups regularly by performing test restores in a non-production environment
  • Store backups off-site to protect against infrastructure failures
  • Enable backup encryption for compliance (see the Security Checklist in the deployment guide)
  • Monitor backup job status via the health check endpoints or container logs
  • Retain backups according to your organization's data retention policy
  • Confirm a recent backup exists before performing any upgrade (see the Upgrade & Rollback guide)