search

djmaze / resticker

Run automatic restic backups via a Docker container.
https://hub.docker.com/r/mazzolino/restic/
Apache License 2.0
502 stars 69 forks source link

readme

Resticker

Docker Pulls Build status

Run automatic restic backups via a Docker container.

Features

Usage

Use the supplied example configs to set up a backup schedule.

The Compose files contain a backup, a prune and a check service which can be scheduled independently of each other. Feel free to remove the prune and/or check service if you want to run the prune jobs manually.

If you have multiple services configured for the same repository, make sure, that at most one service is allowed to initialize the repository or a newly created repository might become corrupt.

To do so, add a SKIP_INIT=true environment variable to the other services.

With Docker Compose

Adjust the supplied docker-compose.yml as needed. Then run:

docker-compose up -d

With Docker Swarm mode

Adjust the supplied docker-swarm.yml as needed. Then deploy it as a stack:

docker stack deploy -f docker-swarm.yml backup

Versioning scheme

This project uses semantic versioning. The docker images (under mazzolino/restic) are tagged accordingly:

It is recommended to pin to the latest patch version (e.g. 1.6.0) and update the version manually (or using an automated process like Renovate).

Look at the CHANGELOG or Github releases to find the latest version.

Also, an image will be generated for each pull request. The tags are labeled pr-xxx where xxx is the id of the pull request.

Restoring

In order to restore files on a host where the container is already running via Docker Compose, you can use exec:

# Find the latest snapshot for the current host (note the ID)
docker-compose exec app restic snapshots -H <HOSTNAME>
# Restore the given file on the host
docker-compose exec app restic restore --include /path/to/file <ID>

When using Swarm mode, you need to manually SSH into the host and run docker exec -it .. accordingly.

Advanced usage

You can use the same config to run any restic command with the given configuration.

When using the Docker Compose setup:

docker-compose run --rm app <RESTIC ARGS>

E.g.

docker-compose run --rm app snapshots

When given the unlock command, the repository check will be skipped (because it will fail on a locked repository either way).

Configuration options

_Note: BACKUP_CRON, PRUNE_CRON and CHECK_CRON are mutually exclusive._

Using the rclone repository type

In order to use the rclone repository type, you need to prepare an rclone.conf file and mount it inside the container at /run/secrets/rclone.conf.

So when in swarm mode, you can just use rclone.conf as a Docker secret.

Example for Docker Compose:

services:
  backup:
    # ...
    volumes:
      - ./rclone.conf:/run/secrets/rclone.conf:ro

Example for Docker swarm mode:

services:
  backup:
    # ...
    secrets:
      - rclone.conf

secrets:
  rclone.conf:
    file: ./rclone.conf

Note for backends with token-based access

If you are using rclone backends which make use of oauth refresh tokens (B2, OneDrive, Google) the rclone.conf needs to be writable inside the container. That means you need to directly mount a directory (r/w) which contains the config file to the final config directory inside the container.

Example for Docker Compose:

services:
  backup:
    # ...
    volumes:
      - ./rclone:/root/.config/rclone

Where ./rclone should be a local directory which contains your rclone.conf.

Using sftp repository type

In order to use the sftp repository type, you need to prepare a .ssh directory with your private ssh key(s), known_hosts (and an optional config file) and mount it inside the container at /run/secrets/.ssh.

Example for Docker Compose:

services:
  backup:
    # ...
    volumes:
      - ./.ssh:/run/secrets/.ssh:ro

Using restic mount

If you want to mount your backup repository inside the container using restic mount, you need to give the container SYS_ADMIN privilege and allow the fuse device.

Example for Docker Compose:

services:
  backup:
    # ...
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse

Also the fuse kernel module should be loaded (modprobe fuse).

Execute commands prior to backup

It's possible to optionally execute commands (like database dumps, or stopping a running container to avoid inconsistent backup data) before the actual backup starts. If you want to execute docker commands on the host, mount the Docker socket to the container. To do that add the following volume to the compose or swarm configuration:

- /var/run/docker.sock:/var/run/docker.sock

You can add one or multiple commands by specifying the following environment variable:

PRE_COMMANDS: |-
            docker exec nextcloud-postgres pg_dumpall -U nextcloud -f /data/nextcloud.sql
            docker exec other-postgres pg_dumpall -U other -f /data/other.sql
            docker stop my_container

The commands specified in PRE_COMMANDS are executed one by one.

Execute commands after backup

It's possible to optionally execute commands (like restarting a temporarily stopped container, send a mail...) once the actual backup has finished. Like for pre-backup commands, if you want to execute docker commands on the host, mount the Docker socket to the container.

You can add one or multiple commands by specifying the following environment variables:

POST_COMMANDS_SUCCESS: |-
    /my/scripts/mail-success.sh

POST_COMMANDS_FAILURE: |-
    /my/scripts/mail-failure.sh

POST_COMMANDS_INCOMPLETE: |-
    /my/scripts/mail-incomplete.sh

POST_COMMANDS_EXIT: |-
    docker start my_container

The commands specified are executed one by one.

By default, when any file could not be backed up, the commands from POST_COMMANDS_FAILURE will be executed. When SUCCESS_ON_INCOMPLETE_BACKUP is set to "true", the commands from POST_COMMANDS_INCOMPLETE will be executed instead. Unless those are not configured – then the commands from POST_COMMANDS_SUCCESS will be executed.

Notification example

The Resticker docker image does not contain any tools for sending notifications, apart from curl. You should thus connect a second container for that purpose. For example, this is how mail notifications can be sent using apprise-microservice:

services:
  app:
    image: mazzolino/restic:1.1
    environment:
      # ...
      POST_COMMANDS_FAILURE: |-
        curl -X POST --data "{\"title\": \"Backup failed\", \"body\": \"\"}" http://notify:5000
    networks:
      - notification

  notify:
    image: mazzolino/apprise-microservice:0.1
    environment:
      NOTIFICATION_URLS: mailto://...
    networks:
      - notification

networks:
  notification:

Build instructions

Use the supplied Makefile in order to build your own image:

make image IMAGE=myuser/restic

You can also push images and build on a different architecture:

make image IMAGE=myuser/restic ARCH=arm

For more targets, see the Makefile.

Testing

There are automated tests for the scripts running in the container. You need to install shellspec to run them.

The test suite can be executed by running the following in the resticker source directory:

shellspec

This will build the image, create a container and run the tests inside the container.

Credits

restic-backup-docker was used as a starting point. Thanks!