Add support for Element Admin

roles/custom/matrix-element-admin/defaults/main.yml

@@ -0,0 +1,97 @@
+# SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+# Element Admin is a web-based administration panel for Synapse and Matrix Authentication Service
+# Project source code URL: https://github.com/element-hq/element-admin
+
+matrix_element_admin_enabled: true
+
+# renovate: datasource=docker depName=oci.element.io/element-admin
+matrix_element_admin_version: 0.1.3
+
+matrix_element_admin_scheme: https
+
+# The hostname at which Element Admin is served.
+matrix_element_admin_hostname: "admin.{{ matrix_server_fqn_element }}"
+
+# The path at which Element Admin is served.
+# This value must either be `/` or not end with a slash (e.g. `/element-admin`).
+matrix_element_admin_path_prefix: /
+
+matrix_element_admin_base_path: "{{ matrix_base_data_path }}/element-admin"
+
+matrix_element_admin_container_image_self_build: false
+matrix_element_admin_container_image_self_build_repo: https://github.com/element-hq/element-admin
+matrix_element_admin_container_image_self_build_repo_version: "{{ 'main' if matrix_element_admin_version == 'main' else matrix_element_admin_version }}"
+matrix_element_admin_container_src_path: "{{ matrix_element_admin_base_path }}/container-src"
+
+matrix_element_admin_container_image: "{{ matrix_element_admin_container_image_registry_prefix }}element-admin:{{ matrix_element_admin_container_image_tag }}"
+matrix_element_admin_container_image_tag: "{{ matrix_element_admin_version }}"
+matrix_element_admin_container_image_force_pull: "{{ matrix_element_admin_container_image.endswith(':main') }}"
+matrix_element_admin_container_image_registry_prefix: "{{ matrix_element_admin_container_image_registry_prefix_upstream }}"
+matrix_element_admin_container_image_registry_prefix_upstream: "{{ matrix_element_admin_container_image_registry_prefix_upstream_default }}"
+matrix_element_admin_container_image_registry_prefix_upstream_default: "oci.element.io/"
+
+# The base container network. It will be auto-created by this role if it doesn't exist already.
+matrix_element_admin_container_network: ''
+
+# A list of additional container networks that the container would be connected to.
+# The role does not create these networks, so make sure they already exist.
+matrix_element_admin_container_additional_networks: "{{ matrix_element_admin_container_additional_networks_default + matrix_element_admin_container_additional_networks_auto + matrix_element_admin_container_additional_networks_custom }}"
+matrix_element_admin_container_additional_networks_default: []
+matrix_element_admin_container_additional_networks_auto: []
+matrix_element_admin_container_additional_networks_custom: []
+
+# matrix_element_admin_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
+# See `../templates/labels.j2` for details.
+#
+# To inject your own other container labels, see `matrix_element_admin_container_labels_additional_labels`.
+matrix_element_admin_container_labels_traefik_enabled: true
+matrix_element_admin_container_labels_traefik_docker_network: "{{ matrix_element_admin_container_network }}"
+matrix_element_admin_container_labels_traefik_hostname: "{{ matrix_element_admin_hostname }}"
+# The path prefix must either be `/` or not end with a slash (e.g. `/element-admin`).
+matrix_element_admin_container_labels_traefik_path_prefix: "{{ matrix_element_admin_path_prefix }}"
+matrix_element_admin_container_labels_traefik_rule: "Host(`{{ matrix_element_admin_container_labels_traefik_hostname }}`){% if matrix_element_admin_container_labels_traefik_path_prefix != '/' %} && PathPrefix(`{{ matrix_element_admin_container_labels_traefik_path_prefix }}`){% endif %}"
+matrix_element_admin_container_labels_traefik_priority: 0
+matrix_element_admin_container_labels_traefik_entrypoints: web-secure
+matrix_element_admin_container_labels_traefik_tls: "{{ matrix_element_admin_container_labels_traefik_entrypoints != 'web' }}"
+matrix_element_admin_container_labels_traefik_tls_certResolver: default  # noqa var-naming
+
+# matrix_element_admin_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
+# See `../templates/labels.j2` for details.
+#
+# Example:
+# matrix_element_admin_container_labels_additional_labels: |
+#   my.label=1
+#   another.label="here"
+matrix_element_admin_container_labels_additional_labels: ''
+
+# A list of extra arguments to pass to the container
+matrix_element_admin_container_extra_arguments: []
+
+# A list of extra arguments to pass to the container process.
+matrix_element_admin_container_process_extra_arguments: []
+
+# List of systemd services that the Element Admin service depends on
+matrix_element_admin_systemd_required_services_list: "{{ matrix_element_admin_systemd_required_services_list_default + matrix_element_admin_systemd_required_services_list_auto + matrix_element_admin_systemd_required_services_list_custom }}"
+matrix_element_admin_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
+matrix_element_admin_systemd_required_services_list_auto: []
+matrix_element_admin_systemd_required_services_list_custom: []
+
+# List of systemd services that the Element Admin service wants
+matrix_element_admin_systemd_wanted_services_list: []
+
+# Controls the `SERVER_NAME` environment variable, which should point to a Matrix homeserver domain name.
+matrix_element_admin_environment_variable_server_name: "{{ matrix_domain }}"
+
+# Additional environment variables.
+#
+# Example:
+# matrix_element_admin_environment_variables_additional_variables: |
+#   SOMETHING=1
+#   ANOTHER="here"
+matrix_element_admin_environment_variables_additional_variables: ''

