docker2pbs/restore_example.md

# Docker2PBS Backup Restore Guide

## Backup Format

The script creates **separate .pxar archives for each volume** of the service:

- `volume_db_data.pxar` - for named volumes
- `bind_dot_html.pxar` - for bind mounts (paths converted to safe names)
- `bind_dot_backups.pxar` - for other bind mounts

## How to Restore Backups

### 1. List Available Backups
```bash
proxmox-backup-client list --repository user@pbs.example.com:backup-datastore
```

### 2. Inspect Specific Backup Contents
```bash
proxmox-backup-client catalog \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45
```

### 3. Selective Volume Restoration

#### Restore Docker Volume
```bash
proxmox-backup-client restore \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45 \
    volume_db_data.pxar /var/lib/docker/volumes/db_data/_data
```

#### Restore Bind Mount
```bash
proxmox-backup-client restore \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45 \
    bind_dot_html.pxar ./html
```

### 4. Restore All Archives at Once
```bash
# Example script to restore all volumes
for archive in volume_db_data.pxar bind_dot_html.pxar bind_dot_backups.pxar; do
    echo "Restoring $archive..."
    proxmox-backup-client restore \
        --repository user@pbs.example.com:backup-datastore \
        host/service_name/2024-01-15_10-30-45 \
        "$archive" "/tmp/restore/$archive/"
done
```

## Archive Naming Convention

The script automatically generates archive names:

| Volume Type | Source Example | Archive Name |
|-------------|----------------|--------------|
| Named volume | `db_data` | `volume_db_data.pxar` |
| Bind mount | `./html` | `bind_dot_html.pxar` |
| Bind mount | `/app/data` | `bind__app_data.pxar` |
| Bind mount | `../config` | `bind_dotdot_config.pxar` |

## Benefits of This Approach

1. **Selective Restoration** - restore only specific volumes
2. **Clear Structure** - each volume has its own descriptive archive name  
3. **Easy Management** - inspect contents of specific volumes
4. **Safer Operations** - lower risk of overwriting unwanted files
5. **Flexible Restore** - restore data to different locations

## Inspect Archive Contents
```bash
proxmox-backup-client catalog \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45 \
    volume_db_data.pxar
```

## Complete Restore Workflow

### 1. Stop the Service
```bash
docker-compose stop service_name
```

### 2. List Available Backups
```bash
proxmox-backup-client list --repository user@pbs.example.com:backup-datastore
```

### 3. Inspect Backup Contents
```bash
proxmox-backup-client catalog \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45
```

### 4. Restore Specific Volumes
```bash
# Restore Docker volume
proxmox-backup-client restore \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45 \
    volume_db_data.pxar /var/lib/docker/volumes/db_data/_data

# Restore bind mounts
proxmox-backup-client restore \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45 \
    bind_dot_html.pxar ./html
```

### 5. Start the Service
```bash
docker-compose up -d service_name
```

## Advanced Restore Scenarios

### Restore to Different Location
```bash
# Restore to temporary location for inspection
proxmox-backup-client restore \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45 \
    volume_db_data.pxar /tmp/inspect_db_data
```

### Restore with Different Ownership
```bash
# Restore and fix permissions
proxmox-backup-client restore \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45 \
    bind_dot_html.pxar ./html

# Fix ownership if needed
sudo chown -R 1000:1000 ./html
```

### Partial Restore (Specific Files)
```bash
# Mount archive and copy specific files
mkdir /tmp/mount_point
proxmox-backup-client mount \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45 \
    /tmp/mount_point

# Copy specific files
cp /tmp/mount_point/volume_db_data.pxar/postgresql.conf ./
cp /tmp/mount_point/bind_dot_html.pxar/index.html ./

# Unmount
fusermount -u /tmp/mount_point
```

## Automation Scripts

### Backup Script
```bash
#!/bin/bash
# backup.sh - Automated backup script

SERVICE_NAME="$1"
COMPOSE_FILE="docker-compose.yml"
PBS_REPO="user@pbs.example.com:datastore"

if [ -z "$SERVICE_NAME" ]; then
    echo "Usage: $0 <service_name>"
    exit 1
fi

echo "Starting backup of service: $SERVICE_NAME"
./docker2pbs.py "$COMPOSE_FILE" "$SERVICE_NAME" --pbs-repository "$PBS_REPO"

if [ $? -eq 0 ]; then
    echo "Backup completed successfully"
else
    echo "Backup failed"
    exit 1
fi
```

### Restore Script
```bash
#!/bin/bash
# restore.sh - Automated restore script

SERVICE_NAME="$1"
BACKUP_ID="$2"
PBS_REPO="user@pbs.example.com:datastore"

if [ -z "$SERVICE_NAME" ] || [ -z "$BACKUP_ID" ]; then
    echo "Usage: $0 <service_name> <backup_id>"
    echo "Example: $0 database 2024-01-15_10-30-45"
    exit 1
fi

echo "Stopping service: $SERVICE_NAME"
docker-compose stop "$SERVICE_NAME"

echo "Listing archives in backup: $BACKUP_ID"
ARCHIVES=$(proxmox-backup-client catalog --repository "$PBS_REPO" "host/$SERVICE_NAME/$BACKUP_ID" | grep "\.pxar$" | awk '{print $1}')

for ARCHIVE in $ARCHIVES; do
    echo "Restoring archive: $ARCHIVE"
    # Determine restore path based on archive type
    if [[ $ARCHIVE == volume_* ]]; then
        VOLUME_NAME=${ARCHIVE#volume_}
        VOLUME_NAME=${VOLUME_NAME%.pxar}
        RESTORE_PATH="/var/lib/docker/volumes/${VOLUME_NAME}/_data"
    else
        # For bind mounts, restore to current directory
        RESTORE_PATH="./"
    fi
    
    proxmox-backup-client restore \
        --repository "$PBS_REPO" \
        "host/$SERVICE_NAME/$BACKUP_ID" \
        "$ARCHIVE" "$RESTORE_PATH"
done

echo "Starting service: $SERVICE_NAME"
docker-compose up -d "$SERVICE_NAME"
```

## Troubleshooting

### Common Issues

1. **Permission Denied**
   ```bash
   # Check PBS client permissions
   ls -la ~/.config/proxmox-backup/
   
   # Run with sudo if needed
   sudo proxmox-backup-client restore ...
   ```

2. **Archive Not Found**
   ```bash
   # List all archives in backup
   proxmox-backup-client catalog \
       --repository user@pbs.example.com:datastore \
       host/service_name/backup_id
   ```

3. **Network/Connection Issues**
   ```bash
   # Test PBS connectivity
   proxmox-backup-client list --repository user@pbs.example.com:datastore
   
   # Check PBS server status
   ping pbs.example.com
   ```

4. **Disk Space Issues**
   ```bash
   # Check available space
   df -h /var/lib/docker/volumes/
   df -h ./
   
   # Clean up if needed
   docker volume prune
   docker system prune
   ```

### Best Practices

- Always stop services before restoring data
- Test restore procedures in non-production environments
- Keep restore documentation up to date
- Monitor disk space during restore operations
- Verify data integrity after restoration
- Create restore scripts for frequently restored services