homelab-configs/INDEX.md

Nextcloud to Backblaze B2 Backup Solution - File Index

📍 Where to Start

New users: Start with README_NEXTCLOUD_BACKUPS.md
Quick setup: Jump to BACKUP_QUICK_START.md
Detailed reference: See NEXTCLOUD_BACKBLAZE_SETUP.md

---

📚 Documentation Files

README_NEXTCLOUD_BACKUPS.md

• Overview of the complete solution
• Features at a glance
• System requirements
• How it works (visual flow)
• Cost estimates
• File structure after installation
• Quick reference for common commands
• Support and troubleshooting pointers

Use this: First time setup, getting overview

---

BACKUP_QUICK_START.md

• 5-minute installation guide
• TL;DR version of everything
• Common commands reference
• File locations
• Troubleshooting shortcuts
• Cost summary

Use this: When you want to get running fast, or need quick reference

---

NEXTCLOUD_BACKBLAZE_SETUP.md

• Complete step-by-step installation
• Detailed backup strategy explanation
• Usage patterns and best practices
• Restore procedures (detailed)
• Troubleshooting with solutions
• Advanced configuration options
• Cost optimization guide
• Maintenance schedules
• References and links

Use this: Installation issues, restore procedures, advanced config, cost optimization

---

🔧 Installation & Configuration Files

install-nextcloud-backup.sh

Automated installation script that:

• Checks dependencies (docker, b2, jq, etc.)
• Creates directories
• Installs backup scripts
• Installs systemd files
• Creates configuration templates
• Provides step-by-step guidance

How to use:

sudo ./install-nextcloud-backup.sh

---

nextcloud-backup-to-backblaze.sh

Main backup execution script that:

• Dumps Nextcloud database (MariaDB or PostgreSQL)
• Finds changed files (incremental) or all files (full)
• Compresses with zstd
• Uploads to Backblaze B2
• Manages retention (deletes old backups)
• Maintains state for incremental backups
• Logs all operations

How to use:

# After installation
sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh [incremental|full]
sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh status

---

nextcloud-backup.env.template

Configuration template for Nextcloud backup settings:

• Nextcloud paths and database credentials
• Backblaze B2 settings (moved to separate file for security)
• Backup strategy (full vs incremental)
• Retention and compression options
• Logging configuration

How to use:

1. Copy to /opt/nextcloud-backup/.env
2. Edit with your values
3. Referenced automatically by backup script

---

nextcloud-backup.service

systemd service unit for running the backup script:

• Defines how backup is executed
• Sets environment variables
• Configures logging
• Sets resource limits
• Configures restart behavior
• Hardened security settings

Installed to: /etc/systemd/system/nextcloud-backup.service

---

nextcloud-backup.timer

systemd timer unit for scheduling:

• Runs backup daily at 2 AM (configurable)
• Persistent scheduling (runs if missed)
• Randomized start time (avoid thundering herd)
• Requires nextcloud-backup.service

Installed to: /etc/systemd/system/nextcloud-backup.timer

How to manage:

sudo systemctl enable nextcloud-backup.timer
sudo systemctl start nextcloud-backup.timer
sudo systemctl status nextcloud-backup.timer
sudo systemctl list-timers nextcloud-backup.timer

---

🔐 Security Files (Created During Installation)

/etc/nextcloud-backup/b2-credentials.env

Stores Backblaze B2 API credentials:

• Account ID
• Application Key
• Bucket name
• Region

Important:

• Permissions: 600 (root only)
• Never commit to git
• Keep separate from other configs
• Rotate keys annually

---

📊 Runtime Files (Created During Backups)

/opt/nextcloud-backup/.env

Your edited configuration file with Nextcloud details

/opt/nextcloud-backup/.backups/.backup-state.json

Metadata about last backup:

• Last backup timestamp
• Backup type (incremental/full)
• Compression method
• Used for incremental backup logic

/opt/nextcloud-backup/.backups/logs/backup_*.log

Detailed logs of each backup run:

• Timestamps
• Success/error messages
• File counts
• Upload status
• Cleanup results

---

🎯 Quick File Reference

File	Purpose	Edit?	Location
install-nextcloud-backup.sh	Installation	No	Current dir
nextcloud-backup-to-backblaze.sh	Backup execution	No	/opt/nextcloud-backup/
nextcloud-backup.env.template	Config template	→ Copy & edit	Current dir
nextcloud-backup.service	systemd service	Rarely	/etc/systemd/system/
nextcloud-backup.timer	systemd timer	Maybe	/etc/systemd/system/
.env (your copy)	Configuration	Yes!	/opt/nextcloud-backup/
b2-credentials.env	B2 secrets	Yes!	/etc/nextcloud-backup/