roles/custom/matrix-element-admin/tasks/install.yml

@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: 2024 David Mehren
+# SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Ensure Element Admin paths exist
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  with_items:
+    - path: "{{ matrix_element_admin_base_path }}"
+      when: true
+    - path: "{{ matrix_element_admin_container_src_path }}"
+      when: "{{ matrix_element_admin_container_image_self_build }}"
+  when: item.when | bool
+
+- name: Ensure Element Admin support files installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/{{ item }}.j2"
+    dest: "{{ matrix_element_admin_base_path }}/{{ item }}"
+    mode: 0640
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  with_items:
+    - labels
+    - env
+
+- name: Ensure Element Admin container image is pulled
+  community.docker.docker_image:
+    name: "{{ matrix_element_admin_container_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_element_admin_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_element_admin_container_image_force_pull }}"
+  when: "not matrix_element_admin_container_image_self_build | bool"
+  register: result
+  retries: "{{ devture_playbook_help_container_retries_count }}"
+  delay: "{{ devture_playbook_help_container_retries_delay }}"
+  until: result is not failed
+
+- when: matrix_element_admin_container_image_self_build | bool
+  block:
+    - name: Ensure Element Admin repository is present on self-build
+      ansible.builtin.git:
+        repo: "{{ matrix_element_admin_container_image_self_build_repo }}"
+        version: "{{ matrix_element_admin_container_image_self_build_repo_version }}"
+        dest: "{{ matrix_element_admin_container_src_path }}"
+        force: "yes"
+      become: true
+      become_user: "{{ matrix_user_name }}"
+      register: matrix_element_admin_git_pull_results
+
+    - name: Ensure Element Admin container image is built
+      ansible.builtin.command:
+        cmd: |-
+          {{ devture_systemd_docker_base_host_command_docker }} buildx build
+          --tag={{ matrix_element_admin_container_image }}
+          --file={{ matrix_element_admin_container_src_path }}/Dockerfile
+          {{ matrix_element_admin_container_src_path }}
+      changed_when: true
+
+- name: Ensure Element Admin container network is created
+  community.general.docker_network:
+    enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"
+    name: "{{ matrix_element_admin_container_network }}"
+    driver: bridge
+    driver_options: "{{ devture_systemd_docker_base_container_networks_driver_options }}"
+
+- name: Ensure Element Admin systemd service installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/systemd/matrix-element-admin.service.j2"
+    dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-element-admin.service"
+    mode: 0644

roles/custom/matrix-element-admin/tasks/main.yml

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- tags:
+    - setup-all
+    - setup-element-admin
+    - install-all
+    - install-element-admin
+  block:
+    - when: matrix_element_admin_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
+
+    - when: matrix_element_admin_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/install.yml"
+
+- tags:
+    - setup-all
+    - setup-element-admin
+  block:
+    - when: not matrix_element_admin_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/uninstall.yml"

roles/custom/matrix-element-admin/tasks/uninstall.yml

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Check existence of Element Admin service
+  ansible.builtin.stat:
+    path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-element-admin.service"
+  register: matrix_element_admin_service_stat
+
+- when: matrix_element_admin_service_stat.stat.exists | bool
+  block:
+    - name: Ensure Element Admin is stopped
+      ansible.builtin.service:
+        name: matrix-element-admin
+        state: stopped
+        enabled: false
+        daemon_reload: true
+
+    - name: Ensure Element Admin systemd service doesn't exist
+      ansible.builtin.file:
+        path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-element-admin.service"
+        state: absent
+
+    - name: Ensure Element Admin paths don't exist
+      ansible.builtin.file:
+        path: "{{ matrix_element_admin_base_path }}"
+        state: absent

