From 642c17e9174242ad111d079cc3fe78116eaa55fe Mon Sep 17 00:00:00 2001
From: Luke Murphy <lukewm@riseup.net>
Date: Sat, 21 Mar 2020 23:20:52 +0100
Subject: [PATCH] Describe new vault approach

---
 README.md | 35 ++++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index cc0238b..52b9f9e 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ $ dokku plugin:install-dependencies
 
 ## Usage
 
-All files must be placed within the `ansible` folder of your git repository. Everything is copied into `$DOKKU_LIB_ROOT/data/ansible/$APP` on the `post-extract` hook. Dokku will make sure that your Ansible plays are run on the right hook against the Dokku server localhost.
+All files must be placed within the `ansible` folder of your git repository. Everything is copied into `$DOKKU_LIB_ROOT/data/ansible/$APP` on the `post-extract` hook. Dokku will make sure that your Ansible plays are run on various hooks against the Dokku server localhost.
 
 - `requirements.yml`: what role dependencies to download before running your plays.
 - `pre-deploy.yml`: play run before a deployment
@@ -27,21 +27,15 @@ All files must be placed within the `ansible` folder of your git repository. Eve
 
 ## Passwords
 
-You can place a `ansible/.vault.sh` script that produces your [Ansible Vault](https://docs.ansible.com/ansible/latest/user_guide/vault.html password. This file will be copied over to `$DOKKU_LIB_ROOT/data/ansible/$APP` and locked down with the correct read-only permissions for the Dokku user account. This will then be used as the [Ansible Vault](https://docs.ansible.com/ansible/latest/user_guide/vault.html) password file which can be used to decrypt secrets.
+Ansible uses the [vault](https://docs.ansible.com/ansible/latest/user_guide/vault.html) password file which can be used to decrypt secrets.
 
-Don't forget to `chmod +x` it and also **add this file to your `.gitignore`**, you've been warned!
-
-Here's an example `ansible/.vault.sh` file.
+To get started with enabling this, you should generate a vault password for your self and run the following on your Dokku host.
 
 ```bash
-#!/bin/bash
-
-set -eu -o pipefail
-
-echo "my-cool-vault-password"
+$ dokku ansible-playbook:add-vault-password
 ```
 
-So, if you then encrypt a secret:
+Then you can start to encrypt your passwords on your local machine with the following.
 
 ```bash
 $ ansible-vault \
@@ -51,11 +45,26 @@ $ ansible-vault \
   mysecretvalue
 ```
 
-You can place this output in your plays and it can be successfully decrypted on the remote Dokku host.
+Where `ansible/.vault.sh` might look like this.
+
+```bash
+#!/bin/bash
+
+set -eu -o pipefail
+
+echo "my-cool-vault-password"
+```
+
+Then for example, if you want to pass a sudo password, you might include a `vars.yml`.
+
+```yaml
+---
+ansible_become_password: !vault ...
+```
 
 ## Permissions
 
-Since the `dokku` user account runs the plays on the host, you will need to deal with sudo permissions when you want to use `become: true` to run a privilege escalation to the root account. In order to do this, you'll need to 1) run `passwd dokku` as the root user and set an account password and 2) add the `dokku` user account to the sudoers group (`usermod -aG sudo dokku`).
+Since the `dokku` user account runs the plays on the host, you will need to deal with sudo permissions when you want to use `become: true` to run a privilege escalation to the root account. You can give your `dokku` user account passwordless sudo access but that would give a lot of power to people who can get access to that user account. A solution to this can be to add your `dokku` to the sudoers group, give the account a password (`passwd dokku && usermod -aG sudo dokku`) and pass `ansible_become_password` in as a variable.
 
 ## Example