---

📋 Documentation Map

README_NEXTCLOUD_BACKUPS.md
├─ Overview & features
├─ System requirements
├─ Quick start
├─ How it works
├─ Cost estimates
├─ File structure
└─ Common commands

BACKUP_QUICK_START.md
├─ 5-minute install
├─ Common commands
├─ File locations
├─ Restore quick reference
└─ Troubleshooting

NEXTCLOUD_BACKBLAZE_SETUP.md
├─ Prerequisites
├─ Installation steps
├─ Backup strategy details
├─ Usage patterns
├─ Restore procedures
├─ Troubleshooting (detailed)
├─ Monitoring & alerts
├─ Advanced configuration
├─ Maintenance schedule
└─ References

---

🚀 Typical Workflow

Initial Setup

1. Read: README_NEXTCLOUD_BACKUPS.md
2. Run: sudo ./install-nextcloud-backup.sh
3. Edit: /opt/nextcloud-backup/.env
4. Edit: /etc/nextcloud-backup/b2-credentials.env
5. Test: sudo /opt/nextcloud-backup/nextcloud-backup-to-backblaze.sh incremental
6. Enable: sudo systemctl enable nextcloud-backup.timer

Daily Use

• Automatic backups run daily at 2 AM
• Monitor: sudo systemctl status nextcloud-backup.timer
• Check: sudo journalctl -u nextcloud-backup.service -n 20

When Restoring

1. See: BACKUP_QUICK_START.md → Restore section
2. Or detailed: NEXTCLOUD_BACKBLAZE_SETUP.md → Restoring section

Troubleshooting

1. Check: BACKUP_QUICK_START.md → Troubleshooting
2. If still stuck: NEXTCLOUD_BACKBLAZE_SETUP.md → Troubleshooting

---

📞 Help Matrix

Question	See
How do I install this?	BACKUP_QUICK_START.md (quick) or install-nextcloud-backup.sh (automated)
What does this do?	README_NEXTCLOUD_BACKUPS.md
How much will it cost?	README_NEXTCLOUD_BACKUPS.md → Costs section
How do I configure it?	BACKUP_QUICK_START.md or NEXTCLOUD_BACKBLAZE_SETUP.md
How do I test it?	BACKUP_QUICK_START.md → Test Backup
How do I restore?	BACKUP_QUICK_START.md or NEXTCLOUD_BACKBLAZE_SETUP.md → Restore
It's not working	BACKUP_QUICK_START.md → Troubleshooting
Advanced config	NEXTCLOUD_BACKBLAZE_SETUP.md → Advanced Configuration
I want details	NEXTCLOUD_BACKBLAZE_SETUP.md (comprehensive)

---

🎓 Learning Path

Beginner (Just want it working)

1. README_NEXTCLOUD_BACKUPS.md - 10 min read
2. Run install-nextcloud-backup.sh - 5 min
3. Edit configs - 5 min
4. Done!

Intermediate (Want to understand it)

1. README_NEXTCLOUD_BACKUPS.md - 10 min
2. BACKUP_QUICK_START.md - 5 min
3. Run installer - 5 min
4. Manual test - 10 min

Advanced (Full control & optimization)

1. All docs + deep dive
2. Customize configs
3. Implement monitoring
4. Optimize costs
5. Custom schedules

---

📄 Version Info

• Created: April 25, 2026
• Tested with: Nextcloud 26+, Backblaze B2, Docker
• Backup script version: 1.0
• Installer version: 1.0

---

✅ Verification Checklist

After installation, verify:

• Scripts installed to /opt/nextcloud-backup/
• systemd files installed to /etc/systemd/system/
• B2 credentials in /etc/nextcloud-backup/b2-credentials.env
• Nextcloud config in /opt/nextcloud-backup/.env
• Manual backup runs successfully
• Timer enabled: sudo systemctl status nextcloud-backup.timer
• Logs available: sudo journalctl -u nextcloud-backup.service
• B2 backups visible: b2 list-file-names

---

🔗 External Resources

• Backblaze B2 Documentation
• B2 CLI Command Reference
• Nextcloud Admin Manual
• systemd Timer Documentation

---

Need help? Start with the documentation guide above!