roles/custom/matrix-element-admin/tasks/validate_config.yml

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Fail if required Element Admin settings not defined
+  ansible.builtin.fail:
+    msg: >
+      You need to define a required configuration setting (`{{ item.name }}`).
+  when: "item.when | bool and lookup('vars', item.name, default='') | string | length == 0"
+  with_items:
+    - {'name': 'matrix_element_admin_hostname', when: true}
+    - {'name': 'matrix_element_admin_path_prefix', when: true}
+    - {'name': 'matrix_element_admin_container_network', when: true}
+    - {'name': 'matrix_element_admin_environment_variable_server_name', when: true}
+
+# Element Admin appears to hardcode all paths to `/` (e.g. `/config.json`, `/assets/...`).
+# While we can properly serve the homepage and handle stripping the path prefix on our side,
+# the hardcoded URLs in the Element Admin are pointing people to the wrong place, which is a problem.
+- name: Fail if Element Admin path prefix is different than /
+  ansible.builtin.fail:
+    msg: >-
+      Element Admin with a path prefix other than '/' is not supported yet.
+      You have configured matrix_element_admin_path_prefix to '{{ matrix_element_admin_path_prefix }}'.
+  when: "matrix_element_admin_path_prefix != '/'"

roles/custom/matrix-element-admin/templates/env.j2

@@ -0,0 +1,9 @@
+{#
+SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+SERVER_NAME={{ matrix_element_admin_environment_variable_server_name }}
+
+{{ matrix_element_admin_environment_variables_additional_variables }}

roles/custom/matrix-element-admin/templates/labels.j2

@@ -0,0 +1,45 @@
+{#
+SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+{% if matrix_element_admin_container_labels_traefik_enabled %}
+traefik.enable=true
+
+{% if matrix_element_admin_container_labels_traefik_docker_network %}
+traefik.docker.network={{ matrix_element_admin_container_labels_traefik_docker_network }}
+{% endif %}
+
+traefik.http.services.matrix-element-admin.loadbalancer.server.port=8080
+
+{% set middlewares = [] %}
+
+{% if matrix_element_admin_container_labels_traefik_path_prefix != '/' %}
+traefik.http.middlewares.matrix-element-admin-slashless-redirect.redirectregex.regex=({{ matrix_element_admin_container_labels_traefik_path_prefix | quote }})$
+traefik.http.middlewares.matrix-element-admin-slashless-redirect.redirectregex.replacement=${1}/
+{% set middlewares = middlewares + ['matrix-element-admin-slashless-redirect'] %}
+{% endif %}
+
+{% if matrix_element_admin_container_labels_traefik_path_prefix != '/' %}
+traefik.http.middlewares.matrix-element-admin-strip-prefix.stripprefix.prefixes={{ matrix_element_admin_container_labels_traefik_path_prefix }}
+{% set middlewares = middlewares + ['matrix-element-admin-strip-prefix'] %}
+{% endif %}
+
+traefik.http.routers.matrix-element-admin.rule={{ matrix_element_admin_container_labels_traefik_rule }}
+{% if matrix_element_admin_container_labels_traefik_priority | int > 0 %}
+traefik.http.routers.matrix-element-admin.priority={{ matrix_element_admin_container_labels_traefik_priority }}
+{% endif %}
+traefik.http.routers.matrix-element-admin.service=matrix-element-admin
+{% if middlewares | length > 0 %}
+traefik.http.routers.matrix-element-admin.middlewares={{ middlewares | join(',') }}
+{% endif %}
+traefik.http.routers.matrix-element-admin.entrypoints={{ matrix_element_admin_container_labels_traefik_entrypoints }}
+traefik.http.routers.matrix-element-admin.tls={{ matrix_element_admin_container_labels_traefik_tls | to_json }}
+{% if matrix_element_admin_container_labels_traefik_tls %}
+traefik.http.routers.matrix-element-admin.tls.certResolver={{ matrix_element_admin_container_labels_traefik_tls_certResolver }}
+{% endif %}
+
+{% endif %}
+
+{{ matrix_element_admin_container_labels_additional_labels }}

roles/custom/matrix-element-admin/templates/systemd/matrix-element-admin.service.j2

@@ -0,0 +1,52 @@
+#jinja2: lstrip_blocks: True
+[Unit]
+Description=Element Admin
+{% for service in matrix_element_admin_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_element_admin_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}"
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-element-admin 2>/dev/null || true'
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-element-admin 2>/dev/null || true'
+
+{#
+	We mount a tmpfs at /tmp, because `/docker-entrypoint.d/replace-config.sh` writes temporary files there.
+#}
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
+			--rm \
+			--name=matrix-element-admin \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--read-only \
+			--network={{ matrix_element_admin_container_network }} \
+			--env-file={{ matrix_element_admin_base_path }}/env \
+			--label-file={{ matrix_element_admin_base_path }}/labels \
+			--tmpfs=/tmp:rw,noexec,nosuid,size=1024m \
+			{% for arg in matrix_element_admin_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_element_admin_container_image }} {{ matrix_element_admin_container_process_extra_arguments | join(' ') }}
+
+{% for network in matrix_element_admin_container_additional_networks %}
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-element-admin
+{% endfor %}
+
+ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-element-admin
+
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-element-admin 2>/dev/null || true'
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-element-admin 2>/dev/null || true'
+
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-element-admin
+
+[Install]
+WantedBy=multi-user.target

roles/custom/matrix-element-admin/templates/systemd/matrix-element-admin.service.j2.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later