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.
Encrypted allows backup storage in insecure offsite locations.
FUSE mount support for easy recovery.
Focus on local backups. (For cloud backups restic offers more options.)

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.
Simplified feature set for sake of simplicity, compared to borgmatic
- 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

Build

Alpine and borg version are hard-coded in docker compose so we don't mess up backups due to version upgrades
Run docker compose build to build the container image from ./build/Dockerfile

Installation & Setup

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

Preparing 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

Stop the backup container: docker compose down
Run an interactive shell: docker compose -f docker-compose.yml -f docker-compose.restore.yml run borg bash
Fuse-mount the backup: borg mount $BORG_REPO <mount_point>
Restore your files
Finally unmount and exit: borg umount <mount_point> && exit.

Monitoring

Status and statistics are sent to Prometheus using a simple bash script and curl

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 status and stats
- executes borg backup
- prunes and compacts old backups in

Failure handling

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