shopdb-flask/scripts/backup

ShopDB Backup & Restore

The backup system provides automated database and instance backups with restore capability.

Quick Start

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

   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