🔄 Add Comprehensive Backup Management System
✨ New Features: - Complete backup lifecycle management (create, list, download, delete, cleanup) - Web-based backup interface with real-time status updates - Individual backup deletion and bulk cleanup for old backups - Docker-aware backup operations with volume persistence - Automated backup scheduling and retention policies 📁 Added Files: - backup.py - Core backup script for creating timestamped archives - docker_backup.sh - Docker-compatible backup wrapper script - app/templates/backup.html - Web interface for backup management - BACKUP_SYSTEM.md - Comprehensive backup system documentation - BACKUP_GUIDE.md - Quick reference guide for backup operations 🔧 Enhanced Files: - Dockerfile - Added backup.py copy for container availability - docker-compose.yml - Added backup volume mount for persistence - app/routes/api.py - Added backup API endpoints (create, list, delete, cleanup) - app/routes/main.py - Added backup management route - app/templates/index.html - Added backup management navigation - README.md - Updated with backup system overview and quick start 🎯 Key Improvements: - Fixed backup creation errors in Docker environment - Added Docker-aware path detection for container operations - Implemented proper error handling and user confirmation dialogs - Added real-time backup status updates via JavaScript - Enhanced data persistence with volume mounting 💡 Use Cases: - Data protection and disaster recovery - Environment migration and cloning - Development data management - Automated maintenance workflows
This commit is contained in:
313
BACKUP_GUIDE.md
Normal file
313
BACKUP_GUIDE.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
./docker_backup.sh schedule
|
||||
```
|
||||
|
||||
2. Or manually add to crontab (`crontab -e`):
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
2. Backup current data (safety):
|
||||
```bash
|
||||
mv data data.backup.$(date +%Y%m%d_%H%M%S)
|
||||
```
|
||||
|
||||
3. Extract backup:
|
||||
```bash
|
||||
tar xzf backup_file.tar.gz
|
||||
```
|
||||
|
||||
4. Restart application:
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
git clone <your-repo>
|
||||
cd qr-code_manager
|
||||
```
|
||||
|
||||
2. **Restore from full backup**:
|
||||
```bash
|
||||
./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**:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Data Corruption
|
||||
|
||||
1. **Stop services**:
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
2. **Restore data only**:
|
||||
```bash
|
||||
./docker_backup.sh restore qr_data_backup_latest.tar.gz
|
||||
```
|
||||
|
||||
3. **Restart services**:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Permission Errors:**
|
||||
```bash
|
||||
chmod +x backup.py docker_backup.sh
|
||||
```
|
||||
|
||||
**Docker Not Found:**
|
||||
```bash
|
||||
# Check Docker installation
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
**Backup Script Fails:**
|
||||
```bash
|
||||
# Check Python dependencies
|
||||
python3 -c "import tarfile, json, pathlib"
|
||||
|
||||
# Check disk space
|
||||
df -h
|
||||
```
|
||||
|
||||
**Large Backup Files:**
|
||||
Consider data cleanup before backup:
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user