# Nextcloud Automated Backups to Backblaze B2

Complete solution for automated, periodic backups of your Nextcloud instance to Backblaze B2 cloud storage.

## 📦 What's Included

This package contains everything needed to set up automated Nextcloud backups:

### Scripts & Configuration
- **`nextcloud-backup-to-backblaze.sh`** - Main backup script (intelligent incremental/full backups)
- **`install-nextcloud-backup.sh`** - One-command installation script
- **`nextcloud-backup.service`** - systemd service file
- **`nextcloud-backup.timer`** - systemd timer for daily backups
- **`nextcloud-backup.env.template`** - Configuration template

### Documentation
- **`BACKUP_QUICK_START.md`** - 5-minute setup guide (start here!)
- **`NEXTCLOUD_BACKBLAZE_SETUP.md`** - Complete detailed documentation
- **`README_NEXTCLOUD_BACKUPS.md`** - This file

## 🚀 Quick Start (Choose One)

### Option A: Automated Installation (Recommended)
```bash
chmod +x install-nextcloud-backup.sh
sudo ./install-nextcloud-backup.sh
```
Then follow the prompts.

### Option B: Manual Installation
1. Read `BACKUP_QUICK_START.md`
2. Run step-by-step commands
3. Customize configuration as needed

## 📋 System Requirements

- Linux system with systemd
- Docker & Docker Compose (running Nextcloud)
- ~10GB free disk space
- Root/sudo access
- B2 account with API credentials

## 🔄 How It Works

```
┌─────────────────────────────────────────────────────────────┐
│  Every Day at 2 AM (configurable)                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. systemd timer triggers nextcloud-backup.service         │
│                                                              │
│  2. Script dumps Nextcloud database                          │
│     ├─ MariaDB: mysqldump                                   │
│     └─ PostgreSQL: pg_dump                                  │
│                                                              │
│  3. Script finds changed files (incremental backup)         │
│     └─ Or all files (full backup)                           │
│                                                              │
│  4. Archives and compresses (zstd compression)              │
│     └─ Reduces size by 40-70%                               │
│                                                              │
│  5. Uploads to Backblaze B2                                 │
│     ├─ Database backup                                      │
│     └─ Files archive                                        │
│                                                              │
│  6. Cleans up old backups (>30 days by default)            │
│                                                              │
│  7. Logs results and updates state                          │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## 💾 What Gets Backed Up

✅ **All Nextcloud files** (user documents, photos, videos)  
✅ **Database** (all settings, user accounts, sharing)  
✅ **Metadata** (file permissions, timestamps)  

## 💰 Estimated Costs

Based on Backblaze B2 pricing (as of 2024):

| Size | Compressed | Monthly Storage | Annual |
|------|-----------|-----------------|--------|
| 50GB | 15-20GB | $0.09-0.12 | $1.08-1.44 |
| 100GB | 30-40GB | $0.18-0.24 | $2.16-2.88 |
| 500GB | 150-200GB | $0.90-1.20 | $10.80-14.40 |

*Plus minimal API costs ($0.0004 per 1000 calls)*

## 🔧 Installation Steps

### 1. Run Installer
```bash
sudo ./install-nextcloud-backup.sh
```

### 2. Configure B2 Credentials
```bash
# Get from https://www.backblaze.com/b2/docs/application_keys.html
sudo nano /etc/nextcloud-backup/b2-credentials.env
```

### 3. Configure Nextcloud Details
```bash
sudo nano /opt/nextcloud-backup/.env
```

### 4. Test Backup
```bash
# Dry run (no upload)
sudo DRY_RUN=true /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh

# Real backup
sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh incremental
```

### 5. Enable Automation
```bash
sudo systemctl enable nextcloud-backup.timer
sudo systemctl start nextcloud-backup.timer
```

**Total time: ~10 minutes**

## 📊 Backup Features

### Intelligent Backups
- **Incremental** - Only back up changed files (daily, fast)
- **Full** - Complete snapshot (weekly, thorough)
- **Compression** - zstd reduces size 40-70%
- **Retention** - Auto-delete old backups (configurable)

### Reliability
- Database is dumped before file backup
- Atomic transactions for consistency
- Automatic error recovery
- Detailed logging

### Monitoring
- systemd integration (logs to journalctl)
- Status commands to check backups
- Dry-run mode for testing
- Email alerts on failure (optional)

## 📁 File Structure

After installation:

```
/opt/nextcloud-backup/
├── .env                          # ← Edit your config here
├── .backups/
│   ├── logs/                     # Backup logs
│   └── .backup-state.json       # Last backup metadata
└── nextcloud-backup-to-backblaze.sh

/etc/nextcloud-backup/
└── b2-credentials.env            # ← Add B2 credentials here

