Refine Synology backup workflow

Co-authored-by: Copilot App <[email protected]>

docs/backup_restore.md

@@ -2,14 +2,21 @@
 
 This guide defines operational backup/restore for clean-slate recovery of the Docker runtime and Synology replication.
 
-## 1. Backup artifacts (full recovery set)
+## 1. Backup artifacts (clean-slate recovery set)
 
 - Primary local backup location: `./data/backups`
-- Files created per timestamp:
+- Local files created per run:
   - `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)
+- Synology files created per run (when `SYNOLOGY_BACKUP_DIR` is set):
+  - `postgres-YYYYMMDD-HHMMSS.dump` (copied from local)
+  - `config-YYYYMMDD-HHMMSS.tar.gz` (deployment config snapshot: `.env.production`, `docker-compose.production.yml`, `deploy/cloudflared/config.yml` when present)
+  - `logs-YYYYMMDD-HHMMSS.tar.gz` (snapshot of `/app/data/logs`)
+  - `backup-YYYYMMDD-HHMMSS.manifest`
+- Synology incremental media mirror (copied only if missing):
+  - `uploads/homepage.md`
+  - `uploads/documents/**`
+  - `uploads/photos/**`
 
 ## 2. Creating backups
 
@@ -23,14 +30,14 @@ Environment overrides:
 
 - `BACKUP_DIR` (default `./data/backups`)
 - `BACKUP_RETENTION_DAYS` (default `14`)
-- `SYNOLOGY_BACKUP_DIR` (if set, backup is copied to this mounted path)
+- `SYNOLOGY_BACKUP_DIR` (if set, dump/config/log/manifest are copied to this mounted path and media is synced incrementally)
 - `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
+SYNOLOGY_BACKUP_DIR=/mnt/synology-backups sh deploy/backup/create_postgres_backup.sh
 ```
 
 ## 2.1 Persisting Synology mount (LXC)
@@ -51,6 +58,7 @@ Recommended pattern:
 
 - Keep NAS credentials in a local file like `/etc/samba/credentials/transcription-synology` with `chmod 600`.
 - Keep `SYNOLOGY_BACKUP_DIR` in `.env.production` aligned to that mount point (for example `/mnt/synology-backups`).
+- The script will also read `SYNOLOGY_BACKUP_DIR` from `ENV_FILE` when not exported in the shell.
 
 ## 3. Restoring from backup
 
@@ -60,7 +68,8 @@ Restore requires downtime for app + worker writes.
    - `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.
+   - if `SYNOLOGY_BACKUP_DIR/uploads` exists, media is restored from the Synology mirror.
+   - if `SYNOLOGY_BACKUP_DIR/config-YYYYMMDD-HHMMSS.tar.gz` exists, config is restored from that archive.
 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.
@@ -68,7 +77,7 @@ Restore requires downtime for app + worker writes.
 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).
+- Legacy full-archive restores (`uploads-*.tar.gz`, `config-*.tar.gz` beside the dump) are still supported for older backups.
 
 ## 4. Retention and recovery targets
 

docs/production-runbook.md

@@ -36,7 +36,7 @@ This runbook is the operational checklist for releasing and monitoring the trans
    - stdout aggregation receives events
    - file logs are written under `./data/logs`
 5. Create a fresh PostgreSQL backup after successful deployment:
-   - `sh deploy/backup/create_postgres_backup.sh` (creates DB dump + uploads + config recovery set)
+   - `sh deploy/backup/create_postgres_backup.sh` (creates local DB dump + Synology DB/config/log artifacts + incremental media mirror)
 
 ## 3. Rollback triggers and actions
 
@@ -56,7 +56,7 @@ This runbook is the operational checklist for releasing and monitoring the trans
    - relevant DB rows (`job`, `job_source`, `execution_attempt`)
 5. If persistence regression is confirmed, restore the latest valid DB dump:
    - `sh deploy/backup/restore_postgres_backup.sh <dump-file>`
-   - paired uploads/config artifacts (same timestamp) are restored automatically when present.
+   - Synology media mirror and paired config snapshot (same timestamp) are restored automatically when present.
 
 ## 4. Post-release monitoring checklist