Docker Data Backup Role

Overview

This role performs comprehensive backup of Docker data volumes to dual NAS storage. It intelligently orchestrates the backup process by scheduling Centreon monitoring downtimes, gracefully stopping containers, creating compressed archives, and automatically managing retention. This ensures data consistency while minimizing false monitoring alerts.

Purpose

• Data Protection: Backs up all Docker container data volumes
• Consistency: Stops containers before backup to ensure data integrity
• Monitoring Integration: Automatically schedules Centreon downtimes to prevent false alerts
• Dual Redundancy: Backs up to two separate NAS devices (Synology DS418 and Proxmox OMV)
• Automated Cleanup: Keeps only the last 5 backups per NAS
• Service Continuity: Automatically restarts containers after backup completes

Requirements

• Ansible 2.9 or higher
• Collections:
  • community.docker (for docker_compose_v2 module)
  • community.general (for archive module)
• Docker Compose V2 installed on target host
• Centreon monitoring server with CLAPI access
• NAS mount points must be accessible and writable
• Variables from docker_compositor role (docker_compose_directory, docker_data_path)

Role Variables

Required Variables

Variable	Required	Source	Description
vault_centreon_admin_password	Yes	Vault	Centreon admin password
centreon_host_name	Yes	Host vars	Host name in Centreon for docker server
docker_compose_directory	Yes	Host vars	Docker Compose project directory
docker_data_path	Yes	Host vars	Docker data volumes directory

Optional Variables

Variable	Default	Description
docker_data_backup_syno_mount_point	/media/nas_win_share/docker	Mount point for Synology NAS backup destination
docker_data_backup_prxmxomv_mount_point	/media/nas_win_share_omv/docker	Mount point for Proxmox OMV NAS backup destination
docker_data_backup_nases_path	See defaults/main.yml	List of destination paths with timestamps
docker_data_backup_downtime_duration_minutes	60	Centreon downtime duration in minutes

Variable Details

docker_compose_directory

Path to the directory containing your compose.yaml file. Used for stopping/starting containers.

Example:

docker_compose_directory: /home/user/docker-server

docker_data_path

Path to the directory containing all Docker volumes and persistent data. This entire directory will be backed up.

Example:

docker_data_path: /home/user/docker

docker_data_backup_downtime_duration_minutes

How long to schedule the Centreon monitoring downtime. Should be longer than your typical backup duration to avoid false alerts.

Example:

docker_data_backup_downtime_duration_minutes: 90  # 1.5 hours

Dependencies

This role depends on variables typically defined by:

• docker_compositor role (for docker_compose_directory and docker_data_path)
• nas_mount or nas_mount_systemd roles (for NAS mounts)

Example Playbook

Basic Usage

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

  roles:
    - docker_data_backup

With Custom Downtime Duration

---
- name: Backup Docker Data with Extended Downtime
  hosts: docker
  become: true

  vars:
    docker_data_backup_downtime_duration_minutes: 120  # 2 hours

  roles:
    - docker_data_backup

Scheduled Backup with Cron

---
- name: Schedule Weekly Docker Backup
  hosts: docker
  become: true

  tasks:
    - name: Create cron job for weekly Docker backup
      ansible.builtin.cron:
        name: "Weekly Docker Data Backup"
        minute: "0"
        hour: "3"
        weekday: "0"  # Sunday
        job: "ansible-playbook /path/to/docker_backup.yml"

What This Role Does

Phase 1: Downtime Scheduling

1. Calculates downtime window based on current time and duration
2. Schedules Centreon downtimes for three services:
   • Docker Containers Uptime (container running check)
   • Docker Containers Status (container health check)
   • Check Nginx Proxy Port (reverse proxy availability)
3. Delegates to Centreon server using CLAPI commands

Phase 2: Backup Execution

1. Ensures backup directories exist on both NAS mount points
2. Stops all Docker containers using Docker Compose V2 (docker compose down)
3. Waits 10 seconds for containers to fully stop
4. Creates compressed tar.gz archive of entire Docker data directory
5. Copies archive to both NAS devices with timestamp in filename
6. Starts all Docker containers using Docker Compose V2 (docker compose up)

Phase 3: Cleanup

1. Finds all existing backups on each NAS
2. Removes old backups, keeping only the 2 most recent per NAS

Backup Content

The backup includes:

• All Docker volume data (databases, application data, configurations)
• Container persistent storage
• Any files in the docker_data_path directory

The backup does NOT include:

