Netgrimoire/nextcloud_backup.md

---
title: Nextcloud Backup
description: Native + Kopia
published: true
date: 2026-02-15T00:11:07.746Z
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

### Important: Borg Backup password: 0c038ada7a620e59802f43422b6fea409b46bab8821be6d3

### 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 <snapshot-id> /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 <config-snapshot-id> /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 <snapshot-id> /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 <borg-snapshot-id> /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::<archive-name> /tmp/borg-mount

# Navigate to user's files
cd /tmp/borg-mount/nextcloud/data/<username>/files/

# Copy needed files to restore location
cp -r /tmp/borg-mount/nextcloud/data/<username>/files/* \
  /actual/nextcloud/data/<username>/files/

# Unmount
borg umount /tmp/borg-mount
exit

# Run Nextcloud file scan
docker exec -it nextcloud-aio-nextcloud bash
php occ files:scan <username>
```

**Via Kopia (if datadir was backed up):**

```bash
# Mount Kopia snapshot
kopia snapshot list --tags datadir
mkdir -p /mnt/kopia-nextcloud
kopia mount <snapshot-id> /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::<archive-name> 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