This repository provides a Docker image for [borgmatic](https://github.com/witten/borgmatic), a simple and efficient backup tool based on [Borgbackup](https://github.com/borgbackup). The image is designed to make it easy to set up and run borgmatic (with Borg and optionally Cron daemon) within a Docker container, enabling you to streamline your backup process and ensure the safety of your data.
Before proceeding, ensure that you have [Docker](https://www.docker.com/) installed and properly configured on your system. Refer to the [Docker documentation](https://docs.docker.com/engine/install/) for installation instructions specific to your operating system. If you want to use [docker-compose](https://docs.docker.com/compose/install/), you may also need to install it seperately.
Alternatively, you can also use [podman](https://podman.io/docs) to run this image.
Configure a copy of borgmatic's [config.yaml](data/borgmatic.d/config.yaml) in `data/borgmatic.d` and run the container. You can modify any of the host mount point to fit your backup configuration.
```
docker run \
--detach --name borgmatic \
-v /home:/mnt/source:ro \
-v ./data/repository:/mnt/borg-repository \
-v ./data/borgmatic.d:/etc/borgmatic.d/ \
-v ./data/.config/borg:/root/.config/borg \
-v ./data/.ssh:/root/.ssh \
-v ./data/.cache/borg:/root/.cache/borg \
-e TZ=Europe/Berlin \
ghcr.io/borgmatic-collective/borgmatic
```
See [Other usage methods](#other-usage-methods) below for more options.
| `/mnt/source` | Your data you wish to backup. For *some* safety you may want to mount read-only. borgmatic is running as root so all files can be backed up. |
| `/mnt/borg-repository` | Mount your borg backup repository here. |
| `/etc/borgmatic.d` | Where you need to create crontab.txt and your borgmatic config.yml |
| `/root/.borgmatic` | **Note** this is now redundant and has been deprecated, please remove this from your configs |
| `/root/.config/borg` | Here the borg config and keys for keyfile encryption modes are stored. Make sure to backup your keyfiles! Also needed when encryption is set to none. |
| `/root/.ssh` | Mount either your own .ssh here or create a new one with ssh keys in for your remote repo locations. |
| `/root/.cache/borg` | A non-volatile place to store the borg chunk cache. |
To generate an example borgmatic configuration, run:
You can also provide your own crontab file. If `data/borgmatic.d/crontab.txt` exists, `BACKUP_CRON` will be ignored in preference to it. In here you can add any other tasks you want ran
Beside that, you can also pass any environment variable that is supported by borgmatic. See documentation for [borgmatic](https://torsion.org/borgmatic/) and [Borg](https://borgbackup.readthedocs.io/) and for a list of supported variables.
### Using Secrets (Optional)
You also have the option to use Docker Secrets for more sensitive information. This is not mandatory, but it adds an extra layer of security. **Note that this feature is only applicable to environment variables starting with `BORG`.**
For every environment variable like `BORG_PASSPHRASE`, you can create a corresponding secret file, named as `BORG_PASSPHRASE_FILE`. Place the content of the secret inside this file. The startup script will automatically look for corresponding `_FILE` secrets if the environment variables are not set and load them.
Apprise allows you to send notifications to a multitude of services and is now the recommended way to handle notifications in Borgmatic. This guide will cover how to set up basic email notifications and further options you can explore.
### Basic Setup
#### Cronjob Configuration
In an unmodified Borgmatic installation, your `cronjob.txt` might look something like this:
If you don't want to send the log file, you can replace `-b "$(cat /tmp/backup_run.log)"` with a custom message like `-b "My message"`.
### Advanced Options
##### Apprise Capabilities
Apprise offers a variety of services to send notifications to, such as Telegram, Slack, Discord, and many more. For a complete list, visit the [Apprise GitHub page](https://github.com/caronc/apprise#productivity-based-notifications).
#### Example for Multiple Services
Apprise allows you to notify multiple services at the same time:
Apprise provides a flexible and powerful way to handle notifications in Borgmatic. Be sure to check out the [official Apprise documentation](https://github.com/caronc/apprise#productivity-based-notifications) for a full range of options and capabilities.
This image can be used to run borgmatic like a binary by passing the borgmatic command while running the container. It allows you to isolate your system and execute borgmatic commands without directly installing borgmatic on your host system and only keeping persistent data.
**NOTE** Replace `MOUNT_FLAGS_HERE` placeholder with appropriate [mount flags](#volumes) and optionally [environment flags](#environment). [See above](#getting-started) for more clues.
This will execute `borgmatic list` in your container. The idea is to create symlink to a script which executes this. Now create a new file `borgmatic-docker.sh` somewhere like your workspace or home directory.
To keep the container always running for continous backup, you can run it in detached mode. If you do not pass the command, by default it'll start the cron daemon which will run borgmatic at interval set in crontab.txt file.
```
docker run -d --restart=always \
MOUNT_FLAGS_HERE \
ghcr.io/borgmatic-collective/borgmatic \
```
If you ever need to run borgmatic manually, for instance to view or recover files, run:
```
docker exec -it container_id_or_name bash
```
Then you can run `borgmatic` directly within that shell.
Use docker compose for easily management of your borgmatic container. You can also use this image with your existing docker-compose configuration to immediate setup backups for your deployed containers and/or the host.
[Backup Docker using borgmatic](https://www.modem7.com/books/docker-backup/page/backup-docker-using-borgmatic) - Thank you [@modem7](https://github.com/modem7)