• Docker images (can be pulled from registries)
• Container definitions (stored in compose.yaml)
• Network configurations (defined in compose.yaml)
• Running container state (containers are stopped)

Centreon Integration

Services with Scheduled Downtime

1. Docker Containers Uptime

   • Checks if containers are running
   • Goes critical when containers are stopped during backup

2. Docker Containers Status

   • Checks container health status
   • Goes critical when containers are unavailable

3. Check Nginx Proxy Port

   • Checks if Nginx Proxy Manager is accessible
   • Goes critical when NPM container is stopped

Downtime Calculation

The role automatically calculates:

• Start time: Current time when role executes
• End time: Current time + downtime_duration_minutes
• Duration: Converted to seconds for Centreon CLAPI

Example:

Current time: 2026-01-07 14:30
Duration: 60 minutes
Start: 2026/01/07 14:30
End: 2026/01/07 15:30
Duration (seconds): 3600

Backup Retention

The role implements automatic retention management:

• Keeps: Last 2 backups per NAS
• Deletes: Backups older than the 2nd most recent
• Per-NAS logic: Each NAS independently maintains 2 backups

This ensures you have:

• 2 backups on Synology DS418
• 2 backups on Proxmox OMV
• Total: Up to 4 backup copies across both devices

File Naming Convention

Backup files are named using ISO 8601 basic short format:

docker_data_backup_YYYYMMDDTHHMMSS.tar.gz

Examples:

• docker_data_backup_20260107T143022.tar.gz
• docker_data_backup_20260107T190530.tar.gz

Downtime Management

Containers are stopped for the duration of the backup:

1. Containers stop: ~5-10 seconds
2. Backup creation: Variable (depends on data size)
3. Containers start: ~10-30 seconds

Total downtime: Typically 2-5 minutes for small datasets, 10-30 minutes for large datasets.

Tip: Monitor your first backup to determine appropriate docker_data_backup_downtime_duration_minutes value.

Restoration

To restore from a backup, use the companion docker_data_restore role or manually:

# Stop all containers
cd /path/to/docker-compose
docker compose down

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

# Start containers
docker compose up -d

Error Handling

• Downtime tasks: Use failed_when: false to prevent backup failure if Centreon is unavailable
• Container stop: Will fail if Docker Compose command fails
• Archive creation: Will fail if insufficient disk space or permissions issues
• Container restart: Ensures containers always restart even if backup fails

Security Considerations

• Centreon Password: Marked with no_log: true to prevent logging
• Vault Storage: Centreon admin password must be in Ansible Vault
• File Permissions: Backup archives created with mode 0644
• Container Data: Backups may contain sensitive application data (encrypt if needed)

Tags

This role does not define any tags. Use playbook-level tags if needed:

- hosts: docker
  roles:
    - docker_data_backup
  tags:
    - backup
    - docker
    - data-protection

Notes

• The role uses Docker Compose V2 (docker compose not docker-compose)
• Archive creation can be slow for large datasets (10GB+ may take 10-20 minutes)
• Downtime scheduling delegates to the Centreon server
• The 10-second pause after stopping containers ensures clean shutdown

Troubleshooting

”docker compose command not found”

Ensure Docker Compose V2 is installed. Check with:

docker compose version

“Permission denied” when accessing NAS

Verify NAS mounts are accessible:

mount | grep nas_win_share
ls -l /media/nas_win_share/docker/

Containers don’t restart after backup

Check Docker Compose logs:

cd /path/to/docker-compose
docker compose logs

Centreon downtime not scheduled

Verify:

• Centreon server is reachable
• Admin credentials are correct
• Host name in Centreon matches centreon_host_name

Test manually:

centreon -u admin -p 'password' -o RTDOWNTIME -a add -v "SVC;Docker_Server,Docker Containers Uptime;2026/01/07 14:30;2026/01/07 15:30;1;3600;Test"

Backup file very large

The backup includes all Docker data. To reduce size:

• Clean up unused volumes: docker volume prune
• Remove old container logs
• Exclude non-critical data from docker_data_path

Performance Tips

• Schedule backups during low-usage periods (e.g., 2-4 AM)
• Use compression (already enabled with tar.gz)
• Consider incremental backups for very large datasets
• Monitor backup duration and adjust downtime window accordingly

Related Roles

• docker_data_restore: Restores Docker data from backups created by this role
• docker_compositor: Defines the Docker Compose stack being backed up
• nas_mount_systemd: Configures NAS mounts for backup storage

License

MIT

Author

Created for homelab infrastructure management.