matrix.developers.italia.it

This repository contains the configuration for deploying a Matrix chat server on matrix.developers.italia.it.

The configuration uses the matrix-docker-ansible-deploy playbook.

Prerequisites

• Git
• Ansible
• just
• Open the ports listed in prerequisites.md

Getting Started

1. Clone this repository:

   git clone --recurse-submodules [email protected]:teamdigitale/matrix.developers.italia.it.git

2. Link the inventory directory:

   cd matrix.developers.italia.it/
   ln -s ../inventory matrix-docker-ansible-deploy/inventory

3. Get the vault file with secrets:

   Get vault.yml and save it to inventory/host_vars/matrix.developers.italia.it/vault.yml (you'll need access to the repo).

First deployment

Your SSH key must be added to authorized_keys of root on the server.

1. Move to the playbook directory:

   cd matrix-docker-ansible-deploy/

2. Update the roles:

   just roles

3. Install and start everything:

   ansible-playbook -i inventory/hosts setup.yml --ask-vault-pass --tags=install-all,ensure-matrix-users-created,start

Maintenance

⏰ Update the playbook (once per month)

This should be done periodically as to not fall behind too much. Small frequent updates are less risky and more likely to be rollback-able than big ones.

Nevertheless, updates can break things proceed carefully and follow these steps: ⚠️

1. Move to the playbook submodule directory:

   cd matrix-docker-ansible-deploy/

2. Check for changes:

   Check for the changes and investigate if there's something potentially risky or not backwards compatible.

   git fetch origin
   git shortlog HEAD..origin/master

3. Check the CHANGELOG:

   Check the CHANGELOG for breaking changes and adapt the local variables if there are any.

4. Update the playbook submodule:

   Move to the repo root:

   cd ..

   Sync the submodule to the latest commit and push:

   git submodule update --remote
   git commit -am "chore: update playbook to latest commit"
   git push

🔄 Update the server

1. Pull the repo:

   git pull --recurse-submodules

2. Move to the playbook directory:

   cd matrix-docker-ansible-deploy/

3. Update the roles:

   just roles

4. Update the installation :

   Beware: this will result in a short downtime because the services will be restarted. ⚠️

   just setup-all --ask-vault-pass