restic-compose-backup/README.md

199 lines
4.3 KiB
Markdown
Raw Normal View History

2019-04-13 17:04:54 +00:00
2019-12-03 08:40:02 +00:00
# restic-compose-backup
2019-04-13 17:04:54 +00:00
2019-12-05 01:31:20 +00:00
![docs](https://readthedocs.org/projects/restic-compose-backup/badge/?version=latest)
2019-04-17 18:13:23 +00:00
Backup using https://restic.net/ for a docker-compose setup.
2019-04-13 17:04:54 +00:00
2019-12-05 00:58:50 +00:00
* [restic-compose-backup Documentation](https://restic-compose-backup.readthedocs.io)
* [restic-compose-backup on Github](https://github.com/ZettaIO/restic-compose-backup)
* [restic-compose-backup on Docker Hub](https://hub.docker.com/r/zettaio/restic-compose-backup)
Features:
* Back up docker volumes or host binds
* Back up mariadb postgres
* Back up mariadb databases
* Back up mysql databases
* Notifications over mail/smtp
* Notifications to Discord through webhooks
Please report issus on [github](https://github.com/ZettaIO/restic-compose-backup/issues).
2019-12-03 23:36:28 +00:00
2019-12-02 22:12:30 +00:00
Automatically detects and backs up volumes, mysql, mariadb and postgres databases in a docker-compose setup.
2019-04-13 17:04:54 +00:00
2019-12-02 22:12:30 +00:00
* Each service in the compose setup is configured with a label
to enable backup of volumes or databases
* When backup starts a new instance of the container is created
mapping in all the needed volumes. It will copy networks etc
to ensure databases can be reached
2019-12-04 21:17:42 +00:00
* Volumes are mounted to `/volumes/<service_name>/<path>`
in the backup process container. `/volumes` is pushed into restic
2019-12-05 00:58:50 +00:00
* Databases are backed up from stdin / dumps into restic using path `/databases/<service_name>/dump.sql`
* Cron triggers backup at 2AM every day
2019-04-13 17:04:54 +00:00
2019-12-03 09:19:12 +00:00
## Install
```bash
docker pull zettaio/restic-compose-backup
```
.. or clone this repo and build it.
2019-04-13 17:04:54 +00:00
## Configuration
2019-04-13 21:59:54 +00:00
Required env variables for restic:
2019-04-13 18:12:25 +00:00
```bash
RESTIC_REPOSITORY
RESTIC_PASSWORD
```
2019-04-13 21:59:54 +00:00
Backend specific env vars : https://restic.readthedocs.io/en/stable/040_backup.html#environment-variables
2019-12-05 00:58:50 +00:00
Additional env vars:
```bash
# Prune rules
RESTIC_KEEP_DAILY=7
RESTIC_KEEP_WEEKLY=4
RESTIC_KEEP_MONTHLY=12
RESTIC_KEEP_YEARLY=3
# Logging level (debug,info,warning,error)
LOG_LEVEL=info
# SMTP alerts
EMAIL_HOST=my.mail.host
EMAIL_PORT=465
EMAIL_HOST_USER=johndoe
EMAIL_HOST_PASSWORD=s3cr3tpassw0rd
EMAIL_SEND_TO=johndoe@gmail.com
# Discord webhook
DISCORD_WEBHOOK=https://discordapp.com/api/webhooks/...
```
2019-12-02 22:12:30 +00:00
### Volumes
2019-04-13 21:59:54 +00:00
```yaml
version: '3'
services:
2019-12-02 22:12:30 +00:00
# The backup service
2019-04-13 21:59:54 +00:00
backup:
2019-12-03 08:43:21 +00:00
build: restic-compose-backup
2019-04-13 21:59:54 +00:00
environment:
- RESTIC_REPOSITORY=<whatever restic supports>
- RESTIC_PASSWORD=hopefullyasecturepw
2019-12-04 22:01:06 +00:00
- RESTIC_KEEP_DAILY=7
- RESTIC_KEEP_WEEKLY=4
- RESTIC_KEEP_MONTHLY=12
- RESTIC_KEEP_YEARLY=3
2019-04-13 21:59:54 +00:00
env_file:
- some_other_vars.env
volumes:
- /var/run/docker.sock:/tmp/docker.sock:ro
2019-12-02 22:12:30 +00:00
2019-04-13 22:57:38 +00:00
example:
2019-04-13 21:59:54 +00:00
image: some_image
# Enable volume backup with label
labels:
2019-12-03 08:43:21 +00:00
restic-compose-backup.volumes: true
2019-04-13 21:59:54 +00:00
# These volumes will be backed up
volumes:
2019-04-13 22:02:40 +00:00
# Docker volume
- media:/srv/media
# Host map
- /srv/files:/srv/files
2019-04-13 21:59:54 +00:00
volumes:
media:
2019-04-13 22:57:38 +00:00
```
2019-12-02 22:12:30 +00:00
A simple `include` and `exclude` filter is also available.
2019-04-13 22:57:38 +00:00
```yaml
2019-04-13 22:58:28 +00:00
example:
2019-04-13 22:57:38 +00:00
image: some_image
labels:
2019-12-03 08:43:21 +00:00
restic-compose-backup.volumes: true
restic-compose-backup.volumes.include: "files,data"
2019-04-13 22:57:38 +00:00
volumes:
# Source don't match include filter. No backup.
- media:/srv/media
# Matches include filter
- files:/srv/files
- /srv/data:/srv/data
volumes:
media:
files:
```
2019-12-02 22:12:30 +00:00
Exclude
2019-04-13 22:57:38 +00:00
```yaml
2019-04-13 22:58:28 +00:00
example:
2019-04-13 22:57:38 +00:00
image: some_image
labels:
2019-12-03 08:43:21 +00:00
restic-compose-backup.volumes: true
restic-compose-backup.volumes.exclude: "media"
2019-04-13 22:57:38 +00:00
volumes:
# Excluded by filter
- media:/srv/media
# Backed up
- files:/srv/files
- /srv/data:/srv/data
volumes:
media:
files:
```
2019-04-15 14:59:53 +00:00
2019-12-02 22:12:30 +00:00
### Databases
Will dump databases directly into restic through stdin.
They will appear in restic as a separate snapshot with
2019-12-04 21:17:42 +00:00
path `/databases/<service_name>/dump.sql` or similar.
2019-04-15 14:59:53 +00:00
2019-12-02 22:12:30 +00:00
```yaml
mariadb:
image: mariadb:10
labels:
2019-12-03 08:43:21 +00:00
restic-compose-backup.mariadb: true
2019-04-15 14:59:53 +00:00
```
2019-12-02 22:12:30 +00:00
```yaml
mysql:
image: mysql:5
labels:
2019-12-03 08:43:21 +00:00
restic-compose-backup.mysql: true
2019-12-02 22:12:30 +00:00
```
```yaml
postgres:
image: postgres
labels:
2019-12-03 08:43:21 +00:00
restic-compose-backup.postgres: true
2019-04-15 14:59:53 +00:00
```
2019-04-15 17:49:15 +00:00
2019-12-02 22:12:30 +00:00
## Running Tests
2019-04-15 17:49:15 +00:00
2019-12-05 00:58:50 +00:00
```bash
2019-12-05 10:23:33 +00:00
pip install -e src/
pip install -r src/tests/requirements.txt
tox
2019-04-15 17:49:15 +00:00
```
2019-12-05 00:58:50 +00:00
## Building Docs
```bash
pip install -r docs/requirements.txt
python setup.py build_sphinx
```
## Contributing
Contributions are welcome regardless of experience level. Don't hesitate submitting issues, opening partial or completed pull requests.