homelab-configs/kopia-nextcloud-backblaze-setup.md

# Kopia Backup Configuration for Nextcloud to Backblaze B2

**Date**: April 27, 2026  
**Status**: ✅ Configured and Running  
**Backup Destination**: Backblaze B2  
**Backup Server**: siklos (192.168.88.27)

---

## 📋 Configuration Summary

### Kopia Server Details
- **Container**: Running on siklos via Docker
- **Location**: `/srv/docker/kopia/`
- **Web UI**: http://192.168.88.27:51515
- **Status**: ✅ Running and configured with B2

### Backblaze B2 Backend
- **Bucket**: jg-kopia-nextcloud
- **Bucket ID**: 42c2db92c477c1fe95df0019
- **Key ID**: 00522b2471e5f090000000003
- **Connection**: ✅ Active and tested
- **Encryption**: AES256-GCM-HMAC-SHA256

### Backup Sources
| Source | Location | Size | Content |
|--------|----------|------|---------|
| **Nextcloud Data** | /data (mounted from /mnt/nextcloud) | ~600GB+ | User files, appdata, config |
| **Database Backup** | /data/nextcloud-db-backup.sql | ~1.1GB | MariaDB database backup |
| **Warm Storage Files** | /data/lvm-*.img | ~630GB | LVM backup staging files |

---

## 🔧 Current Setup

### Repository Configuration
```
Hash Algorithm:         BLAKE2B-256-128
Encryption:             AES256-GCM-HMAC-SHA256
Key Derivation:         scrypt-65536-8-1
Splitter:               DYNAMIC-4M-BUZHASH
Repository Password:    kopia123
```

### Default Retention Policy
```
Annual snapshots:       3
Monthly snapshots:      24
Weekly snapshots:       4
Daily snapshots:        7
Hourly snapshots:       48
Latest snapshots:       10
```

### Kopia Server Maintenance
- Quick maintenance: Every 1 hour
- Full maintenance: Every 24 hours
- Server runs as: root

---

## 🚀 Accessing Kopia

### Web UI Access
1. Open browser: http://192.168.88.27:51515
2. Default credentials configured in docker-compose.yml
3. Create snapshots, view backup history, restore files

### Command Line (via Docker)
```bash
# Access Kopia CLI
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia --help

# Create a snapshot
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia snapshot create /data

# List snapshots
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia snapshot list /data

# Restore a file
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia restore --target /tmp/restore-dir <snapshot-id>
```

---

## 📊 Backup Strategy

### Full Data Backup
- **What**: Entire /data directory (Nextcloud files + database backup)
- **Size**: ~630GB (initial backup will be largest)
- **Schedule**: Manual for now (can be automated)
- **Incremental**: Subsequent backups only capture changes

### Database Strategy
Two approaches available:

#### Option A: File-Based (Current)
- Database backup exported as SQL file: `nextcloud-db-backup.sql`
- Included in Kopia snapshots
- Restore: Import SQL file to recover database

#### Option B: Pre-Backup Hook (Recommended)
Create a backup policy that runs MySQL dump before snapshotting:
```bash
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia policy set /data \
  --pre-snapshot-command="mysqldump -h 192.168.88.62 -u nextcloud -p<password> nextcloud > /data/nextcloud-db-backup.sql"
```

---

## 🔄 Backup Workflow

### Manual Snapshot (Current)
```bash
# SSH to siklos
ssh jgitta@siklos

# Create snapshot of all Nextcloud data
cd /srv/docker/kopia
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia snapshot create /data

# Monitor progress
docker logs -f kopia

# List snapshots
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia snapshot list /data
```

### Automated Snapshots (TODO)
Can be configured using Kopia's policy scheduling:
```bash
# Set daily snapshots at 2 AM
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia policy set /data \
  --snapshot-interval=24h --snapshot-time=02:00
```

---

## 💾 Backup Verification

### Check Backblaze B2 Bucket
1. Log into Backblaze B2 account
2. Navigate to bucket: `jg-kopia-nextcloud`
3. Should see files beginning to upload
4. Monitor transfer progress

### Verify Kopia Connection
```bash
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia repository validate-provider
```

### Check Backup Status
```bash
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia snapshot list

# Detailed snapshot info
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia snapshot show <snapshot-id>
```

---

## 🎯 Capacity Analysis

### Nextcloud Backup Size
- **Initial Backup**: ~630GB (first snapshot)
- **Incremental**: Varies based on changes
- **B2 Storage**: Unlimited (you pay per GB/month)
- **Estimated Monthly**: $1-2 for incremental changes

