# Borg Backup
Container image for creating cron-scheduled backups with [borg backup](https://www.borgbackup.org/) 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](https://restic.net/) 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](https://github.com/borgbackup/borg/releases) 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](https://torsion.org/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`