qr-code_manager/BACKUP_SYSTEM.md

# QR Code Manager - Backup System Documentation

## Overview

The QR Code Manager includes a comprehensive backup system that allows users to create, manage, and restore application data. The backup system supports both manual and automated backup creation, with full lifecycle management including deletion and cleanup capabilities.

## Features

### ✅ Backup Creation
- **Manual Backup**: Create backups on-demand through the web interface
- **Automated Backup**: Schedule regular backups using cron jobs
- **Comprehensive Data**: Backs up all application data including QR codes, short URLs, and link pages
- **Timestamped Files**: Each backup includes creation timestamp for easy identification

### ✅ Backup Management
- **List All Backups**: View all available backups with creation dates and file sizes
- **Download Backups**: Download backup files directly from the web interface
- **Delete Individual Backups**: Remove specific backup files
- **Bulk Cleanup**: Automatically remove old backups (older than 7 days)
- **Real-time Status**: Live updates on backup operations

### ✅ Data Integrity
- **ZIP Compression**: All backups are compressed for efficient storage
- **File Validation**: Automatic validation of backup file integrity
- **Error Handling**: Comprehensive error reporting and recovery

## Architecture

### Components

1. **`backup.py`** - Core backup script
   - Creates timestamped ZIP archives
   - Handles data collection and compression
   - Provides command-line interface for automation

2. **`docker_backup.sh`** - Docker-aware backup wrapper
   - Executes backups within Docker containers
   - Handles volume mounting and permissions

3. **API Endpoints** (`app/routes/api.py`)
   - `/api/backup/create` - Create new backup
   - `/api/backup/list` - List all backups
   - `/api/backup/status` - Check backup operation status
   - `/api/backup/delete/<filename>` - Delete specific backup
   - `/api/backup/cleanup` - Remove old backups

4. **Web Interface** (`app/templates/backup.html`)
   - User-friendly backup management dashboard
   - Real-time operation status updates
   - Confirmation dialogs for destructive operations

## Installation & Setup

### Docker Environment (Recommended)

The backup system is pre-configured for Docker deployment:

```yaml
# docker-compose.yml
services:
  qr-manager:
    build: .
    ports:
      - "8066:5000"
    volumes:
      - ./data:/app/data
      - ./backups:/app/backups  # Backup persistence
```

### Manual Installation

1. Ensure Python dependencies are installed:
   ```bash
   pip install -r requirements.txt
   ```

2. Create backup directory:
   ```bash
   mkdir -p backups
   ```

3. Set appropriate permissions:
   ```bash
   chmod +x backup.py docker_backup.sh
   ```

## Usage Guide

### Creating Backups

#### Via Web Interface
1. Navigate to the backup management page
2. Click "Create Backup"
3. Monitor progress in real-time
4. Download completed backup when ready

#### Via Command Line
```bash
# Direct execution
python backup.py

# Docker execution
./docker_backup.sh
```

#### Via API
```bash
curl -X POST http://localhost:8066/api/backup/create
```

### Managing Backups

#### List All Backups
- **Web**: Visit backup management page
- **API**: `GET /api/backup/list`

#### Download Backup
- **Web**: Click download button next to backup
- **Direct**: Access files in `./backups/` directory

#### Delete Individual Backup
- **Web**: Click red "Delete" button with confirmation
- **API**: `DELETE /api/backup/delete/<filename>`

#### Cleanup Old Backups
- **Web**: Click "Cleanup Old Backups" button
- **API**: `POST /api/backup/cleanup`

### Restoring from Backup

1. **Stop the application**:
   ```bash
   docker compose down
   ```

2. **Extract backup**:
   ```bash
   cd data/
   unzip ../backups/backup_YYYYMMDD_HHMMSS.zip
   ```

3. **Restart application**:
   ```bash
   docker compose up -d
   ```

## Backup Contents

Each backup includes:

```
backup_YYYYMMDD_HHMMSS.zip
├── qr_codes.json          # QR code data and metadata
├── short_urls.json        # URL shortening data
├── link_pages.json        # Link page configurations
└── static/
    └── qr_codes/          # Generated QR code images
        ├── qr_*.png
        └── ...
```

