transcription/docs/backup_restore.md

Backup and Restore (V6.0 Phase 4)

This guide defines operational backup/restore for clean-slate recovery of the Docker runtime and Synology replication.

1. Backup artifacts (full recovery set)

• Primary local backup location: ./data/backups
• Files created per timestamp:
  • postgres-YYYYMMDD-HHMMSS.dump (PostgreSQL custom dump via pg_dump -Fc)
  • uploads-YYYYMMDD-HHMMSS.tar.gz (full /app/uploads volume; includes homepage.md, documents, and photos)
  • config-YYYYMMDD-HHMMSS.tar.gz (deployment config snapshot: .env.production, docker-compose.production.yml, deploy/cloudflared/config.yml)
  • backup-YYYYMMDD-HHMMSS.manifest (artifact index)

2. Creating backups

Use the scripted command from the repository root:

sh deploy/backup/create_postgres_backup.sh

Environment overrides:

• BACKUP_DIR (default ./data/backups)
• BACKUP_RETENTION_DAYS (default 14)
• SYNOLOGY_BACKUP_DIR (if set, backup is copied to this mounted path)
• ENV_FILE (default .env.production)
• COMPOSE_FILE (default docker-compose.production.yml)

Example with Synology mount:

SYNOLOGY_BACKUP_DIR=/mnt/synology/transcription-backups sh deploy/backup/create_postgres_backup.sh

3. Restoring from backup

Restore requires downtime for app + worker writes.

1. Stop app and worker:
   • docker compose --env-file .env.production -f docker-compose.production.yml stop app worker
2. Restore:
   • sh deploy/backup/restore_postgres_backup.sh ./data/backups/postgres-YYYYMMDD-HHMMSS.dump
   • if same-timestamp uploads-*.tar.gz and config-*.tar.gz exist in the same directory, they are restored automatically.
3. Start app and worker:
   • docker compose --env-file .env.production -f docker-compose.production.yml start app worker
4. Validate /healthz and run one smoke workflow.

Notes:

• Config restore extracts the archived files back into the current repository path.
• If only the database dump is present, restore runs in database-only mode (legacy behavior).

4. Retention and recovery targets

• Retention baseline: keep at least 14 days of backups locally.
• Synology copy: replicate each backup artifact set to DS420j mounted path.
• Periodic restore drill: run at least once per release cycle to verify recovery.