From 91822423f678e9b699137a3c60fb771ae0c20c8d Mon Sep 17 00:00:00 2001 From: Administrator Date: Sat, 14 Feb 2026 23:52:38 +0000 Subject: [PATCH] docs: create nextcloud_backup --- nextcloud_backup.md | 970 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 970 insertions(+) create mode 100644 nextcloud_backup.md diff --git a/nextcloud_backup.md b/nextcloud_backup.md new file mode 100644 index 0000000..5f4e506 --- /dev/null +++ b/nextcloud_backup.md @@ -0,0 +1,970 @@ +--- +title: Nextcloud Backup +description: Native + Kopia +published: true +date: 2026-02-14T23:52:25.405Z +tags: +editor: markdown +dateCreated: 2026-02-14T23:52:25.405Z +--- + +# Nextcloud AIO Backup and Recovery Guide + +## Overview + +This document provides comprehensive backup and recovery procedures for Nextcloud All-in-One (AIO). Nextcloud AIO includes a **built-in BorgBackup solution** that handles database, files, and configuration. We enhance this with Kopia for offsite storage in vaults, following the same two-tier approach used for Mailcow and Immich. + +## Quick Reference + +### Common Backup Commands + +```bash +# Run automated backup script +/opt/scripts/backup-nextcloud.sh + +# Trigger AIO backup manually (via web interface) +# Navigate to: https://your-server:8080 → Backup section → Create Backup + +# List Kopia snapshots +kopia snapshot list --tags nextcloud + +# View backup logs +tail -f /var/log/nextcloud-backup.log + +# Check AIO backup status +docker exec -it nextcloud-aio-mastercontainer bash +ls -lh /mnt/docker-aio-config/data/borg/ +``` + +### Common Restore Commands + +```bash +# Restore using AIO's built-in interface (RECOMMENDED) +# Navigate to: https://your-server:8080 → Backup section → Restore + +# Restore from Kopia to new server +kopia snapshot list --tags nextcloud +kopia restore /opt/nextcloud-backups/ + +# Check container status after restore +docker ps | grep nextcloud +docker logs -f nextcloud-aio-mastercontainer +``` + +## Critical Components to Backup + +### 1. Nextcloud AIO BorgBackup Repository +- **Location**: Docker volume `nextcloud_aio_mastercontainer` → `/mnt/docker-aio-config/data/borg/` +- **Contains**: + - Complete database (PostgreSQL) + - All user files and data + - Nextcloud configuration + - Apps and their data +- **Importance**: This is Nextcloud AIO's primary backup - contains everything needed for restore + +### 2. Nextcloud Data Directory +- **Location**: `/srv/NextCloud-AIO` (per your NEXTCLOUD_DATADIR setting) +- **Purpose**: User files, photos, documents +- **Note**: Already included in AIO BorgBackup, but can be backed up separately with Kopia + +### 3. AIO Mastercontainer Volume +- **Volume**: `nextcloud_aio_mastercontainer` +- **Contains**: AIO configuration, certificates, Borg repository +- **Critical**: Required to restore AIO itself + +### 4. Docker Compose Configuration +- **Location**: `/opt/nextcloud/docker-compose.yml` +- **Purpose**: Container definitions, network settings, environment variables +- **Importance**: Needed to recreate the AIO setup + +### 5. Additional Components +- **Apache Port**: 11000 (your custom port) +- **AIO Admin Interface**: Port 8080 +- **Networks**: `netgrimoire` external network + +## Backup Strategy + +### Two-Tier Backup Approach + +We use a **two-tier approach** combining Nextcloud AIO's native BorgBackup with Kopia for offsite storage: + +1. **Tier 1 (Nextcloud AIO Native)**: BorgBackup creates deduplicated, compressed backups of everything +2. **Tier 2 (Offsite)**: Kopia snapshots the Borg repository and configs to vaults + +#### Why This Approach? + +- **Best of both worlds**: AIO's BorgBackup is Nextcloud-aware and handles everything correctly, Kopia provides offsite protection +- **Native restore**: Use AIO's built-in restore interface (easiest, most reliable) +- **Disaster recovery**: Full system restore from Kopia backups on new server +- **Deduplication at two levels**: Borg deduplicates within Nextcloud data, Kopia deduplicates across backups +- **Proven strategy**: Same approach used for Mailcow and Immich + +#### Backup Frequency +- **AIO BorgBackup**: Configurable in AIO interface (recommend daily at 4 AM) +- **Kopia Tier 2**: Daily at 2 AM (snapshots the Borg repository) +- **Retention (AIO Borg)**: `--keep-within=7d --keep-weekly=4 --keep-monthly=6` (customizable) +- **Retention (Kopia/Offsite)**: 30 daily, 12 weekly, 12 monthly + +### Nextcloud AIO Native Backup (BorgBackup) + +Nextcloud AIO includes an integrated BorgBackup solution that: +- Backs up PostgreSQL database (hot backup, no downtime) +- Backs up all user files and data +- Backs up Nextcloud configuration and apps +- Provides deduplication and compression +- Can be triggered manually or on schedule +- Includes built-in restore interface + +**Key Features:** +- **Deduplication**: Only stores changed blocks (very efficient) +- **Compression**: Reduces backup size significantly +- **Encryption**: Backups are encrypted by default +- **Incremental**: Only backs up changes after first backup +- **Web UI**: Manage backups through AIO's admin interface + +**BorgBackup Location:** +- Inside mastercontainer volume: `/mnt/docker-aio-config/data/borg/` +- On host: `/var/lib/docker/volumes/nextcloud_aio_mastercontainer/_data/data/borg/` + +## Setting Up Nextcloud AIO Backups + +### Prereq: +Make sure you are connected to the repository, + +```bash +sudo kopia repository connect server \ + --url=https://192.168.5.10:51516 \ + --override-username=admin \ + --server-cert-fingerprint=696a4999f594b5273a174fd7cab677d8dd1628f9b9d27e557daa87103ee064b2 +``` + +**Note on Multiple Kopia Repositories**: The backup script handles multiple Kopia repositories by explicitly connecting to the Nextcloud-specific repository at the start of each backup. To use a different repository, edit the variables in `/opt/scripts/backup-nextcloud.sh`. + +#### Step 1: Configure AIO Built-in Backup + +First, configure Nextcloud AIO's built-in backup system: + +1. **Access AIO Admin Interface**: + ``` + https://your-server:8080 + ``` + +2. **Navigate to Backup Section** in the AIO interface + +3. **Configure Backup Settings**: + - **Backup time**: Set to 04:00 (4 AM) to avoid conflicts with Kopia script + - **Retention policy**: Default is good (`--keep-within=7d --keep-weekly=4 --keep-monthly=6`) + - Can be customized with `BORG_RETENTION_POLICY` environment variable in docker-compose + +4. **Verify Backup Location**: + ```bash + # Check that Borg repository exists + ls -lh /var/lib/docker/volumes/nextcloud_aio_mastercontainer/_data/data/borg/ + ``` + +5. **Trigger First Backup** via AIO interface to verify it works + +**Optional: Customize Borg Retention** + +Edit your docker-compose.yml to add: +```yaml +environment: + BORG_RETENTION_POLICY: --keep-within=7d --keep-weekly=4 --keep-monthly=6 +``` + +Then restart: +```bash +cd /opt/nextcloud +docker compose down +docker compose up -d +``` + +#### Step 2: Configure Backup Location + +Create the backup directory for metadata and Kopia: + +```bash +sudo mkdir -p /opt/nextcloud-backups +sudo chown -R root:root /opt/nextcloud-backups +sudo chmod 755 /opt/nextcloud-backups +``` + +#### Step 3: Install Backup Script + +```bash +# Create scripts directory if not exists +sudo mkdir -p /opt/scripts + +# Copy the backup script +sudo cp backup-nextcloud.sh /opt/scripts/ +sudo chmod +x /opt/scripts/backup-nextcloud.sh +``` + +#### Step 4: Configure Backup Script + +Edit `/opt/scripts/backup-nextcloud.sh` and verify these settings: + +```bash +BACKUP_DIR="/opt/nextcloud-backups" # Local backup storage +KEEP_DAYS=7 # Keep 7 days locally +NEXTCLOUD_DIR="/opt/nextcloud" # Your Nextcloud compose location +DATADIR="/srv/NextCloud-AIO" # Your NEXTCLOUD_DATADIR +KOPIA_SERVER_URL="https://192.168.5.10:51516" # Your Kopia server +KOPIA_USERNAME="admin" +KOPIA_FINGERPRINT="696a4999..." +``` + +#### Step 5: Test Manual Backup + +Run your first backup manually: + +```bash +sudo /opt/scripts/backup-nextcloud.sh +``` + +Expected output: +``` +======================================== +Starting Nextcloud AIO backup process +======================================== +[timestamp] Connecting to Kopia repository... +[timestamp] Kopia repository connected successfully +[timestamp] Triggering Nextcloud AIO BorgBackup... +[timestamp] Found 3 BorgBackup archives in AIO +[timestamp] Latest BorgBackup is recent (within 24 hours) +[timestamp] Exporting Nextcloud configuration... +[timestamp] Backing up AIO mastercontainer volume... +[timestamp] Creating Kopia snapshot of backup directory... +... +======================================== +``` + +Verify the backup: +```bash +# Check local backup +ls -lh /opt/nextcloud-backups/ +cat /opt/nextcloud-backups/nextcloud-*/manifest.txt + +# Check Kopia snapshots +kopia snapshot list --tags nextcloud + +# Check AIO Borg backups (via web interface or command line) +docker exec -it nextcloud-aio-mastercontainer ls -lh /mnt/docker-aio-config/data/borg/ +``` + +#### Step 6: Automated Backup with Cron + +**Important Timing**: Schedule this AFTER AIO's built-in backup completes. +- AIO backup: 4:00 AM (configured in AIO interface) +- Kopia script: 5:00 AM (snapshots the completed Borg backup) + +Add to root's crontab: + +```bash +sudo crontab -e +``` + +Add this line for daily backups at 5 AM: +``` +0 5 * * * /opt/scripts/backup-nextcloud.sh 2>&1 | logger -t nextcloud-backup +``` + +Alternative schedules: + +**Twice daily (5 AM and 5 PM):** +``` +0 5,17 * * * /opt/scripts/backup-nextcloud.sh 2>&1 | logger -t nextcloud-backup +``` + +**After AIO backup completes (4 AM AIO + 1 hour buffer):** +``` +0 5 * * * /opt/scripts/backup-nextcloud.sh 2>&1 | logger -t nextcloud-backup +``` + +#### Step 7: Configure Kopia Retention Policy + +Set retention for Nextcloud snapshots: + +```bash +kopia policy set /opt/nextcloud-backups \ + --keep-latest 30 \ + --keep-daily 30 \ + --keep-weekly 12 \ + --keep-monthly 12 + +kopia policy set /opt/nextcloud \ + --keep-latest 7 \ + --keep-daily 7 + +# If backing up datadir directly +kopia policy set /srv/NextCloud-AIO \ + --keep-latest 7 \ + --keep-daily 7 +``` + +## Recovery Procedures + +### Understanding Two Recovery Methods + +We have **two restore methods** depending on the scenario: + +1. **AIO Native Restore** (Preferred): Use AIO's built-in restore interface +2. **Kopia Full Restore**: For complete disaster recovery to a new server + +### Method 1: AIO Native Restore (Recommended) + +Use this method when: +- Restoring on the same server +- AIO is still functional +- You have AIO Borg backups available + +This is the **easiest and most reliable** method for Nextcloud AIO. + +#### Via AIO Web Interface (Easiest) + +1. **Access AIO Admin Interface**: + ``` + https://your-server:8080 + ``` + +2. **Navigate to Backup Section** + +3. **Select Restore** + +4. **Choose Backup Date** from available Borg backups + +5. **Confirm Restore** + - AIO will: + - Stop Nextcloud containers + - Restore database + - Restore all files + - Restore configuration + - Restart containers + +6. **Verify** Nextcloud is working after restore + +#### Via Command Line (Advanced) + +```bash +# Stop Nextcloud (if needed) +docker exec -it nextcloud-aio-mastercontainer \ + /usr/bin/docker-compose -f /path/to/compose.yml down + +# List available Borg backups +docker exec -it nextcloud-aio-mastercontainer \ + borg list /mnt/docker-aio-config/data/borg/borgbackup + +# Restore from specific backup +docker exec -it nextcloud-aio-mastercontainer \ + /restore-script.sh + +# Note: Exact restore commands depend on AIO version +# Recommend using web interface for most reliable restore +``` + +### Method 2: Complete Server Rebuild (Kopia Restore) + +Use this when recovering to a completely new server or when AIO is completely lost. + +#### Step 1: Prepare New Server + +```bash +# Update system +apt update && apt upgrade -y + +# Install Docker +curl -fsSL https://get.docker.com | sh +systemctl enable docker +systemctl start docker + +# Install Docker Compose +apt install docker-compose-plugin -y + +# Install Kopia +curl -s https://kopia.io/signing-key | sudo gpg --dearmor -o /usr/share/keyrings/kopia-keyring.gpg +echo "deb [signed-by=/usr/share/keyrings/kopia-keyring.gpg] https://packages.kopia.io/apt/ stable main" | sudo tee /etc/apt/sources.list.d/kopia.list +apt update +apt install kopia -y + +# Create directory structure +mkdir -p /opt/nextcloud +mkdir -p /opt/nextcloud-backups +mkdir -p /srv/NextCloud-AIO +``` + +#### Step 2: Connect to Kopia Repository + +```bash +# Connect to your offsite vault +kopia repository connect server \ + --url=https://192.168.5.10:51516 \ + --override-username=admin \ + --server-cert-fingerprint=696a4999f594b5273a174fd7cab677d8dd1628f9b9d27e557daa87103ee064b2 + +# Verify connection +kopia repository status + +# List available snapshots +kopia snapshot list --tags nextcloud +``` + +#### Step 3: Restore Configuration + +```bash +# Find and restore the config snapshot +kopia snapshot list --tags config + +# Restore to the Nextcloud directory +kopia restore /opt/nextcloud/ + +# Verify critical files +ls -la /opt/nextcloud/docker-compose.yml +``` + +#### Step 4: Restore AIO Mastercontainer Volume + +```bash +# Find the backup with mastercontainer +kopia snapshot list --tags tier1-backup + +# Restore the most recent backup +kopia restore /opt/nextcloud-backups/ + +# Find the most recent backup directory +LATEST_BACKUP=$(ls -td /opt/nextcloud-backups/nextcloud-* | head -1) +echo "Restoring from: $LATEST_BACKUP" + +# Extract mastercontainer volume backup +docker volume create nextcloud_aio_mastercontainer + +docker run --rm \ + -v nextcloud_aio_mastercontainer:/target \ + -v "${LATEST_BACKUP}":/backup:ro \ + alpine tar -xzf /backup/aio-mastercontainer.tar.gz -C /target + +echo "Mastercontainer volume restored" +``` + +#### Step 5: Restore Borg Repository (Optional but Recommended) + +```bash +# Restore the Borg repository directly from Kopia +kopia snapshot list --tags borg + +# Restore Borg backup to volume location +kopia restore /var/lib/docker/volumes/nextcloud_aio_mastercontainer/_data/data/borg/ +``` + +#### Step 6: Start Nextcloud AIO + +```bash +cd /opt/nextcloud + +# Create external network if needed +docker network create netgrimoire + +# Start mastercontainer +docker compose up -d + +# Monitor logs +docker compose logs -f +``` + +#### Step 7: Access AIO and Restore + +1. **Wait for mastercontainer to initialize** (may take 1-2 minutes) + +2. **Access AIO Interface**: + ``` + https://new-server-ip:8080 + ``` + +3. **If Borg backups were restored** (Step 5): + - Navigate to Backup section + - Select restore from available backup + - AIO will restore everything automatically + +4. **If starting fresh**: + - Follow AIO initial setup + - Restore data from datadir backup if available + +#### Step 8: Post-Restore Verification + +```bash +# Check all containers are running +docker ps | grep nextcloud + +# Expected containers: +# - nextcloud-aio-mastercontainer +# - nextcloud-aio-apache +# - nextcloud-aio-nextcloud +# - nextcloud-aio-database +# - nextcloud-aio-redis +# (and others depending on your setup) + +# Check Nextcloud is accessible +curl -I http://localhost:11000 + +# Access web interface +# https://your-server-domain + +# Verify: +# - Login works +# - Files are accessible +# - Apps are functioning +# - Sharing works +``` + +### Scenario 2: Restore Specific User's Files + +To restore a single user's files without affecting others: + +**Via AIO Web Interface:** + +1. Navigate to Files → Deleted Files (if available) +2. Use Nextcloud's built-in file versioning + +**Via Borg Backup:** + +```bash +# Mount a Borg backup +docker exec -it nextcloud-aio-mastercontainer bash + +# Inside container: +cd /mnt/docker-aio-config/data/borg/ + +# List available backups +borg list borgbackup + +# Mount a specific backup +mkdir -p /tmp/borg-mount +borg mount borgbackup:: /tmp/borg-mount + +# Navigate to user's files +cd /tmp/borg-mount/nextcloud/data//files/ + +# Copy needed files to restore location +cp -r /tmp/borg-mount/nextcloud/data//files/* \ + /actual/nextcloud/data//files/ + +# Unmount +borg umount /tmp/borg-mount +exit + +# Run Nextcloud file scan +docker exec -it nextcloud-aio-nextcloud bash +php occ files:scan +``` + +**Via Kopia (if datadir was backed up):** + +```bash +# Mount Kopia snapshot +kopia snapshot list --tags datadir +mkdir -p /mnt/kopia-nextcloud +kopia mount /mnt/kopia-nextcloud & + +# Find user's files +USER="username" +ls /mnt/kopia-nextcloud/${USER}/files/ + +# Copy files back +rsync -av /mnt/kopia-nextcloud/${USER}/files/ \ + /srv/NextCloud-AIO/${USER}/files/ + +# Unmount +kopia unmount /mnt/kopia-nextcloud + +# Rescan files +docker exec -u www-data -it nextcloud-aio-nextcloud \ + php occ files:scan ${USER} +``` + +### Scenario 3: Database Recovery Only + +If only the database is corrupted: + +**Via AIO Interface (Recommended):** +1. Use AIO's restore feature +2. Select database-only restore (if available) + +**Via Borg Backup:** + +```bash +docker exec -it nextcloud-aio-mastercontainer bash + +# Extract database from Borg +borg extract borgbackup:: nextcloud/database/ + +# Restore to PostgreSQL +# (Exact commands depend on AIO's database structure) +``` + +**Note**: Database-only restore is tricky with AIO. Recommend using full AIO restore. + +### Scenario 4: Rollback After Failed Update + +If a Nextcloud update breaks your installation: + +1. **Stop Nextcloud**: + ```bash + docker exec -it nextcloud-aio-mastercontainer \ + /path/to/stop-script.sh + ``` + +2. **Use AIO Restore**: + - Access AIO interface (port 8080) + - Navigate to Backup section + - Restore from backup before the update + +3. **Verify** everything works + +4. **Disable auto-updates** until update issue is resolved + +## Verification and Testing + +### Regular Backup Verification + +Perform monthly verification: + +```bash +# Test 1: Verify AIO Borg backups exist +docker exec -it nextcloud-aio-mastercontainer \ + borg list /mnt/docker-aio-config/data/borg/borgbackup + +# Test 2: Verify local backups +ls -lth /opt/nextcloud-backups/ | head -5 + +# Test 3: Verify Kopia snapshots +kopia snapshot list --tags nextcloud + +# Test 4: Check Borg backup integrity (in test environment) +docker exec -it nextcloud-aio-mastercontainer \ + borg check /mnt/docker-aio-config/data/borg/borgbackup +``` + +### Backup Monitoring Script + +Create `/opt/scripts/check-nextcloud-backup.sh`: + +```bash +#!/bin/bash + +# Check last backup age +LAST_BACKUP=$(ls -td /opt/nextcloud-backups/nextcloud-* 2>/dev/null | head -1) + +if [ -z "$LAST_BACKUP" ]; then + echo "WARNING: No Nextcloud backups found" + exit 1 +fi + +BACKUP_DATE=$(basename "$LAST_BACKUP" | sed 's/nextcloud-//') +BACKUP_EPOCH=$(date -d "${BACKUP_DATE:0:8} ${BACKUP_DATE:9:2}:${BACKUP_DATE:11:2}:${BACKUP_DATE:13:2}" +%s 2>/dev/null) +NOW=$(date +%s) +AGE_HOURS=$(( ($NOW - $BACKUP_EPOCH) / 3600 )) + +if [ $AGE_HOURS -gt 26 ]; then + echo "WARNING: Last Nextcloud backup is $AGE_HOURS hours old" + exit 1 +else + echo "OK: Last backup $AGE_HOURS hours ago" +fi + +# Check AIO Borg backups +BORG_PATH="/var/lib/docker/volumes/nextcloud_aio_mastercontainer/_data/data/borg" +if [ -d "$BORG_PATH" ]; then + BORG_COUNT=$(find "$BORG_PATH" -type d -name "borgbackup_*" | wc -l) + echo "AIO Borg backups available: $BORG_COUNT" +else + echo "WARNING: Cannot access AIO Borg backups" +fi + +# Check Kopia snapshots +KOPIA_LAST=$(kopia snapshot list --tags nextcloud --json 2>/dev/null | jq -r '.[0].startTime' 2>/dev/null) + +if [ -n "$KOPIA_LAST" ]; then + echo "Last Kopia snapshot: $KOPIA_LAST" +else + echo "WARNING: Cannot verify Kopia snapshots" +fi +``` + +Make executable and add to cron: +```bash +chmod +x /opt/scripts/check-nextcloud-backup.sh + +sudo crontab -e +0 8 * * * /opt/scripts/check-nextcloud-backup.sh | logger -t nextcloud-backup-check +``` + +## Disaster Recovery Checklist + +When disaster strikes, follow this checklist: + +- [ ] Confirm scope of failure (server down, storage failure, database corruption) +- [ ] Gather server information (hostname, IP, domain configuration) +- [ ] Access offsite Kopia repository +- [ ] Provision new server (if needed) with Docker and Kopia +- [ ] Connect to Kopia repository +- [ ] Restore docker-compose configuration +- [ ] Restore AIO mastercontainer volume +- [ ] Restore Borg repository (if available) +- [ ] Start AIO mastercontainer +- [ ] Use AIO's restore interface to restore from Borg backup +- [ ] Verify web interface accessible +- [ ] Test file access and sharing +- [ ] Verify user logins work +- [ ] Check all apps are functioning +- [ ] Update DNS if server IP changed +- [ ] Document issues and lessons learned + +## Important Notes + +1. **AIO Backup Schedule**: Configure AIO's built-in backup to run BEFORE the Kopia script (e.g., AIO at 4 AM, Kopia at 5 AM) + +2. **Storage Requirements**: Borg backups are deduplicated but can still be large. Ensure adequate space: + - Borg repository: ~1.5x your data size initially + - Kopia adds minimal overhead due to deduplication + +3. **Network Configuration**: Your setup uses external network `netgrimoire` and custom Apache port 11000. Ensure these are documented for restore. + +4. **SKIP_DOMAIN_VALIDATION**: Your setup has this enabled. Ensure domain is properly configured for restore. + +5. **Testing**: Always test recovery procedures in a lab environment before trusting them in production. + +6. **Documentation**: Keep this guide and server details in a separate location (printed copy, password manager, etc.). + +7. **Retention Policy**: Review both Borg and Kopia retention settings periodically to balance storage costs with recovery needs. + +8. **Updates**: When updating Nextcloud via AIO, ensure a backup is taken first (AIO should do this automatically). + +## Backup Architecture Notes + +### Why Two Backup Layers? + +**Nextcloud AIO BorgBackup** (Tier 1): +- ✅ Nextcloud-aware (knows how to backup everything correctly) +- ✅ Built-in restore interface (easiest to use) +- ✅ Deduplication and compression +- ✅ Incremental backups (efficient) +- ✅ Encryption included +- ❌ Single location (inside Docker volume) +- ❌ No offsite replication built-in + +**Kopia Snapshots** (Tier 2): +- ✅ Offsite protection in vaults +- ✅ Additional deduplication layer +- ✅ Point-in-time recovery +- ✅ Disaster recovery to new infrastructure +- ✅ Independent of Nextcloud/Docker state +- ❌ Less Nextcloud-aware +- ❌ More complex restore process + +### Storage Efficiency + +For a 200GB Nextcloud instance: + +**Borg (Tier 1):** +- First backup: ~200GB +- Daily incremental: ~2-5GB (only changes) +- With retention policy: ~250GB total (7 days daily + 4 weekly + 6 monthly) + +**Kopia (Tier 2) backing up Borg:** +- First snapshot: ~250GB +- Daily changes: ~5-10GB (only changed Borg chunks) +- Much smaller than backing up raw data + +**Combined savings**: Borg handles Nextcloud deduplication, Kopia handles backup deduplication + +### Deduplication Layers + +1. **Nextcloud level**: Versioning and deleted files +2. **Borg level**: Block-level deduplication within Nextcloud data +3. **Kopia level**: File-level deduplication of Borg repository + +## Troubleshooting + +### "Cannot access AIO interface" + +**Symptoms**: Cannot connect to port 8080 + +**Solutions**: +```bash +# Check mastercontainer is running +docker ps | grep nextcloud-aio-mastercontainer + +# Check logs +docker logs nextcloud-aio-mastercontainer + +# Restart mastercontainer +cd /opt/nextcloud +docker compose restart + +# Check firewall +sudo ufw status +sudo ufw allow 8080/tcp +``` + +### "Borg backup fails" + +**Symptoms**: AIO reports backup failure + +**Solutions**: +```bash +# Check disk space +df -h + +# Check Borg repository +docker exec -it nextcloud-aio-mastercontainer \ + borg check /mnt/docker-aio-config/data/borg/borgbackup + +# Repair if needed (last resort) +docker exec -it nextcloud-aio-mastercontainer \ + borg check --repair /mnt/docker-aio-config/data/borg/borgbackup +``` + +### "Restore hangs or fails" + +**Symptoms**: AIO restore doesn't complete + +**Solutions**: +```bash +# Check available disk space +df -h /srv/NextCloud-AIO + +# Check Docker resources +docker stats + +# Increase Docker memory/CPU limits if needed + +# Try restoring to different location first (test) +``` + +### "Files missing after restore" + +**Symptoms**: Nextcloud restored but files don't appear + +**Solutions**: +```bash +# Rescan files +docker exec -u www-data -it nextcloud-aio-nextcloud \ + php occ files:scan --all + +# Check file permissions +ls -la /srv/NextCloud-AIO/ + +# Verify datadir mount +docker inspect nextcloud-aio-nextcloud | grep -A 10 Mounts +``` + +### "Kopia snapshot fails" + +**Symptoms**: Tier 2 backup fails but local backup succeeds + +**Solutions**: +```bash +# Check Kopia connection +kopia repository status + +# Reconnect if needed +kopia repository disconnect +kopia repository connect server --url=... + +# Check available space in Kopia repository +kopia repository status | grep Space + +# Manually create snapshot to test +kopia snapshot create /opt/nextcloud-backups +``` + +## Advanced Topics + +### Customizing Borg Retention Policy + +Edit docker-compose.yml: + +```yaml +environment: + # Keep 7 days, 4 weeks, 12 months + BORG_RETENTION_POLICY: --keep-within=7d --keep-weekly=4 --keep-monthly=12 + + # More aggressive (less space, shorter history) + # BORG_RETENTION_POLICY: --keep-within=3d --keep-weekly=2 --keep-monthly=3 + + # More conservative (more space, longer history) + # BORG_RETENTION_POLICY: --keep-within=14d --keep-weekly=8 --keep-monthly=24 +``` + +Restart AIO: +```bash +cd /opt/nextcloud +docker compose down +docker compose up -d +``` + +### Excluding Large Directories from Backup + +If certain directories don't need backup (e.g., temporary files, caches): + +This must be configured in AIO's backup interface or Borg configuration. Consult AIO documentation for current version's options. + +### Backup to Multiple Destinations + +For critical data, backup to multiple vaults: + +```bash +# In backup script, add second Kopia repository +# After first snapshot completes: + +# Connect to second repository +kopia repository disconnect +kopia repository connect server --url=https://backup2.example.com:51517 ... + +# Create snapshots in second repository +kopia snapshot create /opt/nextcloud-backups +kopia snapshot create /var/lib/docker/volumes/nextcloud_aio_mastercontainer/_data/data/borg/ +``` + +### Backup Notifications + +Add to the end of `/opt/scripts/backup-nextcloud.sh`: + +```bash +ADMIN_EMAIL="admin@example.com" + +if [ $? -eq 0 ]; then + echo "Nextcloud backup completed successfully" | \ + mail -s "✓ Nextcloud Backup Success" "$ADMIN_EMAIL" +else + echo "Nextcloud backup FAILED! Check logs at /var/log/nextcloud-backup.log" | \ + mail -s "✗ Nextcloud Backup FAILED" "$ADMIN_EMAIL" +fi + +# Healthchecks.io ping +curl -fsS --retry 3 https://hc-ping.com/your-uuid-here + +# Webhook notification +curl -X POST https://monitor.example.com/backup-status \ + -H "Content-Type: application/json" \ + -d '{"service":"nextcloud","status":"success"}' +``` + +## Additional Resources + +- [Nextcloud AIO Official Documentation](https://github.com/nextcloud/all-in-one) +- [Nextcloud AIO Backup Documentation](https://github.com/nextcloud/all-in-one#backup-and-restore) +- [BorgBackup Documentation](https://borgbackup.readthedocs.io/) +- [Kopia Documentation](https://kopia.io/docs/) +- [Docker Volume Backup Best Practices](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes) + +## Revision History + +| Date | Version | Changes | +|------|---------|---------| +| 2026-02-13 | 1.0 | Initial documentation - two-tier backup strategy using AIO's BorgBackup + Kopia | + +--- + +**Last Updated**: February 13, 2026 +**Maintained By**: System Administrator +**Review Schedule**: Quarterly