/etc/systemd/system/
├── nextcloud-backup.service
└── nextcloud-backup.timer
```

## 🔐 Security Features

- B2 credentials stored separately (chmod 600)
- Credentials not in logs or scripts
- Backup script runs as root with restrictions
- Automatic credential rotation support
- Secure deletion of temporary files

## ⏰ Default Schedule

**Daily at 2 AM** (configurable)

To change:
```bash
sudo nano /etc/systemd/system/nextcloud-backup.timer
# Modify OnCalendar= line
sudo systemctl daemon-reload
sudo systemctl restart nextcloud-backup.timer
```

## 🔍 Monitoring & Logs

```bash
# Check last backup
sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh status

# View recent logs
sudo tail -f /opt/nextcloud-backup/.backups/logs/backup_*.log

# systemd logs
sudo journalctl -u nextcloud-backup.service -n 50

# Live monitoring
sudo journalctl -u nextcloud-backup.service -f
```

## ✅ Manual Backup Commands

```bash
# Incremental (changed files only)
sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh incremental

# Full (all files)
sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh full

# Dry run (test without upload)
sudo DRY_RUN=true /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh

# Status check
sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh status
```

## 🔄 Restore Instructions

### Quick Restore Database
```bash
# Get backup ID
b2 list-file-names nextcloud-backups nextcloud-backups/

# Download & restore
b2 download-file-by-id nextcloud-backups <ID> - | \
  zstd -d | mysql -u root -p nextcloud
```

### Restore Files
```bash
# Download
b2 download-file-by-id nextcloud-backups <ID> backup.tar.zst

# Extract to /tmp for review
tar --zstd -xf backup.tar.zst -C /tmp

# Copy back (careful!)
cp -r /tmp/srv/docker/nextcloud/data/* /srv/docker/nextcloud/data/
```

See `NEXTCLOUD_BACKBLAZE_SETUP.md` for detailed restore procedures.

## 🐛 Troubleshooting

### Backup Not Running
```bash
# Check timer status
sudo systemctl status nextcloud-backup.timer

# Enable if needed
sudo systemctl enable --now nextcloud-backup.timer

# Check logs
sudo journalctl -u nextcloud-backup.timer -n 50
```

### B2 Authentication Failed
```bash
# Test connection
b2 account-info

# Re-authenticate
b2 authorize-account <ACCOUNT_ID> <APP_KEY>

# Verify credentials file
cat /etc/nextcloud-backup/b2-credentials.env
```

### Backup Script Errors
```bash
# Check logs
sudo tail -100 /opt/nextcloud-backup/.backups/logs/backup_*.log

# Test manually
sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh incremental

# Check permissions
sudo ls -la /srv/docker/nextcloud/data | head -5
```

See `NEXTCLOUD_BACKBLAZE_SETUP.md` for more troubleshooting.

## 🎯 Configuration Options

### Backup Frequency
- Edit `/etc/systemd/system/nextcloud-backup.timer`
- Change `OnCalendar=` for different schedule

### Backup Retention
- Edit `/opt/nextcloud-backup/.env`
- Change `BACKUP_RETENTION_DAYS=30`

### Compression
- Edit `/opt/nextcloud-backup/.env`
- Options: `zstd` (fast), `gzip` (compatible), `bzip2` (slow)

### Database Type
- Auto-detected (MariaDB or PostgreSQL)
- Credentials in `/opt/nextcloud-backup/.env`

## 📚 Documentation

- **Quick Start**: `BACKUP_QUICK_START.md` ← Start here!
- **Full Guide**: `NEXTCLOUD_BACKBLAZE_SETUP.md`
- **This File**: `README_NEXTCLOUD_BACKUPS.md`

## 🆘 Support

### Common Issues
1. See `BACKUP_QUICK_START.md` troubleshooting section
2. Check logs: `sudo journalctl -u nextcloud-backup.service -n 100`
3. Test manually: `sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh`

### Getting Help
- Review logs for error messages
- Check B2 account for uploads
- Verify file permissions
- Test B2 credentials: `b2 account-info`

## 🔗 References

- [Backblaze B2 Docs](https://www.backblaze.com/b2/docs/)
- [B2 CLI Reference](https://github.com/Backblaze/B2_Command_Line_Tool)
- [Nextcloud Backup Guide](https://docs.nextcloud.com/server/latest/admin_manual/)
- [systemd Timer Docs](https://www.freedesktop.org/software/systemd/man/systemd.timer.html)

## 📄 License

These scripts are provided as-is for use with Nextcloud and Backblaze B2.

## ✨ Features at a Glance

| Feature | Status |
|---------|--------|
| Automated daily backups | ✅ |
| Incremental & full backups | ✅ |
| Database + files | ✅ |
| Compression | ✅ |
| Retention management | ✅ |
| Easy restoration | ✅ |
| Error logging | ✅ |
| Dry-run testing | ✅ |
| Cost optimization | ✅ |
| Security hardened | ✅ |

---

**Ready to get started?** Open `BACKUP_QUICK_START.md` or run `sudo ./install-nextcloud-backup.sh`