transcription/docs/backup_restore.md

Backup and Restore (V6.1)

This guide defines operational backup/restore for clean-slate recovery of the Docker runtime using a host-visible backup folder.

1. Backup artifacts

• Backup target root: BACKUP_DIR (recommended production value: /backup)
• Database artifact per run:
  • postgres-YYYYMMDD-HHMMSS.dump (PostgreSQL custom dump via pg_dump -Fc)
  • backup-YYYYMMDD-HHMMSS.manifest (run manifest)
• Media/config mirrors under BACKUP_DIR:
  • uploads/** (incremental copy: new files only)
  • prompts/** (prompt directory mirror)

Retention:

• BACKUP_RETENTION_DAYS applies to postgres-*.dump and backup-*.manifest files.

2. Creating backups

Run from repository root:

sh deploy/backup/create_postgres_backup.sh

Environment variables used by the backup script:

• BACKUP_DIR (default ./data/backups)
• BACKUP_RETENTION_DAYS (default 14)
• UPLOAD_DIR (default /app/uploads)
• PROMPT_DIR (default /app/prompts)
• DATABASE__DRIVER (must be postgres)
• DATABASE__HOST (default postgres)
• DATABASE__PORT (default 5432)
• DATABASE__DATABASE (required)
• DATABASE__USER (required)
• DATABASE__PASSWORD (required)

Recommended production setup:

• Mount a host-visible folder into /backup for both app and worker.
• Set BACKUP_DIR=/backup in .env.production.
• Use host-level tooling (for example Synology Drive Client on the host) to replicate that folder externally.

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 database:
   • sh deploy/backup/restore_postgres_backup.sh /backup/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.

Notes:

• restore_postgres_backup.sh still supports legacy archive restore paths for older backup sets.