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

proxmox-backup-client list --repository user@pbs.example.com:backup-datastore

2. Inspect Specific Backup Contents

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

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

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

# 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

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

docker-compose stop service_name

2. List Available Backups

proxmox-backup-client list --repository user@pbs.example.com:backup-datastore

3. Inspect Backup Contents

proxmox-backup-client catalog \
    --repository user@pbs.example.com:backup-datastore \
    host/service_name/2024-01-15_10-30-45

4. Restore Specific Volumes

# 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

docker-compose up -d service_name

Advanced Restore Scenarios

Restore to Different Location

# 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

# 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)

# 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

#!/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

#!/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

   # Check PBS client permissions
   ls -la ~/.config/proxmox-backup/
   
   # Run with sudo if needed
   sudo proxmox-backup-client restore ...
   

2. Archive Not Found

   # List all archives in backup
   proxmox-backup-client catalog \
       --repository user@pbs.example.com:datastore \
       host/service_name/backup_id
   

3. Network/Connection Issues

   # 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

   # 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