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:

```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.