feat(element): add ansible role

roles/element/README.md

@@ -0,0 +1,24 @@
+# `finallycoffee.matrix.element` ansible role
+
+## Deployment method
+
+Deploy the [element web-app](https://element.io/)
+using the following supported methods by setting `element_deployment_method` to it:
+
+- [`docker` (docs)](docs/docker.md) (default)
+
+Planned deployment methods:
+
+- `podman`
+- `tarball`
+- `nginx`
+- `apache2`
+
+## Configuration
+
+Configure your element web-app instance by setting `element_config` directly
+or use flattened config keys with the `element_config_` prefix.
+
+For all available keys see
+[the upstream configuration manual](https://github.com/element-hq/element-web/blob/develop/docs/config.md)
+or [the role defaults in `defaults/config.yml`](defaults/config.yml).

roles/element/defaults/main/config.yml

@@ -0,0 +1,10 @@
+---
+element_config_complete: >-
+  {{ element_config | default({})
+  | combine(element_default_config | default({})) }}
+element_config: {}
+element_default_config:
+  default_server_name: "{{ element_config_default_server_name }}"
+  show_labs_settings: "{{ element_config_show_labs_settings }}"
+element_config_default_server_name: "matrix.org"
+element_config_show_labs_settings: false

roles/element/defaults/main/container.yml

@@ -0,0 +1,25 @@
+---
+element_container_image: >-
+  {{
+    element_container_image_registry + '/'
+    + ((element_container_image_namespace + '/')
+      if element_container_image_namespace | default(false, true) else '')
+    + element_container_image_name + ':'
+    + (element_container_image_tag | default('v' + element_version, true))
+  }}
+element_container_image_registry: "docker.io"
+element_container_image_namespace: "vectorim"
+element_container_image_name: "element-web"
+element_container_image_tag: ~
+element_container_name: "element-web"
+element_container_restart_policy: >-
+  {{ (element_deployment_method == 'docker')
+      | ternary('unless-stopped',
+        (element_deployment_method == 'podman' |
+          ternary('on-failure', 'always'))
+  }}
+element_container_full_volumes: >-
+  {{ element_container_default_volumes
+  + element_container_volumes | default([]) }}
+element_container_default_volumes:
+  - "{{ element_config_file }}:/app/config.json:ro"

roles/element/defaults/main/main.yml

@@ -0,0 +1,18 @@
+---
+element_user: element
+element_state: "present"
+element_version: "1.11.77"
+element_deployment_method: "docker"
+
+element_base_path: "/opt/element"
+element_source_path: "{{ element_base_path }}/src"
+element_dist_path: "{{ element_source_path }}/dist"
+element_config_path: "{{ element_base_path }}/config"
+element_config_file: "{{ element_config_path }}/config.json"
+
+element_host_uid: >-
+  {{ element_user_info is defined
+  | ternary(element_user_info.uid, element_user) }}
+element_host_gid: >-
+  {{ element_user_info is defined
+  | ternary(element_user_info.group, element_user) }}

roles/element/docs/docker.md

@@ -0,0 +1,33 @@
+# `element` deployment using `docker`
+
+> [!NOTE]
+> Needs the python library `docker` on the `ansible_host`.
+
+## Configuration
+
+The following options to the
+[`docker_container` module](https://docs.ansible.com/ansible/latest/collections/community/docker/docker_container_module.html)
+are available under the `element_container_` prefix:
+
+- `env`
+- `ports`
+- `labels`
+- `networks`
+- `etc_hosts`
+- `purge_networks`
+
+The following variables are pre-populated by the role, so override them with care:
+
+- `name`
+- `image`
+- `user`
+- `volumes`
+- `restart_policy`
+
+## Pulling from a self-hosted container registry
+
+Set `element_container_image_registry` to use a self-hosted docker registry / mirror / cache.
+
+If you need to authenticate to your registry and are not yet logged in, set `element_container_image_registry_{username,password}` and the role will attempt to log in.
+
+Set `element_container_image_registry_reauthorize` to `true` if you want to force a reauthorization at the registry.

roles/element/tasks/configure.yml

@@ -0,0 +1,35 @@
+---
+- name: Ensure element user '{{ element_user }}' is {{ element_state }}
+  ansible.builtin.user:
+    name: "{{ element_user }}"
+    system: "{{ element_user_system | default(true, true) }}"
+    create_home: "{{ element_user_create_home | default(false, true) }}"
+    state: "{{ element_state }}"
+  register: element_user_info
+
+- name: Ensure host paths are {{ element_state }}
+  ansible.builtin.file:
+    name: "{{ path.name }}"
+    state: "{{ (element_state == 'present') | ternary('directory', 'absent') }}"
+    owner: "{{ path.owner | default(element_host_uid) }}"
+    group: "{{ path.group | default(element_host_gid) }}"
+    mode: "{{ path.mode | default('0750') }}"
+  loop_control:
+    loop_var: path
+    label: "{{ path.name }}"
+  loop:
+    - name: "{{ element_base_path }}"
+      mode: '0755'
+    - name: "{{ element_config_path }}"
+      mode: '0755'
+    - name: "{{ element_source_path }}"
+      mode: '0750'
+
+- name: Ensure config file is {{ element_state }}
+  ansible.builtin.copy:
+    content: "{{ element_config | to_nice_json }}"
+    dest: "{{ element_config_file }}"
+    owner: "{{ element_host_uid }}"
+    group: "{{ element_host_gid }}"
+    mode: "{{ element_config_file_mode | default('0664') }}"
+  when: element_state == 'present'

roles/element/tasks/deploy-docker.yml

@@ -0,0 +1,33 @@
+---
+- name: Ensure docker client is logged {{ (element_state == 'present') | ternary('in', 'out') }}
+  community.docker.docker_login:
+    registry_url: "{{ element_container_image_registry }}"
+    username: "{{ element_container_image_registry_username }}"
+    password: "{{ element_container_image_registry_password }}"
+    reauthorize: "{{ element_container_image_registry_reauthorize | default(omit, true) }}"
+    state: "{{ element_state }}"
+  when:
+    - element_container_image_registry_username | default(false, true)
+    - element_container_image_registry_password | default(false, true)
+
+- name: Ensure container image '{{ element_container_image }}' is {{ element_state }} locally
+  community.docker.docker_image:
+    name: "{{ element_container_image }}"
+    state: "{{ element_state }}"
+    source: "{{ element_container_source }}"
+    force_source: "{{ element_container_image_tag | default(false, true) }}"
+
+- name: Ensure container '{{ element_container_name }}' is {{ element_state }}
+  community.docker.docker_container:
+    name: "{{ element_container_name }}"
+    image: "{{ element_container_image }}"
+    state: "{{ (element_state == 'present') | ternary('started', 'absent') }}"
+    env: "{{ element_container_env | default(omit) }}"
+    user: "{{ element_container_user }}"
+    ports: "{{ element_container_ports | default(omit) }}"
+    labels: "{{ element_container_labels | default(omit) }}"
+    volumes: "{{ element_container_full_volumes }}"
+    networks: "{{ element_container_networks | default(omit) }}"
+    etc_hosts: "{{ element_container_etc_hosts | default(omit) }}"
+    restart_policy: "{{ element_container_restart_policy }}"
+    purge_networks: "{{ element_container_purge_networks | default(omit) }}"

roles/element/tasks/main.yml

@@ -0,0 +1,20 @@
+---
+- name: Check if state is valid
+  ansible.builtin.fail:
+    msg: "Unknown state '{{ element_state }}'. Valid states are {{ element_states | join(', ') }}"
+  when: element_state not in element_states
+
+- name: Check if deployment method is supported
+  ansible.builtin.fail:
+    msg: >-
+      Deployment method '{{ element_deployment_method }}' is not supported!
+      Supported are: {{ element_deployment_methods | join(', ') }}
+  when: element_deployment_method not in element_deployment_methods
+
+- name: Include base configuration
+  ansible.builtin.include_tasks:
+    file: configure.yml
+
+- name: Deploy using {{ element_deployment_method }}
+  ansible.builtin.include_tasks:
+    file: "deploy-{{ element_deployment_method }}.yml"

roles/element/vars/main.yml

@@ -0,0 +1,7 @@
+---
+element_state:
+  - present
+  - absent
+
+element_deployment_methods:
+  - docker