Run automatic restic backups via a Docker container.

• run scheduled backups
• backup to any (local or remote) target supported by restic
• support for tags, exclude definitions, and all other optional restic options
• automatic forgetting of old backups
• prune backups on a schedule
• remove a stale repository lock
• can be used as a (global) Docker swarm service in order to backup every cluster node
• multi-arch: the image mazzolino/restic runs on amd64 as well as armv7 (for now)

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

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

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

docker-compose up -d

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

docker stack deploy -f docker-swarm.yml backup

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.

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).

Note: BACKUP_CRON, PRUNE_CRON and CHECK_CRON are mutually exclusive.

• BACKUP_CRON - A cron expression for when to run the backup. E.g. 0 30 3 * * * in order to run every night at 3:30 am. See the go-cron documentation for details on the expression format (a customized go-cron is used which allows the definition of seconds as first parameter).
• PRUNE_CRON - A cron expression for when to run the prune job. E.g. 0 0 4 * * * in order to run every night at 4:00 am. See the go-cron documentation for details on the expression format (a customized go-cron is used which allows the definition of seconds as first parameter).
• CHECK_CRON - A cron expression for when to run the check job. E.g. 0 15 5 * * * in order to run every night at 5:15 am. See the go-cron documentation for details on the expression format (a customized go-cron is used which allows the definition of seconds as first parameter).
• RUN_ON_STARTUP - Set to "true" to execute a backup or prune job right on startup, in addition to the given cron expression. Disabled by default
• RESTIC_REPOSITORY - Location of the restic repository. You can use any target supported by restic. Default /mnt/restic
• RESTIC_BACKUP_SOURCES - Source directory to backup. Make sure to mount this into the container as a volume (see the example configs). Default /data
• RESTIC_PASSWORD - Password for the restic repository. Will also be used to initialize the repository if it is not yet initialized
• RESTIC_BACKUP_ARGS - If specified restic backup is run with the given arguments, e.g. for tags, exclude definitions, or verbose logging: --tag docker-volumes --exclude-file='exclude.txt' --verbose. See the restic backup documentation for available options
• RESTIC_BACKUP_TAGS - Deprecated. Tags to set for each snapshot, separated by commas. This option will soon be removed. Please use RESTIC_BACKUP_ARGS to define tags.
• RESTIC_FORGET_ARGS - If specified restic forget is run with the given arguments after each backup or before every prune, e.g. --prune --keep-last 14 --keep-daily 1. See the restic forget documentation for available options
• RESTIC_PRUNE_ARGS - If specified restic prune is run with the given arguments, e.g. for B2 concurrent connection settings and verbose logging: -o b2.connections=10 --verbose.
• RESTIC_CHECK_ARGS - If specified restic check is run with the given arguments, e.g. --read-data-subset=10% to check a randomly choosen subset (10%) of the repository pack files. Without option, only the structure of the repository is checked. The option --read-data-subset will also check data, at the cost of transfering them from the repository.; e.g. for B2 concurrent connection settings and verbose logging: -o b2.connections=10 --verbose.
• (Additional variables as needed for the chosen backup target. E.g. B2_ACCOUNT_ID and B2_ACCOUNT_KEY for Backblaze B2. See official restic documentation about supported environment variables.)
• TZ - Optional. Set your timezone for the correct cron execution time.

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

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

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.

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_EXIT: |-
	docker start my_container

The commands specified are executed one by one.

• POST_COMMANDS_SUCCESS commands will be executed after a successful backup run.
• POST_COMMANDS_FAILURE commands will be executed after a failed backup run.
• POST_COMMANDS_EXIT will always be executed, after both successful or failed backup runs.

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:

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.

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