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:

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

   pip install -r requirements.txt
   

2. Create backup directory:

   mkdir -p backups
   

3. Set appropriate permissions:

   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

# Direct execution
python backup.py

# Docker execution
./docker_backup.sh

Via API

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:

   docker compose down
   

2. Extract backup:

   cd data/
   unzip ../backups/backup_YYYYMMDD_HHMMSS.zip
   

3. Restart application:

   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:

# 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

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

export FLASK_ENV=development
export FLASK_DEBUG=1

Check container logs:

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

POST /api/backup/create
Content-Type: application/json

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

List Backups

GET /api/backup/list

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

Delete Backup

DELETE /api/backup/delete/backup_20250801_143022.zip

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

Cleanup Old Backups

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.