# Nextcloud to Backblaze B2 Backup Solution - File Index

## 📍 Where to Start

**New users**: Start with [`README_NEXTCLOUD_BACKUPS.md`](#readmemd)  
**Quick setup**: Jump to [`BACKUP_QUICK_START.md`](#quick-startmd)  
**Detailed reference**: See [`NEXTCLOUD_BACKBLAZE_SETUP.md`](#detailed-setupmd)

---

## 📚 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**:
```bash
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**:
```bash
# 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**:
```bash
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](https://www.backblaze.com/b2/docs/)
- [B2 CLI Command Reference](https://github.com/Backblaze/B2_Command_Line_Tool)
- [Nextcloud Admin Manual](https://docs.nextcloud.com/server/latest/admin_manual/)
- [systemd Timer Documentation](https://www.freedesktop.org/software/systemd/man/systemd.timer.html)

---

**Need help? Start with the documentation guide above!**