# 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

## Local Development Setup

For local dev on Windows, configure a local backup directory:

1. Add to `.env`:
   ```
   SHOPDB_BACKUPS_ROOT=C:/Users/YOUR_USERNAME/Documents/github/flask-shopdb/backups
   ```

2. Create the directory:
   ```bash
   mkdir backups
   ```

3. Restart Flask

Note: Actual backup execution requires Docker (the backup container). The API can queue backups but won't execute them without the sidecar container.

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