Docker Data Restore Role

Overview

This role restores Docker data volumes from backup archives stored on NAS. It automatically identifies the latest backup, displays restore information for user confirmation, and extracts the data to the target location. This role is the companion to docker_data_backup and is typically used for disaster recovery or system migration.

Purpose

Disaster Recovery: Restore Docker data after system failure or data loss
System Migration: Transfer Docker volumes to a new server
Testing: Create test environments from production backups
Safe Restoration: Requires user confirmation before extracting data
Automated Selection: Automatically selects the most recent backup

Requirements

Ansible 2.9 or higher
NAS mount point accessible with backup files
Sufficient disk space on target system for extracted data
Docker data backups created by docker_data_backup role

Role Variables

Required Variables

None - all variables have defaults.

Optional Variables

Variable	Default	Description
`docker_data_restore_syno_mount_point`	`/media/nas_win_share/docker`	Mount point where backup archives are stored
`docker_data_restore_target_path`	`/home/bjoffrey`	Target directory for extracting Docker data

Variable Details

docker_data_restore_syno_mount_point

Directory containing the backup tar.gz files. The role searches for files matching docker_data_backup_*.tar.gz.

Example:

docker_data_restore_syno_mount_point: /mnt/backup/docker

docker_data_restore_target_path

The directory where Docker data will be extracted. The archive contains a docker/ subdirectory, so if you extract to /home/bjoffrey, the data will be restored to /home/bjoffrey/docker/.

Example:

docker_data_restore_target_path: /opt
# This will restore to /opt/docker/

Dependencies

This role has no dependencies on other Ansible roles, but requires:

NAS mount configured (see nas_mount or nas_mount_systemd roles)
Backup files created by docker_data_backup role
Read permissions on the NAS mount point

Example Playbook

Basic Usage (Restore Latest Backup)

---
- name: Restore Docker Data
  hosts: docker
  become: true

  roles:
    - docker_data_restore

Restore from Custom Backup Location

---
- name: Restore Docker Data from Custom Location
  hosts: docker
  become: true

  vars:
    docker_data_restore_syno_mount_point: /mnt/backup2/docker
    docker_data_restore_target_path: /opt

  roles:
    - docker_data_restore

Full Disaster Recovery Workflow

---
- name: Complete Docker Disaster Recovery
  hosts: docker_new
  become: true

  tasks:
    - name: Restore Docker data from backup
      ansible.builtin.include_role:
        name: docker_data_restore

    - name: Install Docker
      ansible.builtin.include_role:
        name: docker_install

    - name: Deploy Docker Compose stack
      ansible.builtin.include_role:
        name: docker_compositor

What This Role Does

Searches for backup files matching pattern docker_data_backup_*.tar.gz
Sorts backups by modification time (newest first)
Selects the most recent backup automatically
Fails gracefully if no backups are found
Displays backup information (filename and size in MB)
Prompts for confirmation before proceeding (can be skipped in check mode)
Extracts the archive to the target path
Displays restore results with next steps

Backup File Selection

The role automatically selects the most recent backup using these criteria:

Searches for files matching pattern: docker_data_backup_*.tar.gz
Sorts by modification time (mtime)
Uses the newest file

Example backup files (newest first):

docker_data_backup_20260107T190530.tar.gz  <- This will be used
docker_data_backup_20260107T143022.tar.gz
docker_data_backup_20260106T020000.tar.gz

User Confirmation

Before extracting data, the role displays:

Using backup: /media/nas_win_share/docker/docker_data_backup_20260107T190530.tar.gz (1234.56 MB)

Press ENTER to continue with restore or Ctrl+C to abort:

This safety check:

Prevents accidental data overwrites
Shows which backup will be restored
Displays backup size to verify you have enough disk space
Can be skipped when running with --check mode

To skip confirmation (for automation):

# Use expect or yes command
yes "" | ansible-playbook restore_playbook.yml

# Or run in check mode (no actual changes)
ansible-playbook restore_playbook.yml --check

Restored Data Structure

The backup archive contains:

docker/
├── 2fauth/
├── dokuwiki/
├── gitlab/
├── mariadb/
├── nextcloud/
├── postgresql/
└── ... (all other container volumes)

If you extract to /home/bjoffrey (default), the data will be restored to:

/home/bjoffrey/docker/
├── 2fauth/
├── dokuwiki/
└── ...

What Gets Restored

The restoration includes:

All Docker volume data (databases, application data, configurations)
Container persistent storage
Any files that were in docker_data_path during backup

The restoration does NOT include:

Docker images (must be pulled separately)
Container definitions (must deploy with docker-compose)
Network configurations (defined in compose.yaml)
Docker daemon configuration

Post-Restoration Steps

After restoring data, you typically need to:

Install Docker (if not already installed)

