adapt readme file

Author: madoke

GROUPVARS.md

@@ -6,30 +6,103 @@ This repository contains Ansible roles to install and run
 
 They include a Systemd service file both.
 
+## Requirements
+
+- Ansible. you can install it by running `pip install ansible`
+- [optional] Working moledule setup with docker for running the tests
+
+## Installation
+
+### Git
+Use `git clone` or `git submodule add` to clone the ansible-ipfs-cluster role (`https://github.com/hsanjuan/ansible-ipfs-cluster.git`) into the `roles` folder of your playbook to pull the latest edge commit of the role from GitHub. 
+
 ## Usage
 
 If you are familiar with Ansible, you can just re-use the modules in the way
 that fits you best. Otherwise follow these steps:
 
-0. Make sure you have ansible installed: `pip install ansible`.
-1. Fill in `inventory.yml` and place the hostnames of your nodes under the `[ipfs]` group.
-2. Edit the `group_vars/ipfs.yml` and `group_vars/ipfs_cluster.yml` file
-   setting the right configuration values, including generating an
-   [IPFS Cluster secret](https://cluster.ipfs.io/documentation/guides/security/#the-cluster-secret)
-   with `od -vN 32 -An -tx1 /dev/urandom | tr -d ' \n' ; echo`
-3. Add a file for each hostname (filename is the hostname), to the `host_vars`
-   folder as outlined in [`host_vars/README.md`](host_vars/README.md),
-   containing the necessary host-specific variables (example in the
-   `host_vars` README).
-4. Run `make`.
-
-`make` will run ansible for the `ipfs` and the `ipfs-cluster` roles, which
-apply to the `[ipfs]` and `[ipfs_cluster]` inventory group. Upon successful,
-both `go-ipfs` and `ipfs-cluster` should be running in the nodes (they are
-installed under `/usr/local/bin` and run by a created `ipfs` system user).
-
-You can use `systemctl status ipfs` and `systemctl status ipfs-cluster` to
-check the status of the new services.
-
-Note that `ipfs` configuration has been generated using `profile=server`, thus
-will not automatically scan the local network.
+- Fill in `inventory.yml` and place the hostnames of your nodes under the `[ipfs]` and `[ipfs-cluster]` groups.
+- Edit the `group_vars/ipfs.yml` and `group_vars/ipfs_cluster.yml` files setting the right configuration values including generating an [IPFS Cluster secret](https://cluster.ipfs.io/documentation/guides/security/#the-cluster-secret) with `od -vN 32 -An -tx1 /dev/urandom | tr -d ' \n' ; echo`
+- Add a file for each hostname (filename is the hostname), to the `host_vars` folder as outlined in [`Host Vars`](#host-vars), containing the necessary host-specific variables (example in the `molecule/default/molecule.yml` file).
+
+Upon successful execution, both `go-ipfs` and `ipfs-cluster` should be running in the nodes (they are installed under `/usr/local/bin` and run by a created `ipfs` system user).
+
+You can use `systemctl status ipfs` and `systemctl status ipfs-cluster` to check the status of the new services.
+
+Note that `ipfs` configuration has been generated using `profile=server`, thus will not automatically scan the local network.
+
+### Host Vars
+
+Add one file for each ipfs-cluster host. The filename should match a domain name from your inventory, i.e. `example.org`.
+
+Each file should contain the following variables, updated for your cluster:
+
+```yaml
+ipfs_peer_id: "<ipfs_daemon_peer_id>"
+ipfs_private_key: "<ipfs_daemon_private_key>"
+
+ipfs_cluster_id: "<cluster_peer_id>"
+ipfs_cluster_private_key: "<cluster_peer_private_key>"
+
+ipfs_cluster_peer_addr: "/dns4/<hostname>/tcp/9096/ipfs/<ipfs_cluster_peer_id>"
+```
+
+To generate the `ipfs_peer_id`/`ipfs_private_key` and `ipfs_cluster_id`/`ipfs_cluster_private_key` key-pairs, use [`ipfs-key`]. Theymust be all different (no ID or Key can be shared between daemons).
+
+To install [`ipfs-key`], with Go installed, run:
+
+```console
+$ go get github.com/whyrusleeping/ipfs-key
+```
+
+then generate a key-pair:
+
+```console
+$ ipfs-key | base64 -w 0
+
+# or on macos
+$ ipfs-key | base64
+
+Generating a 2048 bit RSA key...
+Success!
+ID for generated key: Qmat3Bk4SixhZdU5j5pf2uXcpUuTSxKHQu7whbWrdFwn5g
+CAASqAkwggSkAgEAAoIBAQCUzxjdml2fORveg9PN98qqiENexLzoaSeNc6N7K8iVzneCU1aDZpM...
+```
+
+Where:
+
+- the value of `ID for generated key: <PeerId>` is your `ipfs_peer_id` or `ipfs_cluster_id`
+- the subsequent line is your `ipfs_private_key` or `ipfs_cluster_private_key`, encoded as base64
+
+Copy those values into your host config file.
+
+For `ipfs_cluster_peer_addr` you need to specify a valid [multiaddr] by taking the example below
+
+```
+"/dns4/<hostname>/tcp/9096/ipfs/<ipfs_cluster_peer_id>"
+```
+and replacing:
+
+`hostname`: with the host from your invetory that this file is for, e.g `example.org` `ipfs_cluster_peer_id`: with the peer id for this cluster node, that you just created.
+
+
+You can also define `ipfs_cluster_peername` to name your cluster peer for conviniency. Otherwise, the hostname will be used.
+
+[`ipfs-key`]: https://github.com/whyrusleeping/ipfs-key
+[multiaddr]: https://multiformats.io/multiaddr/
+
+### Group Vars
+
+The `group_vars` file can be used to set variables to control the common configuration for of all ipfs and ipfs-cluster peers.
+
+Edit the `ipfs.yml` file in this folder and set the appropiate values for the variables.
+
+Note the cluster `service.json` template can be fully customized by defining the appropiate variables, and otherwise they will take sensisble defaults.
+
+## Running the tests
+
+Assumes you have a working molecule setup with docker, running `molecule test` should spin up a docker container and execute the test playbook declared in `molecule/default/converge.yml`.
+
+```console
+python 3 -m molecule test
+```

HOSTVARS.md

@@ -4,7 +4,7 @@
   tasks:
     - name: "Include ansible-ipfs-cluster"
       vars:
-        ipfs_enable: false
+        ipfs_enable: true
         ipfs_cluster_enable: true
       include_role:
         name: "ansible-ipfs-cluster"

Makefile

@@ -18,8 +18,6 @@ provisioner:
         ipfs_peer_id: "QmUdZCogpVVrPMxdPHhtT2KuUuxNVi1uLb7UC4HwHBqejb"
         ipfs_private_key: "CAASqAkwggSkAgEAAoIBAQC3NFhK6XMF9tDDky2aoCdwnNsIzk0DnvkVtfTsM1/fCqnrlMDzvVOY7tsMFBNBHsjCAuLwjUMxtLTgY2+8b8vil5TTuYk0A2nCCTwyxqKHoxwn5RW3J5HlBBMgTV9vKtRyrDONFnRwvVmUbCaxblOp74tl03KEfF3zH46+vz8bzVeNdqDrGmEIc1tWnERddFAeqcM5r8fhNVsVInCWFThqFA2qUahif43Uo1B/gBySnyXWr61htiHoWBXqPK8eFk4FCBodhs+Ct81KE4QQhV9OQaZeQkChGezIPidvwiojY8Lr40xBsRn0H95AKYWwdo0lTbAJ7dtFuBinZrTNdSz/AgMBAAECggEAM7Ism+7mCy/LVvSn8LLyjh9k20ZDixsH1G2E0EXq7qg2rIhMLjslZMk5vF3J1R1Xrw9bdF+YL2V7iLnmZLjzQlxdnaUEJ04zQJKUjwtn/3gyULue9hDPZV1R/FJ49IiUbEtVPKGyd8GmjnA6NuUX7KLwpeoVrXbel+U2xXJ332MGU1uydteq4iH27FYKYK+6UZUzHLd+V9BOwzGXEXG22Z25hT8n0mp0u1LcJy5tecAj3PAPW0uhsvAFX95c/jkQRkUNj8mntTb2AL2aw4MGNj8UbLYg0EdBRfE3V+esyj0ob7OUt0Nk5d6yCOBXDSZdD/P1mDYOgiL6JpaG9445YQKBgQDvgSKClI4TmXPerRNHhN8ZKbgLy1Hcu9hMs/pmv4Up0KQ6VbrsArXD1KMglrpsXZojgKeDuLmzLnVmMeslZyYqlWS3wWXeJZ2Ms2PlcnNDQlxlwJbJapNO4V9UZTIGcydg5lJ0QWL7HVGANNvM0Jg4wFQbvjj+tXS6kVYNz4JCDwKBgQDD0owaNJNIfo9JvkXFCNafhepiSJSqxXozo1zqVLCjuesmzfgplo+6qjiJJCMbK4rZbb8DCHK1NQmROahyWmyKDNl4sOMHnH6ckO7HUILLx9M4LKzJj1B7lQX7hEjy3XZAXwT+xx4t/lyF8iG3Ta4Kxcd8ya7tQW8YBMB3LUaWEQKBgQCNBe+JDenedoO4gRaSDRXEXkFFiJGKNH03JN5zM6A4L+cThjlLEIlwZrsqzDW26yKAdxerwtBtRhTQeOIpouPhPRgR7umJdYKgP1y51LszxlZbf5wJuxxD3QZhzjg3fgSY1OWGGJ4smGXN5NHrdoO7HtwnfclXiQbTeBJAjYf4VwKBgGK8AlAkOi7PQUgZW+xg7HY6e1da6TrBnz/yGqM8WGP1Fg/Wwk2V0Jp5wU/EnL7SUYwXvbu1wsCDIXPL8pbV6OwiVnR4G8B2s5AVs49jlM9SzbkBLY3jaN0m4oFSzcVGzJzgTBB6LUlbeyM+VqmpzRs5ZcARoNWXrIAbxT9R4MlBAoGBAJPGfycrr284aF67Q30drAfxXE5AFw11DBqE6KfRdfDe02PNnlClI0BDbvA1BJyg2kzAeJvOZAAvuiw/eNuwOnqhtnoBjzJLW2EnEUu7++m/joa6nq4LZ5eHwoR+exwA6l0GH6pItHuDPESQq8JqrByLfEwsS5Jj4OxILBD7cBO8"
         ipfs_cluster_id: "QmfCpBt7JUbKRvLDvDbxvivBcnpRwSif2x3GEEYzZkCh6c"
-    group_vars:
-      ipfs_cluster:
         ipfs_cluster_private_key: "CAASqQkwggSlAgEAAoIBAQC2+Z7NiL0mwDQfkXUvKLipM/T6Op/7X5H5jG9MoCxCrMGS+u5cpQpI2o0YRXNEUGaw/pGyam5xdnZ2wC2PE9Yt9zgWpsWPakZgtJ9ZK4CapHASp6pqHkwPBmDx+t4Xs4sKlnoI3i0x+yuqYqWKCP0BvHu0zKS0rkdVtg5Qs0hjyjfphDg8DYPBz8V7lI5dlpqJ8rGsWntNkmD+lCZHiFThDhNgzPcw4/KVK9cDSw9eHoluMFMD4ZH8dFzGltXKWoqzncrFrhcpnrBOs4erJGMddLIArfJhVLWjZd8k8PE3AZ7wtjRawzDxJN8kHNvglYBo77iD81FXjtGbxtSJQiDbAgMBAAECggEBAJuAn36L1D0noeSmSRIQKIfcWTmEM0x+F2AfAsP7aEIt8cFJMuRXetsZqknTVDfdoLiRUR9xJnWVOO6JOu7a6+5aqTdO+p18s10ihD5TI1PJplmkVscjAn7Oa/uaub8o3mTcJ9B7iatti9mdRpR+OQ+NsRChzuSjLIriU14wT7hFxdQ82Y0PsJAtPJpjzsygdhJP0o9yzfiVDV+xpKIX1CXTWKFvK/Mat1mEhErFpP6gLgWksQnjw6otkmiNfgxZ/KR3auxzEhsRzOyBvbi9/gF9pgxxYf1i63plq5+OhRUNZwZv4OIZsl7iJ/uReS4muM9h+4Rvi5CqymHNykZ67kkCgYEA6J5Uh8Ppqc7FcP/ipVDoIVFcDKziwpFf2m5x1XDvZYz+khy5E8seKeKpn4rqBjKE7gbAQw/9arJrEZbE1BHhKxDgWOIlGW4xtFC+83kaAim0H/TnQtlwC3ewRi6eM+/zyKERixmQdO/qyEU5Vo3lrU2oRdEeSrhPDZRpXYFzd80CgYEAyV3hgwo2wMkGyYsdGFtzohLwz4kQuv6ntopULyFXHDVMxFOxNWYZuC+y2dn8f1qKjRsUrPNLa6jOaGem6xNKzc1iWokfEk30xKkN2lZcnxZYdjzsHtquoZs7tnlXCwyDbIOmmD+cG2FBQ8hINVzo0HaUtlchkDv3qKaGYFGmg0cCgYEAweI10nMYbtBJAMZGwkONNzf44Re4aTOCES2884oN/zZleKM4H6dMnNyvRKskI8Y3xa0a0sqhDi1n0GE57Qh6BMssMulKwsd15jTm80gcxXC9EWWu26kgGm7IHbb9ZYy6RJ77YFUOcmkF56bLA7mBldEEUCzccqrsOQVaTPV4qIECgYBRktOJVzjpDkbOnKlztZB5ZrzhBgCeEA12+EC0Owhj5/+qRNEz9aGTqNcGQ7VzDgW0tfTBP2odOewsBVlsP4t9JaejT4sjyirPBEEVYwjwdYfuli19Lk+yLgWZnTwywKX47rgtUw91VAexYtBFtdampHMIDvIM0Q455wPmvwz6fwKBgQCoPJBvL5jvA94a29NXMNtNYsxH12wOxwO9fFkY4PjnO+U/Qb4vI1PZoUzpMx63xmW0VfUEALyRQqwbV3mUmQtSNRFhw1Hxtlbv2gA/mOs7eINGf4X5cVctp0MWlpBzDFEZI7Z7tpc893Cuu4F28MS3VgGhyc/zHOymHDNuvm+QGw=="
         ipfs_cluster_peer_addr: "/dns4/node01/tcp/9096/ipfs/QmUdZCogpVVrPMxdPHhtT2KuUuxNVi1uLb7UC4HwHBqejb"
 verifier: