README.md 2.8 KB

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 as alternative more options.

Installation & Setup

  1. Build:
    • Run docker compose build to build the container image from ./build/Dockerfile
  2. Configuration:
    • cp (.env.template)[.env.template] .env
    • Adapt .env, parameters are explained in the template file
  3. Init the backup archive:
    • docker exec --rm -it borg bash -c "borg init --encryption repokey-blake2"
  4. Start the container:
    • docker compose up -d
  5. 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! 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 has 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