From 83cf0538c076cefda4e04d0ebd3e3efa84a3f438 Mon Sep 17 00:00:00 2001
From: Luke Murphy <lukewm@riseup.net>
Date: Sat, 21 Mar 2020 01:08:57 +0100
Subject: [PATCH] Update README about vault setup

---
 README.md | 53 ++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 95fd28f..75e46a2 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,8 @@ This plugin can be useful when you need to provision your server before or after
 
 ## Requirements
 
-* dokku 0.19.13+
-* Debian based system (uses `apt` package manager for installing dependencies)
+- dokku 0.19.13+
+- Debian based system (uses `apt` package manager for installing dependencies)
 
 ## Installation
 
@@ -20,14 +20,38 @@ $ dokku plugin:install-dependencies
 
 All files must be placed within the `ansible` folder of your git repository.
 
-* `requirements.yml`: what role dependencies to download before running your plays.
-* `pre-deploy.yml`: play run before a deployment
-* `post-deploy.yml`: play run after a deployment
+- `requirements.yml`: what role dependencies to download before running your plays.
+- `pre-deploy.yml`: play run before a deployment
+- `post-deploy.yml`: play run after a deployment
 
-Notes:
+- 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.
 
-* 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.
+## Passwords
+
+You can place a `ansible/.vault.sh` script (don't forget to `chmod +x` it) that looks like this:
+
+```bash
+#!/bin/bash
+
+set -eu -o pipefail
+
+echo "my-cool-vault-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.
+
+So, if you then encrypt a secret:
+
+```bash
+$ ansible-vault \
+  encrypt_string \
+  --vault-password-file ansible/.vault.sh \
+  --name mysecretname \
+  mysecretvalue
+```
+
+You can place this in your plays and it can be successfully decrypted on the host.
 
 ## Example
 
@@ -45,9 +69,12 @@ Notes:
 ---
 - hosts: all
   tasks:
-    - name: Create foobar group
-      group:
-        name: foobar
-        system: true
-        state: present
+    - name: Configure the foobar environment
+      dokku_config:
+        app: foobar
+        restart: false
+        config:
+          FOO: BAR
+      become: true
+      become_user: dokku
 ```