homelab-configs/README_NEXTCLOUD_BACKUPS.md

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)

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

sudo ./install-nextcloud-backup.sh

2. Configure B2 Credentials

# Get from https://www.backblaze.com/b2/docs/application_keys.html
sudo nano /etc/nextcloud-backup/b2-credentials.env

3. Configure Nextcloud Details

sudo nano /opt/nextcloud-backup/.env

4. Test Backup

# 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

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:

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

🔍 Monitoring & Logs

# 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

# 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

# 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

# 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

# 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

# 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

# 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
• B2 CLI Reference
• Nextcloud Backup Guide
• systemd Timer Docs

📄 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