borg/README.md

Borg Backup

Container image for creating cron-scheduled backups with borg backup based on Alpine Linux.

Borg key features

• Space efficient storage through deduplication and compression.
• Fast backup runs and pruning of old backups.
• Encryption to allow backup storage in insecure offsite locations.
• FUSE mount support for easy recovery.
• Focus on local backups. (For cloud backups restic offers more options.)

Installation & Setup

• Build: Run docker compose build to build the container image from ./build/Dockerfile
• Configuration: cp .env.template .env and adapt .env (parameters are explained in the template file)
• Init the backup archive: docker exec --rm -it borg bash -c "borg init --encryption repokey-blake2"
• Start the container: docker compose up -d
• Upgrade: Alpine and Borg versions are hard-coded in docker-compose.yml. Borg Release Notes should be consulted prior to upgrades.

Preparation for disaster recovery

Very important: The following files MUST be stored along with the backup to enable decryption of the backup data

• .env-file file containing the passphrase
• Keyfiles, stored in ./data/.config/borg/keys/
  

Backup restore

1. Stop the backup container: docker compose down
2. Run an interactive shell in the recovery: docker compose -f docker-compose.yml -f docker-compose.restore.yml run borg bash
3. Fuse-mount the backup: borg mount $BORG_REPO <mount_point>
4. Restore your files
5. Unmount and exit: borg umount <mount_point> && exit.
6. Start the backup container: docker-compose up -d

Monitoring

• Status and statistics are sent to Prometheus Push-Gateway using a simple bash-script and curl

Security considerations

• This container will run with root priveliges in order to access all data for backup.
• The backup source-volume is mounted read-only to avoid alering data by mistake.
• This image as a reduced feature set for sake of simplicity.
  • borgmatic offers more features such as notifications and backup of databases.
  • py3-llfuse and bash are included for comfort during backup restore and could be potentially removed
  • curl is included to push Promethous metrics and could be removed if this functionality is not used

Progam flow

• /scripts/entry.sh is called during container startup and installs the cronjob defined in .env variable $CRON
• crond starts /scripts/do-backup.sh which
  • notifies Prometheus about the backup status and stats
  • executes borg backup
  • prunes and compacts old backups

Failure handling

• In case Borg fails to create/acquire a lock: borg break-lock /mnt/repository