qr-code_manager/BACKUP_GUIDE.md

QR Code Manager - Backup System

The QR Code Manager includes a comprehensive backup system to protect your data and ensure business continuity. This document explains how to use the backup features effectively.

📋 Overview

The backup system provides three types of backups:

• Data Backup 📄: QR codes, link pages, and short URLs (recommended for regular backups)
• Config Backup ⚙️: Configuration files and environment settings
• Full Backup 📦: Complete application backup including all files

🛠️ Backup Methods

1. Web Interface (Recommended)

Access the backup management interface through the main dashboard:

1. Login to your QR Code Manager
2. Click the "🛡️ Backup" button in the top-right corner
3. Use the web interface to create, download, and manage backups

Features:

• Visual backup status dashboard
• One-click backup creation
• Direct backup downloads
• Backup history and file sizes

2. Python Script

Use the dedicated backup script for command-line operations:

# Data backup (default)
python3 backup.py

# Specific backup types
python3 backup.py --data-only
python3 backup.py --config
python3 backup.py --full

# List available backups
python3 backup.py --list

# Restore from backup
python3 backup.py --restore backup_file.tar.gz

# Automated backup (for cron)
python3 backup.py --auto

# Cleanup old backups
python3 backup.py --cleanup 10

3. Docker Script

For Docker deployments, use the Docker-specific backup script:

# Make script executable
chmod +x docker_backup.sh

# Data backup
./docker_backup.sh backup-data

# Full backup  
./docker_backup.sh backup-full

# List backups
./docker_backup.sh list

# Restore from backup
./docker_backup.sh restore backup_file.tar.gz

# Cleanup old backups
./docker_backup.sh cleanup 5

# Set up automated backups
./docker_backup.sh schedule

⏰ Automated Backups

Using Cron (Linux/macOS)

1. Set up automated backups:

   ./docker_backup.sh schedule
   

2. Or manually add to crontab (crontab -e):

   # Daily data backup at 2 AM
   0 2 * * * /path/to/qr-code_manager/docker_backup.sh backup-data >> /path/to/backup.log 2>&1
   
   # Weekly full backup on Sundays at 3 AM
   0 3 * * 0 /path/to/qr-code_manager/docker_backup.sh backup-full >> /path/to/backup.log 2>&1
   

Using Python Auto Mode

The Python script includes an intelligent auto mode:

# Add to cron for smart automated backups
0 2 * * * cd /path/to/qr-code_manager && python3 backup.py --auto >> backup.log 2>&1

Auto mode behavior:

• Daily: Data backup
• Monday: Data + Config backup
• 1st of month: Data + Config + Full backup
• Automatic cleanup of old backups

📁 Backup Storage

Default Location

All backups are stored in the backups/ directory within your QR Code Manager installation.

Backup Files

• Data backups: qr_data_backup_YYYYMMDD_HHMMSS.tar.gz
• Config backups: qr_config_backup_YYYYMMDD_HHMMSS.tar.gz
• Full backups: qr_full_backup_YYYYMMDD_HHMMSS.tar.gz

Metadata Files

Each backup includes a JSON metadata file with:

• Backup type and timestamp
• Application version
• File list and sizes
• Backup method used

🔄 Restore Process

Web Interface Restore

Currently, the web interface provides backup download. For restoration:

1. Download the desired backup file
2. Use command-line restore methods below

Command Line Restore

# Python script restore
python3 backup.py --restore backup_file.tar.gz

# Docker script restore  
./docker_backup.sh restore backup_file.tar.gz

Manual Restore

1. Stop the application:

   docker compose down
   

2. Backup current data (safety):

   mv data data.backup.$(date +%Y%m%d_%H%M%S)
   

3. Extract backup:

   tar xzf backup_file.tar.gz
   

4. Restart application:

   docker compose up -d
   

🔐 Security Considerations

Backup Content

• Data backups contain QR codes, links, and URLs (may include sensitive information)
• Config backups contain environment variables and settings (may include passwords)
• Full backups contain entire application including source code

Best Practices

1. Encrypt backups for off-site storage
2. Secure backup storage with appropriate access controls
3. Regular backup testing to ensure restoration works
4. Monitor backup logs for failures
5. Rotate backup files to manage storage space

Encryption Example

# Encrypt backup for storage
gpg --symmetric --cipher-algo AES256 backup_file.tar.gz

# Decrypt when needed
gpg backup_file.tar.gz.gpg

📊 Monitoring

Backup Status

Monitor backup health through:

1. Web Interface: Real-time status dashboard
2. Log Files: backup.log for automated backups
3. API Endpoints: /api/backup/status for integration

Key Metrics

• Total number of backups
• Last backup timestamp
• Data directory size
• Total backup storage used
• Backup success/failure rates

🚨 Disaster Recovery

Complete System Failure

1. Prepare new environment:

   git clone <your-repo>
   cd qr-code_manager
   

2. Restore from full backup:

   ./docker_backup.sh restore qr_full_backup_latest.tar.gz
   

3. Verify configuration:

   • Check environment variables
   • Update domain settings if needed
   • Test database connections

4. Start services:

   docker compose up -d
   

Data Corruption

1. Stop services:

   docker compose down
   

2. Restore data only:

   ./docker_backup.sh restore qr_data_backup_latest.tar.gz
   

3. Restart services:

   docker compose up -d
   

🔧 Troubleshooting

Common Issues

Permission Errors:

chmod +x backup.py docker_backup.sh

Docker Not Found:

# Check Docker installation
docker --version
docker compose version

Backup Script Fails:

# Check Python dependencies
python3 -c "import tarfile, json, pathlib"

# Check disk space
df -h

Large Backup Files: Consider data cleanup before backup:

python3 clean_data.py

Getting Help

1. Check the application logs: docker compose logs
2. Review backup logs: tail -f backup.log
3. Test backup creation manually
4. Verify file permissions and disk space

📈 Best Practices

Backup Strategy

• Daily: Data backups (automated)
• Weekly: Config backups
• Monthly: Full backups
• Before updates: Create full backup

Storage Management

• Keep last 15 daily backups
• Keep last 8 weekly backups
• Keep last 12 monthly backups
• Archive yearly backups off-site

Testing

• Monthly restore tests
• Document restore procedures
• Train team on backup/restore process
• Test disaster recovery scenarios

---

💡 Remember: The best backup is one that has been tested! Regularly verify your backups can be restored successfully.