Resolve "external backup on S3"

Closes #26 (closed)

roles/ynh_backup/README.md

@@ -11,10 +11,11 @@ YunoHost needs to be installed on your server.
 ## Role Variables
 
 The default variables are available in `default/main.yml` however it is possible to override them according to your needs.
-We have integrated two different backup systems to this YunoHost role:
+We have integrated three different backup systems to this YunoHost role:
 
 - YunoHost native local backups
 - Remote backups with a [BorgBackup repository](https://borgbackup.readthedocs.io/en/stable/)
+- Remote backups with a [Restic repository](https://restic.readthedocs.io/en/stable/)
 
 ### YunoHost native local backups
 
@@ -22,16 +23,15 @@ YunoHost provides its own native backup system. It is able to back up YunoHost c
 
 ```yml
 ynh_backup:
-  scheduled: True
-  directory: "/data/backup"
-  scheduled_hour: "*"
-  scheduled_minute: "*/30"
+  scheduled:         True
+  directory:         "/data/backup/local_ynh_backups"
+  scheduled_hour:    "*"
+  scheduled_minute:  "*/30"
   scheduled_weekday: "*"
-  scheduled_month: "*"
-  system: True
-  apps: True
-  src_script: "templates/ynh_backup.sh.j2"
-  dest_script: "/usr/bin"
+  scheduled_month:   "*"
+  system:            True
+  apps:              True
+  number_days_to_keep: "2"
 ```
 
 - `ynh_backup.scheduled`: Enable the YunoHost applications backup feature by setting the value to `True`.
@@ -39,7 +39,7 @@ ynh_backup:
 - `ynh_backup.scheduled_[hour|minute|weekday|month]`: modifies the scheduling of the cron task. By default, it will run every day of the year at 3am. For more information about cron time settings, this tool can be useful: <https://crontab.guru/>.
 - `ynh_backup.system`: Disable YunoHost system backup by setting the value to `False`, the default value is `True`.
 - `ynh_backup.apps`: Disable backup of YunoHost applications by setting the value to `False`, the default is `True`.
-- `ynh_backup.number_days_to_keep` : Determines the number of days to keep for the purging system, the default is 2.
+- `ynh_backup.number_days_to_keep`: Determines the number of days to keep for the purging system, the default is 2.
 - ⚠️ Beware, once you enable the local backup feature `ynh_backup.scheduled`, you cannot disable system **and** application backups. If you set `ynh_backup.system` **and** `ynh_backup.apps` to `False`, the role will fail.
 
 ### remote backups with YunoHost BorgBackup
@@ -47,23 +47,23 @@ ynh_backup:
 - Backups with [BorgBackup](https://borgbackup.readthedocs.io/en/stable/) and [Borgmatic](https://github.com/witten/borgmatic): Thanks to the Ansible role `m3nu.ansible_role_borgbackup` we can automate the installation and configuration process of Borg Backup on a YunoHost server. Borg backups are accessible on a local or a remote Borg repository. More info about this role [here](https://github.com/borgbase/ansible-role-borgbackup).
 
 ```yml
-ynh_borg_backup_scheduled: True
-borg_source_directories:
-  - "/data/yunohost"
-borg_repository: "/data/backup/live"
+ynh_borg_backup_scheduled:  True
+borg_source_directories:    "{{ ynh_backup.directory }}"
+borg_repository:            "/data/backup/borg_repository"
 borg_encryption_passphrase: "PLEASECHANGEME"
-borgmatic_config_name: "borgmatic_ynh_config"
-borgmatic_cron_name: "borgmatic_ynh_cron"
+borgmatic_config_name:      "borgmatic_ynh_config"
+borgmatic_cron_name:        "borgmatic_ynh_cron"
 borg_retention_policy:
   keep_daily: "4"
 ynh_borg_backup_remote_repo: True
-borg_ssh_keys_src: "files/prd/ssh_keys/ynh_ed25519.vault"
-borg_ssh_keys_dest: "/home/debian/.ssh/ynh_ed25519"
+borg_ssh_keys_src:          "files/prd/ssh_keys/ynh_ed25519.vault"
+borg_ssh_keys_dest:         "/home/debian/.ssh/ynh_ed25519"
+ynh_ssh_borg_command:       "ssh_command: ssh -p 7410 -o StrictHostKeychecking=no -i {{ borg_ssh_keys_dest }}"
 ```
 
 - `ynh_borg_backup_scheduled`: Enable / disable the backup feature with BorgBackup.
 - `ynh_borg_backup_remote_repo`: Enable / disable the backup functionality on a BorgBackup remote repository (tasks related to SSH keys setup). If you enable this feature, then you will need to use `borg_ssh_keys_src` and `borg_ssh_keys_dest` variables. 
-- `borg_source_directories`: List of source folders to back up. By default, this is the folder containing all YunoHost data (configuration, applications).
+- `borg_source_directories`: List of source folders to back up. By default, this is the folder in which YunoHost local backups are located.
 - `borg_repository`: Full path to the Borg repository. Possibility to give a list of repositories to save data in several places.
 - `borg_encryption_passphrase` : **Mandatory**, password to use for the Borg repository encryption key.
 - `borgmatic_config_name`: **Optional**, name of the Borgmatic configuration file.
@@ -75,9 +75,64 @@ borg_ssh_keys_dest: "/home/debian/.ssh/ynh_ed25519"
 
 Feel free to look at the variables available in the [role](https://github.com/borgbase/ansible-role-borgbackup).
 
+### remote backups with YunoHost Restic
+
+- Backups with [Restic](https://restic.net/): Thanks to the Ansible role `do1jlr.restic` we can automate the installation and configuration process of Restic on a YunoHost server. Restic backups can be done on a local or a remote Restic repository and compatible with S3 object storage. More info about this role [here](https://github.com/roles-ansible/ansible_role_restic).
+
+⚠️ Be careful, in order to use the Ansible role `do1jlr.restic`, you must have the following [packages](https://github.com/roles-ansible/ansible_role_restic#requirements) installed on the machine running Ansible:
+
+- `bzip2` (binary available on most Linux systems).
+- `jmespath` (python package, can be installed through pip).
+
+```yml
+ynh_restic_backup_scheduled: True
+restic_create_schedule:      True
+restic_keep_time:            "0y2m0d0h"
+
+restic_repos:
+  s3_ynh_restic_repo:
+    location:               "s3:s3.fr-par.scw.cloud/dummy_bucket_name"
+    password:               "dummy_restic_repo_password"
+    aws_access_key:         "dummy_access_key"
+    aws_secret_access_key:  "dummy_secret_access_key"
+    aws_default_region:     "fr-par"
+    init:                   True
+
+restic_backups:
+  YunoHost_remote:
+    name:                   "remote_ynh_restic"
+    repo:                   "s3_ynh_restic_repo"
+    src:                    "{{ ynh_backup.directory }}"
+    tags:
+      - yunohost
+      - remote
+    keep_within:            "{{ restic_keep_time }}"
+    scheduled: True
+    schedule_hour: 1
+    schedule_minute: 0
+```
+
+- `ynh_restic_backup_scheduled`: Enable / disable the backup feature with Restic.
+- `restic_keep_time`: Allows to fine tune the time period during which snapshots should be kept. The default value is 1 month `0y1m0d0h`.
+- `restic_repos`: Restic keeps data in repositories. You must specify at least one repository to use this role. A repository must have the following variables:
+  - `location`: **Mandatory**, the path to the repository. This can be a local path (e.g. `/data/backup`) or a path to an S3 bucket (see example above).
+  - `password`: **Mandatory**, password to use for the Restic repository.
+  - `init`: Describes whether the repository should be initialized or not. Use `false` if you are using an already initialized Restic repository.
+  - ⚠️ Beware, if this is an S3 object storage repository, you must provide additional variables for Restic to authenticate and access the cloud provider (see example above).
+- `restic_backups`: A backup specifies a directory or file to be backed up. It has the following variables:
+  - `name` : **Mandatory**, this name of this backup. It must be unique and is used with the __pruning__ and scheduling.
+  - `repo`: **Mandatory**, the name of the repository where to save the snapshots. This repository should have been declared beforehand (see above for variables to fill in).
+  - `src` : **Mandatory**, the directory or file to be backed up.
+  - `tags`: **Optional**, list of tags to add information.
+  - `keep-within`: Can be used in connection with the `restic_keep_time` variable (in this case, keep this variable as it is) or you can choose a retention period for each backup.
+  - `scheduled`: Use `true` if you want to set up a cron job to trigger a backup at regular intervals. In correlation with `restic_create_schedule: true` (both need to be set to `true` for the cron task to be created).
+  - `schedule_[minute|hour|weekday|month]`: Allows you to fine-tune the timing of the cron job.
+
+Feel free to look at the variables available in the [role](https://github.com/roles-ansible/ansible_role_restic).
+
 ## Dependencies
 
-The `m3nu.ansible_role_borgbackup` role will be installed on the machine running Ansible for Borg-related tasks to work. A `requirements.yml` file is in the root of the role and will download the role (by default to `~/.ansible/roles`).
+The `m3nu.ansible_role_borgbackup` and `do1jlr.restic` roles will be installed on the machine running Ansible for Borg and Restic related tasks to work.
 
 ## Example Playbook