# 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/) might be an alternative.

## Installation & Setup
  0. Clone this repository
  1. Build the container image from [./build/Dockerfile](./build/Dockerfile):
    - `docker compose build`
  2. Configure backup in `.env`. Copy and adapt [.env.template](.env.template) which describes all variables:  
     - `cp .env.template .env && vi .env`
  3. Borg needs an initial init of the backup archive. To create an encrypted archive run:
    - `docker exec --rm -it borg bash -c "borg init --encryption repokey-blake2"`
  4. Finally, start the container and wait for cron to start the backup:
    - `docker compose up -d`
  5. (Optional) Run an unscheduled backup:
    - `docker exec borg bash -c 'do-backup.sh'`
  6. Upgrade:
    - Alpine and Borg versions are hard-coded in `docker-compose.yml`.
    - [Borg Release Notes](https://github.com/borgbackup/borg/releases) should be consulted for breaking changes.

## 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 containing the passphrase
  - Keyfile(s), stored in ./data/.config/borg/keys/
  
## Backup restore
  1. Stop the backup container
     - `docker compose down`
  2. Run the container with FUSE-support and enter an interactive shell:
    - `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 again:
     - `docker-compose up -d`

## Monitoring
Simple bash [scripts](scripts/) sent the backup status and statistics using `curl` to a Prometheus [Pushgateway](https://prometheus.io/docs/practices/pushing/) defined in `.env`.

## Security considerations
  - This container runs with root privileges to allow backup of all data independent of permissions.
  - The backup source-volume is mounted read-only to avoid altering data by mistake.
  - This image has a reduced feature set for the sake of simplicity.
    - If necessary, [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

## Program flow
  - [docker-compose.yml](docker-compose.yml) sets variables `.env` as environment variables in the container
  - `/scripts/entry.sh` is called during container startup
    and installs the cronjob defined in the $CRON
  - crond starts `/scripts/do-backup.sh` which
	- executes borg backup 
	- prunes and compacts old backups
    - notifies Prometheus about the backup start/stop/fail and stats

# Failure handling
  - Break the lock in case Borg has been interrupted and fails to create/acquire a new lock:
    - `docker exec borg bash -c 'borg break-lock'`