## Automation

### Cron Job Setup

Add to crontab for automated backups:

```bash
# Daily backup at 2 AM
0 2 * * * cd /opt/qr-code_manager && ./docker_backup.sh

# Weekly cleanup (remove backups older than 7 days)
0 3 * * 0 cd /opt/qr-code_manager && curl -X POST http://localhost:8066/api/backup/cleanup
```

### Docker Compose Automation

```yaml
# Optional: Backup service with automated scheduling
services:
  backup-scheduler:
    image: alpine:latest
    command: >
      sh -c "
        apk add --no-cache curl &&
        while true; do
          sleep 86400;
          curl -X POST http://qr-manager:5000/api/backup/create;
        done
      "
    depends_on:
      - qr-manager
```

## Security Considerations

### Access Control
- Backup operations require user authentication
- API endpoints validate user permissions
- Backup files are stored with restricted permissions

### Data Protection
- Backups contain sensitive application data
- Store backup files in secure locations
- Consider encryption for long-term storage
- Implement retention policies for compliance

### Network Security
- API endpoints use HTTPS in production
- Validate all input parameters
- Implement rate limiting for backup operations

## Troubleshooting

### Common Issues

#### "Backup creation failed"
- **Cause**: Insufficient disk space or permissions
- **Solution**: Check available space and file permissions
- **Command**: `df -h && ls -la backups/`

#### "Cannot delete backup file"
- **Cause**: File in use or permission denied
- **Solution**: Ensure file is not being accessed
- **Command**: `lsof | grep backup`

#### "Docker backup script not found"
- **Cause**: Script not executable or missing
- **Solution**: Check file exists and permissions
- **Command**: `chmod +x docker_backup.sh`

### Error Codes

| Code | Description | Action |
|------|-------------|---------|
| 200 | Success | Operation completed |
| 400 | Bad Request | Check request parameters |
| 404 | Not Found | Backup file doesn't exist |
| 500 | Server Error | Check logs and permissions |

### Debugging

Enable debug logging:
```bash
export FLASK_ENV=development
export FLASK_DEBUG=1
```

Check container logs:
```bash
docker compose logs qr-manager
```

## Performance Optimization

### Backup Size Optimization
- Implement incremental backups for large datasets
- Compress QR code images efficiently
- Exclude temporary files from backups

### Speed Improvements
- Use parallel compression for large backups
- Implement background processing for web requests
- Cache backup status for faster UI updates

### Storage Management
- Automatic cleanup of old backups
- Configurable retention policies
- External storage integration (S3, etc.)

## API Reference

### Create Backup
```http
POST /api/backup/create
Content-Type: application/json

Response:
{
  "status": "success",
  "message": "Backup creation started",
  "backup_id": "backup_20250801_143022"
}
```

### List Backups
```http
GET /api/backup/list

Response:
{
  "backups": [
    {
      "filename": "backup_20250801_143022.zip",
      "size": "2.5 MB",
      "created": "2025-08-01 14:30:22"
    }
  ]
}
```

### Delete Backup
```http
DELETE /api/backup/delete/backup_20250801_143022.zip

Response:
{
  "status": "success",
  "message": "Backup deleted successfully"
}
```

### Cleanup Old Backups
```http
POST /api/backup/cleanup

Response:
{
  "status": "success",
  "message": "Cleanup completed",
  "deleted_count": 3
}
```

## Changelog

### Version 2.0.0 (August 2025)
- ✅ Added comprehensive backup management system
- ✅ Implemented web-based backup interface
- ✅ Added individual backup deletion
- ✅ Added bulk cleanup functionality
- ✅ Enhanced Docker integration
- ✅ Added real-time status updates
- ✅ Improved error handling and validation

### Version 1.0.0 (Initial Release)
- ✅ Basic backup creation functionality
- ✅ Command-line backup tools
- ✅ Docker support

## Support

For issues or questions regarding the backup system:

1. Check this documentation
2. Review application logs
3. Verify file permissions and disk space
4. Test with minimal data set
5. Create GitHub issue with detailed error information

---

**Note**: Always test backup and restore procedures in a development environment before implementing in production.