Skip to content

README.md

Latest commit

 

History

History
139 lines (105 loc) · 4.35 KB

README.md

File metadata and controls

139 lines (105 loc) · 4.35 KB

Docker Appdata Backup for Unraid

A Python utility to back up and restore Docker container appdata (files and configuration) on Unraid and other Docker hosts, locally or remotely over SSH.

Table of Contents

Features

  • Backup and restore Docker container appdata (files and configuration) on Unraid
  • Supports grouping containers for batch operations
  • Works with local and remote Docker hosts via SSH
  • Flexible storage: grouped or flat backup directory structure
  • Optionally stops/restarts containers before/after backup or restore for data integrity
  • Dry-run and debug logging modes for safe testing
  • Colorized, structured logging output

Requirements

  • Python 3.7 or later
  • Docker Engine on target hosts
    • lscr.io/linuxserver/socket-proxy:latest or similar
  • rsync installed on both source and destination systems
  • SSH access for remote operations
  • Python packages:
    • docker
    • pyyaml
    • schema
    • colorlog

Installation

Install Python dependencies with:

pip install -r requirements.txt

Ensure rsync and ssh are available on all participating hosts.

Usage

python backup_script.py [options]

Options

Option Description
--group GROUP Only back up the specified group as defined in config.yaml
--restore Perform a restore operation (all groups by default)
--restore-group GROUP Restore a specific group
--restore-container NAME Restore a specific container (requires --restore-group)
--dry-run Show what would happen without making changes
--debug Enable verbose debug logging

Configuration

All settings are defined in a config.yaml file located in the same directory as the script.

Example config.yaml

# Path where all backups will be stored.
backup_destination: /mnt/user/backup/appdata

# Whether to organize backups into subfolders based on groups (e.g., group-1, group-2).
store_by_group: yes

# Definition of backup groups
groups:
  group-1:
    - name: container-a
      host: local
      appdata_path: /mnt/user/appdata/container-a
      restart: yes
      start_delay: 10 # Wait (in seconds) before starting this container. Helpful if a dependent container needs time to init

    - name: container-b
      host: local
      appdata_path: /mnt/user/appdata/container-b
      restart: yes

  group-2:
    - name: container-c
      host: 10.253.0.2
      ssh_key: /mnt/user/system/keys/ssh_key.pub
      ssh_port: 2222
      appdata_path: /docker/container-c
      restart: yes

    - name: container-d
      host: 10.253.0.2
      ssh_key: /mnt/user/system/keys/ssh_key.pub
      ssh_port: 22
      appdata_path: /docker/container-d
      restart: yes

How it Works

  • For each container, the script may:

    • Optionally stop the container for backup integrity
    • Export the container's configuration to JSON
    • Use rsync to copy the appdata directory to the backup destination
    • Optionally restart the container

  • Restore operations support group or per-container granularity, syncing data back to the original path and restarting containers if configured.

  • If present, notifications are sent using Unraid's notify script.

Notes

  • The script assumes rsync and ssh are available.
  • For remote hosts, ensure SSH key-based access is set up.
  • This tool does not back up Docker images; only configurations and appdata directories are saved.
  • Tested with Unraid and standard Docker hosts.

Troubleshooting

  • Ensure all dependencies are installed on both local and remote hosts.
  • If SSH connections fail, verify SSH keys and network connectivity.
  • Use --debug for verbose logging to diagnose issues.
  • Check permissions for reading appdata and writing to the backup destination.