From 5eb5c83b23ffc180f06778bfb823bc377a7bf7ac Mon Sep 17 00:00:00 2001
From: Proudlock <270015376@geaerospace.com>
Date: Sun, 6 Sep 2026 23:54:11 -0400
Subject: [PATCH] Document backup feature in scripts/backup/README.md

- Quick start guide for backup/restore
- Configuration options (local, SMB, S3)
- Troubleshooting common issues
- API endpoints reference
- Clarify empty list on first deployment is normal
---
 scripts/backup/README.md | 79 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 scripts/backup/README.md

diff --git a/scripts/backup/README.md b/scripts/backup/README.md
new file mode 100644
index 00000000..1390ed6e
--- /dev/null
+++ b/scripts/backup/README.md
@@ -0,0 +1,79 @@
+# ShopDB Backup & Restore
+
+The backup system provides automated database and instance backups with restore capability.
+
+## Quick Start
+
+```bash
+# Trigger a backup via docker-compose
+docker compose -f docker-compose.backup.yml up backup
+
+# Or via API (requires admin JWT token)
+curl -X POST http://localhost:5001/api/shopdbbackups \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+## Configuration
+
+By default, backups are stored in `/backups` volume (local to Docker host).
+
+For production, configure storage in Settings > Backups web UI:
+- **Local**: Default, no configuration needed
+- **SMB**: Network share (requires hostname, share, credentials)
+- **AWS S3**: Cloud storage (requires region, bucket, credentials)
+
+## Retention Policy
+
+- 5 daily backups
+- 4 weekly backups  
+- 6 monthly backups
+
+## Backup Contents
+
+Each backup set includes:
+- `db.sql.gz` - Compressed MySQL dump
+- `instance/` - Uploaded files, branding, floor plans, maps
+- `manifest.json` - Schema revisions for compatibility checking
+
+## Restore
+
+1. Go to **Settings > Backups** in web UI
+2. Select a backup set
+3. Click **Restore**
+4. System validates schema compatibility and restores database + files
+
+## First Deployment
+
+On fresh install, `/api/shopdbbackups` returns empty list - this is normal.
+No backups exist until first backup runs.
+
+## Troubleshooting
+
+**"No backups found"**
+- Check `/backups` volume is mounted
+- Verify backup container ran: `docker logs shopdb-backup-1`
+
+**"500 error on backup endpoint"**
+- Must be logged in as admin
+- Check Flask logs for details
+
+**"Restore failed: incompatible schema"**
+- Backup is from newer ShopDB version
+- Update code first, then restore
+
+## API Endpoints
+
+All require `admin` role:
+
+- `GET /api/shopdbbackups` - List backups
+- `POST /api/shopdbbackups` - Trigger backup
+- `POST /api/shopdbbackups/<id>/restore` - Restore backup
+- `GET /api/shopdbbackups/status` - Current status
+- `GET /api/shopdbbackups/history` - Backup history
+
+## Security
+
+- Backups contain sensitive data (DB dump, uploads)
+- Secure `/backups` volume with appropriate permissions
+- Use encrypted storage for offsite backups
+- Only admin role can access backup endpoints