# 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:

```bash
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`)
- `POSTGRES_HOST` (default `postgres`)
- `POSTGRES_PORT` (default `5432`)
- `POSTGRES_DB` (required)
- `POSTGRES_USER` (required)
- `POSTGRES_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.