### Backblaze B2 Costs
- Upload: $0.60/GB (initial upload)
- Download: $0.03/GB
- Storage: $0.006/GB-month
- First 1GB free per day

---

## 🔐 Security

### Encryption
- ✅ All backups encrypted with AES256-GCM
- ✅ Keys are hashed using scrypt
- ✅ Repository password protected

### Access Control
- Repository password: `kopia123` (change recommended)
- Server credentials: Configured in docker-compose.yml
- B2 API Key: Limited scope (read/write to bucket only)

### Recommendations
1. **Change repository password**:
   ```bash
   docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia repo change-password
   ```

2. **Update server credentials** in docker-compose.yml

3. **Use environment variables** instead of hardcoding secrets:
   ```bash
   export KOPIA_PASSWORD='secure-password-here'
   ```

---

## 📞 Restore Procedure

### Restore Entire Snapshot
```bash
# List available snapshots
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia snapshot list /data

# Restore to /tmp/restore-dir
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia restore \
  --target /tmp/restore-dir \
  <snapshot-id>
```

### Restore Specific Files
```bash
# Find file in snapshot
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia find <filename>

# Restore specific file
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia restore \
  --target /tmp/restore-file \
  <snapshot-id>/<file-path>
```

### Restore to Nextcloud VM
```bash
# SSH to restore location
ssh jgitta@next

# Mount Kopia via SFTP or restore locally
# Then copy restored files back to Nextcloud
```

---

## 📈 Monitoring & Maintenance

### Daily Checks
```bash
# Container health
docker ps | grep kopia

# Recent logs
docker logs -n 50 --tail=50 -f kopia

# Snapshot listing
docker exec -e KOPIA_PASSWORD='kopia123' kopia kopia snapshot list /data
```

### Monthly Tasks
- Review backup success rate
- Check Backblaze B2 storage usage
- Test restore procedures (at least monthly)
- Review and update retention policies if needed

### Quarterly Tasks
- Full test restore to alternate location
- Review backup costs
- Audit repository integrity: `kopia repository validate-provider`

---

## 🔗 Integration with Existing Setup

### Current Backup Architecture
```
Nextcloud (192.168.88.62)
├─ MariaDB database
├─ /mnt/nextcloud-data (2TB)
└─ Existing tar backup script (to warm storage)

Kopia (siklos - 192.168.88.27)
├─ Backs up entire /data directory
├─ Includes database backups
└─ Uploads to Backblaze B2

Warm Storage (1.4TB)
├─ Temporary backup staging
└─ Used by existing backup script
```

### Benefits of Kopia
- ✅ Deduplication (saves storage space)
- ✅ Incremental backups (faster than full)
- ✅ Point-in-time restore (any snapshot in history)
- ✅ Encryption (security)
- ✅ B2 integration (cost-effective)

---

## 🚨 Troubleshooting

### Container won't start
```bash
cd /srv/docker/kopia
docker-compose logs kopia
docker-compose down && docker-compose up -d
```

### Cannot connect to B2
- Verify credentials: Bucket ID, Key ID, Application Key
- Check network connectivity: `curl https://api.backblazeb2.com`
- Verify bucket exists in B2 account

### Snapshots failing
- Check disk space: `df -h /srv/docker/kopia/`
- Check source accessibility: `ls -la /srv/docker/kopia/`
- Review logs: `docker logs kopia`

### Slow backups
- Normal for initial 600GB+ backup
- Adjust `Parallel uploads` policy if needed
- Consider scheduling during off-peak hours

---

## 📚 Documentation Links

- Kopia Documentation: https://kopia.io/docs/
- Backblaze B2 API: https://www.backblaze.com/b2/docs/
- Docker Compose: https://docs.docker.com/compose/

---

## ✅ Setup Checklist

- ✅ Kopia installed and running on siklos
- ✅ Backblaze B2 repository created
- ✅ Repository configured with AES256 encryption
- ✅ Backup source mounted (/mnt/nextcloud → /data)
- ✅ Database backup file present
- ⏳ Initial snapshot in progress
- 📋 Schedule automated snapshots (TODO)
- 📋 Test restore procedure (TODO)
- 📋 Update security credentials (TODO)
- 📋 Configure pre-backup hooks (TODO)

---

**Status**: Ready for continuous backup operations  
**Last Updated**: April 27, 2026  
**Backup Destination**: Backblaze B2 (jg-kopia-nextcloud)  
**Server**: siklos at 192.168.88.27:51515