V6 Phase 4 - Postgres backup to Synology

docs/backup_restore.md

@@ -0,0 +1,49 @@
+# Backup and Restore (V6.0 Phase 4)
+
+This guide defines operational backup/restore for the Docker PostgreSQL runtime and Synology replication.
+
+## 1. Backup artifacts
+
+- Primary local backup location: `./data/backups`
+- Backup format: PostgreSQL custom dump (`pg_dump -Fc`)
+- Naming: `postgres-YYYYMMDD-HHMMSS.dump` (UTC timestamp)
+
+## 2. Creating backups
+
+Use the scripted command:
+
+```bash
+sh deploy/backup/create_postgres_backup.sh
+```
+
+Optional 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:
+
+```bash
+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`
+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.
+
+## 4. Retention and recovery targets
+
+- Retention baseline: keep at least 14 days of backups locally.
+- Synology copy: replicate each new backup to DS420j mounted path.
+- Periodic restore drill: run at least once per release cycle to verify recovery.