Ansible Collection - eraga.matrix

Table of Contents

• Modules
• Installing this collection
  • Python dependencies
• Usage
  • Module dependencies
  • Send a message to Matrix room with eraga.matrix.send
  • Manage users and rooms with eraga.matrix.user and eraga.matrix.room
  • Manage communities with eraga.matrix.community

Collection of modules to manage Matrix Homeserver instance. Only tested with Synapse but may (partially) work with the other Matrix Homeserver implementations.

Modules

Name	Check mode	Description and features
eraga.matrix.user	yes	Manage Matrix users with Ansible (via synapse admin api): ✓ register user (password can’t be set though), ✓ update profile, ✓ deactivate.
eraga.matrix.room	yes	Manage Matrix rooms with Ansible: ✓ create; ✓ update; ✓ delete (via synapse admin api); ✓ invite room members; ✓ kick room members; ✓ update room avatar. ❏ ability to reference room by the id instead of alias. ✓ add room to list of communities
eraga.matrix.community	yes	Manage Matrix communities with Ansible: ✓ create; ✓ update; ✓ delete; ✓ kick/invite members. ✓ update avatar.
eraga.matrix.send	no	Send messages to Matrix rooms with Ansible: ✓ unencrypted messages: ✓ markdown text; ❏ images; ❏ file attachments; ❏ encrypted messages.

Installing this collection

You can install the eraga.matrix collection with the Ansible Galaxy CLI:

ansible-galaxy install git+https://github.com/eraga/ansible-matrix-collection.git,v1.0.0-rc2

You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: https://github.com/eraga/ansible-matrix-collection.git
    type: git
    version: v1.0.0-rc2

Python dependencies

Python 3.6 or higher is required for matrix modules to execute as well as following dependencies:

pip install dataclasses==0.6 dataclasses-json==0.5.2 requests markdown aiofiles "pycryptodome==3.9.9" "matrix-nio[e2e]" cairosvg

Usage

Module dependencies

All dependencies are gathered in role eraga.matrix.module_dependencies for convenience.

---
- hosts: localhost
  roles:
    - eraga.matrix.module_dependencies

Send a message to Matrix room with eraga.matrix.send

---
- name: Send a message to the room
  connection: local
  hosts: localhost
  gather_facts: false
  vars:
    matrix_uri: "https://matrix.example.net"
    matrix_token: "redacted"
    matrix_user: "ansible"
  roles:
    - eraga.matrix.module_dependencies
  tasks:
    - name: Set some fact
      set_fact:
        variables: "__variables__"

    - name: Send text to room
      eraga.matrix.send:
        matrix_uri: "{{matrix_uri}}"
        matrix_user: "{{matrix_token}}"
        matrix_token: "{{matrix_user}}"
        matrix_domain: example.net
        room: ansible_example_room_1
        text: |
          ## Test message

          It *supports* mardown and jinja {{variables}} (of course)

Manage users and rooms with eraga.matrix.user and eraga.matrix.room

---
- name: Sync users and project rooms from JetBrains Hub instance to Matrix Synapse
  connection: local
  hosts: localhost
  gather_facts: false
  vars:
    hub_uri: "https://hub.example.net/hub"
    hub_token: "redacted"

    matrix_uri: "https://matrix.example.net"
    matrix_token: "redacted"
    matrix_user: "ansible"

    all_users: []
  roles:
    - eraga.matrix.module_dependencies
  tasks:
    - name: Get Hub projects with fields and query
      eraga.jb_hub.projects:
        hub_uri: "{{hub_uri}}"
        hub_token: "{{hub_token}}"
        query: "not is: global"
        fields: "name,key,team(users(login,banned,avatar,name))"
      register: projects_result

    - name: Aggregate all unbanned users
      set_fact:
        all_users: "{{ project.team.users  | rejectattr('banned', 'true') | eraga.jb_hub.user2dict | union(all_users) }}"
      with_items: "{{projects_result.projects}}"
      loop_control:
        loop_var: project
        label: "{{ project.key }}"

    - name: Ensure user {{user.login}} exists in Matrix and has synced profile
      eraga.matrix.user:
        matrix_uri: "{{matrix_uri}}"
        matrix_user: "{{matrix_user}}"
        matrix_token: "{{matrix_token}}"
        matrix_domain: example.net
        login: "{{user.login}}"
        avatar: "{{user.avatar_url | default(omit) }}"
        displayname: "{{user.name | default(omit) }}"
      with_items: "{{all_users}}"
      loop_control:
        loop_var: user
        label: "{{ user.login }}"

    - name: Room for Hub Project exists and room members are synced
      eraga.matrix.room:
        matrix_uri: "{{matrix_uri}}"
        matrix_user: "{{matrix_user}}"
        matrix_token: "{{matrix_token}}"
        matrix_domain: example.net
        alias: "{{ project.key | lower }}_general"
        name: "{{ project.name }}"
        topic: This is room managed by ansible, yay!
        federate: no
        visibility: private
        preset: private_chat
        encrypt: yes
        room_members: "{{ project.team.users | rejectattr('banned', 'true') | map(attribute='login') | eraga.matrix.list2members(0) }}"
        power_level_override:
          events_default: 0
          state_default: 90
          ban: 90
          kick: 50
          redact: 50
          invite: 10
      with_items: "{{projects_result.projects}}"
      loop_control:
        loop_var: project
        label: "{{ project.key }}"

Manage communities with eraga.matrix.community

Create community

---
- name: Create community and room
  connection: local
  hosts: localhost
  gather_facts: false
  vars:
    hub_uri: "https://hub.example.net/hub"
    hub_token: "redacted"

    matrix_uri: "https://matrix.example.net"
    matrix_token: "redacted"
    matrix_user: "ansible"

    all_users: []
  roles:
    - eraga.matrix.module_dependencies
  tasks:
    - name: Community exists at matrix server with avatar from link
      eraga.matrix.community:
        matrix_uri: "{{uri}}"
        matrix_user: "{{user}}"
        matrix_token: "{{token}}"
        matrix_domain: example.com
        localpart: ansible_test_comm
        name: Test Community
        avatar: "http://example.com/path/to/ansible.svg"
        description: This community is managed by Ansible
        long_description: |
          # ¡Hola!
          Long description that supports markdown.
        members:
          - macarena
          - @astarta:example.com
        rooms:
          - "!BCkWAqXKUSyROyodqx:eraga.net"
        state: present
#      check_mode: yes
      register: community
    - name: Unencrypted room exists in community
      eraga.matrix.room:
        matrix_uri: "{{uri}}"
        matrix_user: "{{user}}"
        matrix_token: "{{token}}"
        matrix_domain: example.com
        alias: ansible_example_room_1
        name: Ansible Example
        topic: This room is managed by ansible
        communities:
          - ansible_test_comm
        room_members:
          margaret: 50
      register: room

Delete community

---
- name: Remove community
  connection: local
  hosts: localhost
  gather_facts: false
  vars:
    hub_uri: "https://hub.example.net/hub"
    hub_token: "redacted"

    matrix_uri: "https://matrix.example.net"
    matrix_token: "redacted"
    matrix_user: "ansible"

    all_users: []
  roles:
    - eraga.matrix.module_dependencies
  tasks:
    - name: Community does not exist at server
      eraga.matrix.community:
        matrix_uri: "{{uri}}"
        matrix_user: "{{user}}"
        matrix_token: "{{token}}"
        matrix_domain: example.com
        localpart: ansible_test_comm
        state: absent
#      check_mode: yes
      register: community