Fix: improved README

2 files changed, 68 insertions, 35 deletions

diff --git a/README b/README
deleted file mode 100644
index 1efc47a..0000000
--- a/README
+++ /dev/null
@@ -1,35 +0,0 @@
-This module contains the general backup conventions and defintions used by the
-Fluxo Group according to
-
-  https://padrao.fluxo.info/backup/
-
-It relies on the Backupninja module,
-
-  https://gitlab.com/shared-puppet-modules-group/backupninja
-
-What is basically do is to help the creation of standardized definitions for
-rdiff-backup and duplicity like these:
-
-  # local encrypted/signed backup
-  backup::duplicity { "localhost":
-    encryptkey => "$key_id",
-    password   => "$key_password",
-  }
-
-  # remote backup of previously encrypted/signed backup
-  backup::rdiff { "$node_name":
-    port => "$port",
-  }
-
-The first definition will keep local encrypted/signed backups using duplicity
-at /var/backups/duplicity.
-
-The second definition will push the local /var/backups/duplicity to a remote
-destination using rdiff-backup over ssh.
-
-We choose this two stage approach as the experience showed that it's more
-reliable and fast than to let duplicity do all the job.
-
-Note that this is a simple module that don't manages backup users or keys by
-itself: you should do that manually or use another puppet module such as
-backupninja::server.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..89483cf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# Fluxo Puppet Backup Module
+
+## About
+
+This module contains the general backup conventions and defintions used by the
+Fluxo Group according to the [Fluxo Pattern](https://padrao.fluxo.info/backup/).
+
+It relies on the [backupninja module](https://gitlab.com/shared-puppet-modules-group/backupninja).
+
+What is basically do is to help the creation of standardized definitions for
+backup definitions.
+
+Note: this is a simple module that don't manages backup users or keys by
+itself: you should do that manually or use another puppet module such as
+`backupninja::server`.
+
+## Available methods
+
+### Remote backups using Borg
+
+  # remote encrypted backup from localhost to $node_name using Borg
+  backup::borg { "$node_name":
+    port => "$port",
+  }
+
+### Local encrypted backups pushed to remotes
+
+One of the methods relies in a local encrypted backup that's later on pushed to
+remotes.
+
+The advantage of this two stage approach, as the experience showed, is that
+it's more reliable and fast than to let duplicity do all the job.
+
+#### Example with [duplicity][] and [rsync][]
+
+  # local encrypted/signed backup
+  backup::duplicity { "localhost":
+    encryptkey => "$key_id",
+    password   => "$key_password",
+  }
+
+  # remote backup of previously encrypted/signed backup sent to $node_name
+  backup::rsync { "$node_name":
+    port => "$port",
+  }
+
+* The first definition will keep local encrypted/signed backups using duplicity
+  at `/var/backups/duplicity`.
+
+* The second definition will push the local `/var/backups/duplicity` to a
+  remote destination using [rsync][] over SSH.
+
+#### Example with [duplicity][] and [rdiff-backup][]
+
+  # local encrypted/signed backup
+  backup::duplicity { "localhost":
+    encryptkey => "$key_id",
+    password   => "$key_password",
+  }
+
+  # remote backup of previously encrypted/signed backup sent to $node_name
+  backup::rdiff { "$node_name":
+    port => "$port",
+  }
+
+[duplicity]: https://duplicity.gitlab.io/
+[rdiff-backup]: https://rdiff-backup.net/
+[rsync]: https://rsync.samba.org/