infrastructure/op_guide/update_matrix/README.md

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:

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:

  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
2. Revert to this deployment with nomad 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).