1 files changed, 89 insertions, 0 deletions
diff --git a/op_guide/update_matrix/README.md b/op_guide/update_matrix/README.md
new file mode 100644
index 0000000..7df588f
--- /dev/null
+++ b/op_guide/update_matrix/README.md
@@ -0,0 +1,89 @@
+How to update Matrix?
+=====================
+
+## 1. Build the new containers
+
+It starts with this file: `app/build/docker-compose.yml`.
+Often, I update Riot Web and Synapse at the same time.
+In the file, find the `riot` and `synapse` entries.
+The only thing you need to do is to update the `VERSION` argument.
+This argument is then used to template the Dockerfile.
+The `VERSION` value should match a github release, the link to the corresponding release page is put as a comment next to the variable in the compose file.
+
+Next, we put tags on our images.
+You need to increment it, for example: `superboum/amd64_riotweb:v17` will become `superboum/amd64_riotweb:v18`.
+We use the docker hub to store our images, if you are not `superboum` you must change the name with your handle, eg. `john/amd64_riotweb:v18`.
+
+So, from now we expact you have:
+  - changed the `VERSION` value and `image` name/tag of `riot`
+  - changed the `VERSION` value and `image` name/tag of `synapse`
+
+You can now simply build and push the new images:
+
+```bash
+docker-compose build riot synapse
+```
+
+And then send them to the docker hub:
+
+```
+docker-compose push riot synapse
+```
+
+Don't forget to commit and push your changes before doing anything else!
+
+## 2. Deploy the new containers
+
+Now, we will edit the deployment file `app/deployment/im.hcl`.
+
+Find where the image is defined in the file, for example in Riot, it will look like that:
+
+
+```hcl
+  group "riotweb" {
+    count = 1
+
+    task "server" {
+      driver = "docker"
+      config {
+        image = "superboum/amd64_riotweb:v17"
+        port_map {
+          web_port = 8043
+        }
+```
+
+And replace the `image =` entry with your image name.
+Do the same thing for `synapse`.
+
+Now, you need a way to access the cluster to deploy this file.
+To do this, you must bind nomad on your machine through a SSH tunnel.
+Check the end of `README.md` to do it.
+If you have access to the Nomad web UI when entering http://127.0.0.1:4646
+you are ready to go.
+
+You must have installed the Nomad command line tool on your machine (also explained in `README.md`).
+
+Now, on your machine, you must be able to run (from the `app/deployment` folder) :
+
+```
+nomad plan im.hcl
+```
+
+Check that the proposed diff corresponds to what you have in mind.
+If it seems OK, just copy paste the proposed `nomad job run ... im.hcl` command proposed as part of the output of the `nomad plan` command.
+
+From now, it will take around ~2 minutes to deploy the new images.
+You can follow the deployment from the Nomad UI.
+Bear in mind that, once the deployment is done on Nomad, you may still need to wait some minutes that Traefik refreshes its configuration.
+
+If everythings worked as intended, you can commit and push your deployment file.
+
+If something went wrong, you must rollback your deployment.
+
+  1. First, find a working deployment with [nomad job history](https://www.nomadproject.io/docs/commands/job/history)
+  2. Revert to this deployment with [nomad job revert](https://www.nomadproject.io/docs/commands/job/revert)
+
+Now, if the deployment failed, you should probably investigate what went wrong offline.
+In this case, I build a test stack with docker-compose in `app/integration` (for now, I had to do that only for plume and jitsi).
+
+