From f43cc32ac3d7861b660c17ff69dbe17e306b190b Mon Sep 17 00:00:00 2001 From: Romain de Laage Date: Wed, 14 Sep 2022 12:58:18 +0200 Subject: [PATCH] Update docs to explain restore hooks feature and add a migration guide --- docs/markdown/_toc.md | 1 + docs/markdown/config.md | 9 +++--- docs/markdown/examples.md | 13 +++++---- docs/markdown/location/hooks.md | 35 +++++++++++++++-------- docs/markdown/migration/1.7_1.8.md | 45 ++++++++++++++++++++++++++++++ docs/markdown/migration/index.md | 1 + 6 files changed, 82 insertions(+), 22 deletions(-) create mode 100644 docs/markdown/migration/1.7_1.8.md diff --git a/docs/markdown/_toc.md b/docs/markdown/_toc.md index c50dc14..2858097 100644 --- a/docs/markdown/_toc.md +++ b/docs/markdown/_toc.md @@ -45,6 +45,7 @@ > > [0.x → 1.0](/migration/0.x_1.0) > [1.4 → 1.5](/migration/1.4_1.5) +> [1.7 → 1.8](/migration/1.7_1.8) [Examples](/examples) [Docker](/docker) diff --git a/docs/markdown/config.md b/docs/markdown/config.md index ee4e285..4e81851 100644 --- a/docs/markdown/config.md +++ b/docs/markdown/config.md @@ -55,10 +55,11 @@ version: 2 extras: hooks: &foo - before: - - echo "Hello" - after: - - echo "kthxbye" + backup: + before: + - echo "Hello" + after: + - echo "kthxbye" policies: &bar keep-daily: 14 keep-weekly: 52 diff --git a/docs/markdown/examples.md b/docs/markdown/examples.md index 9243bc9..94c5c30 100644 --- a/docs/markdown/examples.md +++ b/docs/markdown/examples.md @@ -22,12 +22,13 @@ autorestic exec -b my-backend -- unlock extras: healthchecks: &healthchecks hooks: - before: - - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Starting backup for location: ${AUTORESTIC_LOCATION}" https:///ping//start' - failure: - - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Backup failed for location: ${AUTORESTIC_LOCATION}" https:///ping//fail' - success: - - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Backup successful for location: ${AUTORESTIC_LOCATION}" https:///ping/' + backup: + before: + - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Starting backup for location: ${AUTORESTIC_LOCATION}" https:///ping//start' + failure: + - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Backup failed for location: ${AUTORESTIC_LOCATION}" https:///ping//fail' + success: + - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Backup successful for location: ${AUTORESTIC_LOCATION}" https:///ping/' locations: something: diff --git a/docs/markdown/location/hooks.md b/docs/markdown/location/hooks.md index a2bcf45..02dd19b 100644 --- a/docs/markdown/location/hooks.md +++ b/docs/markdown/location/hooks.md @@ -1,8 +1,8 @@ # Hooks -If you want to perform some commands before and/or after a backup, you can use hooks. +If you want to perform some commands before and/or after a backup or restore, you can use hooks. -They consist of a list of commands that will be executed in the same directory as the target `from`. +They consist of a list of commands that will be executed in the same directory as the config file or in the `dir` directory if configured. The following hooks groups are supported, none are required: @@ -17,16 +17,27 @@ locations: from: /data to: my-backend hooks: - before: - - echo "One" - - echo "Two" - - echo "Three" - after: - - echo "Byte" - failure: - - echo "Something went wrong" - success: - - echo "Well done!" + backup: + before: + - echo "One" + - echo "Two" + - echo "Three" + after: + - echo "Byte" + failure: + - echo "Something went wrong" + success: + - echo "Well done!" + restore: + dir: /var/www/html + before: + - echo "Let's restore this backup!" + after: + - echo "Finished to restore" + failure: + - echo "A problem has been encountered :(" + success: + - echo "Successfully restored!" ``` ## Flowchart diff --git a/docs/markdown/migration/1.7_1.8.md b/docs/markdown/migration/1.7_1.8.md new file mode 100644 index 0000000..e60779a --- /dev/null +++ b/docs/markdown/migration/1.7_1.8.md @@ -0,0 +1,45 @@ +# Migration from `1.7` to `1.8` + +## Config files + +- The config version have been changed +- You can now configure restore hooks + +See detailed instructions below. + +## Config Version + +The version field of the config file has been changed from `2` to `3`. + +## Hooks + +Since `1.8` both backup and restore hooks are possible. +For this reason, backup hooks have been moved one layer deeper, you have to move them in a `backup` object. + +Before: + +```yaml +locations: + l1: + # ... + from: /foo/bar + hooks: + before: + - pwd +``` + +After: + +```yaml +locations: + l1: + # ... + from: /foo/bar + hooks: + backup: + before: + - pwd + restore: + after: + - echo "My super restore hook" +``` diff --git a/docs/markdown/migration/index.md b/docs/markdown/migration/index.md index 624561d..e5621f5 100644 --- a/docs/markdown/migration/index.md +++ b/docs/markdown/migration/index.md @@ -2,3 +2,4 @@ - [From 0.x to 1.0](/migration/0.x_1.0) - [From 1.4 to 1.5](/migration/1.4_1.5) +- [From 1.7 to 1.8](/migration/1.7_1.8)