merge from upstream

1 files changed, 52 insertions, 0 deletions

diff --git a/app/README.md b/app/README.md
new file mode 100644
index 0000000..3049cac
--- /dev/null
+++ b/app/README.md
@@ -0,0 +1,52 @@
+## Understand this folder hierarchy
+
+This folder contains the following hierarchy:
+
+- `<module>/build/<image_name>/`: folders with dockerfiles and other necessary resources for building container images
+- `<module>/config/`: folder containing configuration files, referenced by deployment file
+- `<module>/secrets/`: folder containing secrets, which can be synchronized with Consul using `secretmgr.py`
+- `<module>/deploy/`: folder containing the HCL file(s) necessary for deploying the module
+- `<module>/integration/`: folder containing files for integration testing using docker-compose
+
+## How to install `secretmgr.py` dependencies
+
+How to install its dependencies:
+
+```bash
+# on fedora:
+dnf install -y openldap-devel
+# on ubuntu:
+apt-get install -y libldap2-dev
+
+# for eveyrone:
+pip3 install --user --requirement requirements.txt
+```
+
+## How to use `secretmgr.py`
+
+Check that all secrets are correctly deployed for app `dummy`:
+
+```bash
+./secretmgr.py check dummy
+```
+
+Generate secrets for app `dummy` if they don't already exist:
+
+```bash
+./secretmgr.py gen dummy
+```
+
+Rotate secrets for app `dummy`, overwriting existing ones (be careful, this is dangerous!):
+
+```bash
+./secretmgr.py regen dummy
+```
+
+## How to upgrade our packaged apps to a new version?
+
+ 1. Edit `docker-compose.yml`
+ 2. Change the `VERSION` variable to the desired version
+ 3. Increment the docker image tag by 1 (eg: superboum/riot:v13 -> superboum/riot:v14)
+ 4. Run `docker-compose build`
+ 5. Run `docker-compose push`
+ 6. Done