ansible-playbook -i inventory install_docker.yml

Deploy Docker Compose stack

ansible-playbook -i inventory deploy_docker_compositor.yml

Verify container startup
```
docker compose ps
docker compose logs
```
Check data integrity
- Test database connections
- Verify application data is accessible
- Check file permissions

Disk Space Requirements

Before restoring, ensure you have sufficient disk space:

# Check available space
df -h /home/bjoffrey

# Check backup size (shown during restore)
# The role displays: "Using backup: ... (1234.56 MB)"

Rule of thumb: You need at least 2-3x the backup size in free space:

1x for the compressed backup (if copying locally)
1x for the extracted data
1x buffer for temporary files during extraction

Error Handling

No Backup Files Found

TASK [Fail if no backup found]
fatal: [docker]: FAILED! => {"msg": "No Maloja backup files found in /media/nas_win_share/docker"}

Note: Error message says “Maloja” but refers to Docker backups (appears to be a copy-paste artifact in the code).

Resolution:

Verify NAS is mounted
Check backup directory path
Ensure backup files exist and match the pattern

Insufficient Disk Space

The unarchive task will fail if there’s not enough space.

Resolution:

# Free up space
docker system prune -a
# Or expand the filesystem

Permission Denied

Resolution:

# Ensure target directory is writable
sudo chown -R bjoffrey:bjoffrey /home/bjoffrey

Safety Considerations

Destructive Operation: Extraction will overwrite existing files with the same names
Backup First: Create a backup of current data before restoring
Test Restore: Test in a non-production environment first
User Confirmation: Built-in pause prevents accidental overwrites
Check Mode: Use --check to verify without making changes

Security Considerations

File Permissions: Extracted files maintain permissions from the backup
Sensitive Data: Backups may contain database credentials and application secrets
NAS Access: Ensure only authorized users can access backup storage
Encryption: Consider encrypting backups at rest on NAS

Notes

The role uses remote_src: true for unarchive, meaning the backup is extracted directly from NAS (no local copy needed)
Extraction preserves file ownership and permissions from the backup
The confirmation pause is skipped when running in check mode
Archive extraction can take several minutes for large backups

Troubleshooting

”No backup files found”

Verify:

NAS is mounted: mount | grep nas_win_share
Backup directory exists: ls -l /media/nas_win_share/docker/
Backup files exist: ls -l /media/nas_win_share/docker/docker_data_backup_*.tar.gz

Extraction fails with “Permission denied”

Ensure the target directory is writable:

sudo chown -R $USER:$USER /home/bjoffrey
chmod 755 /home/bjoffrey

Containers fail to start after restore

Check:

File ownership: ls -la /home/bjoffrey/docker/
File permissions: Some containers need specific UID/GID
Volume paths in compose.yaml match restored paths

Wrong data restored

The role always selects the newest backup. To restore a specific backup:

Temporarily move other backups: mv docker_data_backup_202601*.tar.gz /tmp/
Run the restore role
Move backups back: mv /tmp/docker_data_backup_*.tar.gz ./

Alternative: Manual Restoration

If you need more control:

# Find backups
ls -lth /media/nas_win_share/docker/docker_data_backup_*.tar.gz | head -5

# Extract specific backup
tar -xzf /media/nas_win_share/docker/docker_data_backup_20260107T143022.tar.gz -C /home/bjoffrey

# Verify extraction
ls -l /home/bjoffrey/docker/

# Fix permissions if needed
chown -R bjoffrey:bjoffrey /home/bjoffrey/docker/

Best Practices

Test restores regularly to verify backup integrity
Document your docker_data_path for future reference
Maintain restore procedures for disaster recovery planning
Verify data integrity after restoration
Keep restore playbooks in version control

docker_data_backup: Creates the backup files this role restores
docker_install: Installs Docker after data restoration
docker_compositor: Deploys Docker Compose stack using restored data

License

MIT

Author

Created for homelab infrastructure management.

Docker Data Restore

Docker Data Restore Role

Overview

Purpose

Requirements

Role Variables

Required Variables

Optional Variables

Variable Details

docker_data_restore_syno_mount_point

docker_data_restore_target_path

Dependencies

Example Playbook

Basic Usage (Restore Latest Backup)

Restore from Custom Backup Location

Full Disaster Recovery Workflow

What This Role Does

Backup File Selection

User Confirmation

Restored Data Structure

What Gets Restored

Post-Restoration Steps

Disk Space Requirements

Error Handling

No Backup Files Found

Insufficient Disk Space

Permission Denied

Safety Considerations

Security Considerations

Tags

Notes

Troubleshooting

”No backup files found”

Extraction fails with “Permission denied”

Containers fail to start after restore

Wrong data restored

Alternative: Manual Restoration

Best Practices

Related Roles

License

Author