From ba0a4e864af298bf262e49626767221f96e56159 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 5 Jan 2024 17:54:50 +0200
Subject: [PATCH] Replace matrix-mailer with an external role

---
 CHANGELOG.md                                  | 18 ++++++
 docs/configuring-playbook-email.md            | 40 ++++++-------
 docs/faq.md                                   |  2 +-
 group_vars/matrix_servers                     | 58 +++++++++++-------
 requirements.yml                              |  3 +
 .../tasks/setup_install.yml                   |  2 +-
 .../matrix-bot-chatgpt/tasks/install.yml      |  2 +-
 .../tasks/setup_install.yml                   |  2 +-
 .../tasks/setup_install.yml                   |  2 +-
 .../tasks/setup_install.yml                   |  2 +-
 .../tasks/setup_install.yml                   |  2 +-
 .../tasks/setup_install.yml                   |  2 +-
 roles/custom/matrix-mailer/defaults/main.yml  | 35 -----------
 roles/custom/matrix-mailer/tasks/main.yml     | 17 ------
 .../matrix-mailer/tasks/setup_install.yml     | 60 -------------------
 .../matrix-mailer/tasks/setup_uninstall.yml   | 25 --------
 .../matrix-mailer/templates/env-mailer.j2     |  9 ---
 .../systemd/matrix-mailer.service.j2          | 37 ------------
 .../matrix_playbook_migration/tasks/main.yml  |  6 ++
 .../tasks/migrate_matrix_mailer.yml           | 39 ++++++++++++
 .../tasks/validate_config.yml                 | 14 +++++
 setup.yml                                     |  2 +-
 22 files changed, 145 insertions(+), 234 deletions(-)
 delete mode 100644 roles/custom/matrix-mailer/defaults/main.yml
 delete mode 100644 roles/custom/matrix-mailer/tasks/main.yml
 delete mode 100644 roles/custom/matrix-mailer/tasks/setup_install.yml
 delete mode 100644 roles/custom/matrix-mailer/tasks/setup_uninstall.yml
 delete mode 100644 roles/custom/matrix-mailer/templates/env-mailer.j2
 delete mode 100644 roles/custom/matrix-mailer/templates/systemd/matrix-mailer.service.j2
 create mode 100644 roles/custom/matrix_playbook_migration/tasks/migrate_matrix_mailer.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2975ff562..c8a109e01 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,21 @@
+# 2024-01-05
+
+## matrix-mailer has been replaced by the exim-relay external role
+
+We're continuing our effort to make [the playbook use external roles for some things](#the-playbook-now-uses-external-roles-for-some-things), so as to avoid doing everything ourselves and to facilitate code re-use.
+
+The `matrix-mailer` role has been moved to its own repository ([ansible-role-exim-relay](https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay)) that this playbook now includes.
+
+To migrate:
+
+- pull the playbook changes, as usual
+- update your roles (run `just roles` or `make roles`)
+- update your `vars.yml`, renaming `matrix_mailer`-prefixed variables to `exim_relay`-prefixed ones (e.g. `matrix_mailer_sender_address` -> `exim_relay_sender_address`). If you find none, it means you're using the default configuration and your migraiton job is even simpler.
+- re-run the playbook (`install-all` or `setup-all`)
+
+The playbook will take care of stopping the old `matrix-mailer` systemd service, relocating its directory and restarting it under the new name (`matrix-exim-relay.service`).
+
+
 # 2024-01-02
 
 ## mautrix-signal now powered by the new Go-based bridge
diff --git a/docs/configuring-playbook-email.md b/docs/configuring-playbook-email.md
index d9721a4ef..ae479bc98 100644
--- a/docs/configuring-playbook-email.md
+++ b/docs/configuring-playbook-email.md
@@ -5,9 +5,9 @@ By default, this playbook sets up an [Exim](https://www.exim.org/) email server
 The email server would attempt to deliver emails directly to their final destination.
 This may or may not work, depending on your domain configuration (SPF settings, etc.)
 
-By default, emails are sent from `matrix@<your-domain-name>` (as specified by the `matrix_mailer_sender_address` playbook variable).
+By default, emails are sent from `matrix@<your-domain-name>` (as specified by the `exim_relay_sender_address` playbook variable).
 
-**Note**: If you are using a Google Cloud instance, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so you need to relay email through another SMTP server as described below.   
+**Note**: If you are using a Google Cloud instance, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so you need to relay email through another SMTP server as described below.
 
 
 ## Firewall settings
@@ -21,35 +21,35 @@ If you'd like to relay email through another SMTP server, feel free to redefine
 Example:
 
 ```yaml
-matrix_mailer_sender_address: "another.sender@example.com"
-matrix_mailer_relay_use: true
-matrix_mailer_relay_host_name: "mail.example.com"
-matrix_mailer_relay_host_port: 587
-matrix_mailer_relay_auth: true
-matrix_mailer_relay_auth_username: "another.sender@example.com"
-matrix_mailer_relay_auth_password: "some-password"
+exim_relay_sender_address: "another.sender@example.com"
+exim_relay_relay_use: true
+exim_relay_relay_host_name: "mail.example.com"
+exim_relay_relay_host_port: 587
+exim_relay_relay_auth: true
+exim_relay_relay_auth_username: "another.sender@example.com"
+exim_relay_relay_auth_password: "some-password"
 ```
 
 **Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.
 
 
 ### Configuations for sending emails using Sendgrid
-An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `matrix_mailer_sender_address`.
+An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `exim_relay_sender_address`.
 
-The only other thing you need to change is the `matrix_mailer_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
+The only other thing you need to change is the `exim_relay_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
 
-Note that the `matrix_mailer_relay_auth_username` is literally the string `apikey`, it's always the same for Sendgrid.
+Note that the `exim_relay_relay_auth_username` is literally the string `apikey`, it's always the same for Sendgrid.
 
 ```yaml
-matrix_mailer_sender_address: "arbitrary@email.com"
-matrix_mailer_relay_use: true
-matrix_mailer_relay_host_name: "smtp.sendgrid.net"
-matrix_mailer_relay_host_port: 587
-matrix_mailer_relay_auth: true
-matrix_mailer_relay_auth_username: "apikey"
-matrix_mailer_relay_auth_password: "<your api key password>" 
+exim_relay_sender_address: "arbitrary@email.com"
+exim_relay_relay_use: true
+exim_relay_relay_host_name: "smtp.sendgrid.net"
+exim_relay_relay_host_port: 587
+exim_relay_relay_auth: true
+exim_relay_relay_auth_username: "apikey"
+exim_relay_relay_auth_password: "<your api key password>"
 ```
 
 ## Troubleshooting
 
-If you're having trouble with email not being delivered, it may be useful to inspect the mailer logs: `journalctl -f -u matrix-mailer`.
+If you're having trouble with email not being delivered, it may be useful to inspect the mailer logs: `journalctl -f -u matrix-exim-relay`.
diff --git a/docs/faq.md b/docs/faq.md
index d47c8b77d..74b9b6249 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -285,7 +285,7 @@ You can disable some not-so-important services to save on memory.
 matrix_ma1sd_enabled: false
 
 # Disabling this will prevent email-notifications and other such things from working.
-matrix_mailer_enabled: false
+exim_relay_enabled: false
 
 # You can also disable this to save more RAM,
 # at the expense of audio/video calls being unreliable.
diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index efc2a94d4..7759c1dd5 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -346,7 +346,7 @@ devture_systemd_service_manager_services_list_auto: |
     +
     ([{'name': (matrix_media_repo_identifier + '.service'), 'priority': 4000, 'groups': ['matrix', 'matrix-media-repo']}] if matrix_media_repo_enabled else [])
     +
-    ([{'name': 'matrix-mailer.service', 'priority': 2000, 'groups': ['matrix', 'mailer']}] if matrix_mailer_enabled else [])
+    ([{'name': (exim_relay_identifier ~ '.service'), 'priority': 2000, 'groups': ['matrix', 'mailer', 'exim-relay']}] if exim_relay_enabled else [])
     +
     ([{'name': 'matrix-nginx-proxy.service', 'priority': 3000, 'groups': ['matrix', 'nginx', 'nginx-proxy', 'reverse-proxies']}] if matrix_nginx_proxy_enabled else [])
     +
@@ -2605,24 +2605,38 @@ matrix_ldap_registration_proxy_enabled: false
 #
 ######################################################################
 
-######################################################################
-#
-# matrix-mailer
-#
-######################################################################
 
-# By default, this playbook sets up an exim mailer server (running in a container).
-# This is so that Synapse can send email reminders for unread messages.
-# Other services (like ma1sd), also use the mailer.
-matrix_mailer_enabled: true
+########################################################################
+#                                                                      #
+# exim-relay                                                           #
+#                                                                      #
+########################################################################
 
-matrix_mailer_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm32', 'arm64'] }}"
+# We set up an Exim email relay by default.
+# This is so that the homeserver and various other services can send emails through it.
+# To completely disable this service, use: `exim_relay_enabled: false`
+
+exim_relay_identifier: "matrix-exim-relay"
+
+exim_relay_base_path: "{{ matrix_base_data_path }}/exim-relay"
+
+exim_relay_uid: "{{ matrix_user_uid }}"
+exim_relay_gid: "{{ matrix_user_gid }}"
+
+exim_relay_container_network: "{{ matrix_docker_network }}"
+
+exim_relay_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm32', 'arm64'] }}"
+
+exim_relay_hostname: "{{ matrix_server_fqn_matrix }}"
+
+exim_relay_sender_address: "matrix@{{ matrix_domain }}"
+
+########################################################################
+#                                                                      #
+# /exim-relay                                                          #
+#                                                                      #
+########################################################################
 
-######################################################################
-#
-# /matrix-mailer
-#
-######################################################################
 
 ######################################################################
 #
@@ -2663,7 +2677,7 @@ matrix_ma1sd_dns_overwrite_homeserver_client_name: "{{ matrix_server_fqn_matrix
 matrix_ma1sd_dns_overwrite_homeserver_client_value: "{{ matrix_homeserver_container_url }}"
 
 # By default, we send mail through the `matrix-mailer` service.
-matrix_ma1sd_threepid_medium_email_identity_from: "{{ matrix_mailer_sender_address }}"
+matrix_ma1sd_threepid_medium_email_identity_from: "{{ exim_relay_sender_address }}"
 matrix_ma1sd_threepid_medium_email_connectors_smtp_host: "matrix-mailer"
 matrix_ma1sd_threepid_medium_email_connectors_smtp_port: 8025
 matrix_ma1sd_threepid_medium_email_connectors_smtp_tls: 0
@@ -2681,7 +2695,7 @@ matrix_ma1sd_systemd_wanted_services_list: |
     +
     ([devture_postgres_identifier ~ '.service'] if devture_postgres_enabled else [])
     +
-    (['matrix-mailer.service'] if matrix_mailer_enabled else [])
+    ([exim_relay_identifier ~ '.service'] if exim_relay_enabled else [])
   }}
 
 # Postgres is the default, except if not using internal Postgres server
@@ -3633,11 +3647,11 @@ matrix_synapse_federation_port_openid_resource_required: "{{ not matrix_synapse_
 # If someone instals Prometheus via the playbook, they most likely wish to monitor Synapse.
 matrix_synapse_metrics_enabled: "{{ prometheus_enabled }}"
 
-matrix_synapse_email_enabled: "{{ matrix_mailer_enabled }}"
-matrix_synapse_email_smtp_host: "matrix-mailer"
+matrix_synapse_email_enabled: "{{ exim_relay_enabled }}"
+matrix_synapse_email_smtp_host: "{{ exim_relay_identifier }}"
 matrix_synapse_email_smtp_port: 8025
 matrix_synapse_email_smtp_require_transport_security: false
-matrix_synapse_email_notif_from: "Matrix <{{ matrix_mailer_sender_address }}>"
+matrix_synapse_email_notif_from: "Matrix <{{ exim_relay_sender_address }}>"
 
 # Even if TURN doesn't support TLS (it does by default),
 # it doesn't hurt to try a secure connection anyway.
@@ -3679,7 +3693,7 @@ matrix_synapse_systemd_wanted_services_list: |
   {{
     (['matrix-coturn.service'] if matrix_coturn_enabled else [])
     +
-    (['matrix-mailer.service'] if matrix_mailer_enabled else [])
+    ([exim_relay_identifier ~ '.service'] if exim_relay_enabled else [])
   }}
 
 # Synapse workers (used for parallel load-scaling) need Redis for IPC.
diff --git a/requirements.yml b/requirements.yml
index 649fe5247..4ff9f8350 100644
--- a/requirements.yml
+++ b/requirements.yml
@@ -18,6 +18,9 @@
 - src: git+https://gitlab.com/etke.cc/roles/etherpad.git
   version: v1.9.6-0
   name: etherpad
+- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay.git
+  version: v4.97-r0-0-0
+  name: exim_relay
 - src: git+https://gitlab.com/etke.cc/roles/grafana.git
   version: v10.2.3-0
   name: grafana
diff --git a/roles/custom/matrix-bot-buscarron/tasks/setup_install.yml b/roles/custom/matrix-bot-buscarron/tasks/setup_install.yml
index 1c2c62e14..51548749d 100644
--- a/roles/custom/matrix-bot-buscarron/tasks/setup_install.yml
+++ b/roles/custom/matrix-bot-buscarron/tasks/setup_install.yml
@@ -79,7 +79,7 @@
     name: "{{ matrix_bot_buscarron_docker_image }}"
     source: build
     force_source: "{{ matrix_bot_buscarron_git_pull_results.changed 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_mailer_git_pull_results.changed }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_bot_buscarron_git_pull_results.changed }}"
     build:
       dockerfile: Dockerfile
       path: "{{ matrix_bot_buscarron_docker_src_files_path }}"
diff --git a/roles/custom/matrix-bot-chatgpt/tasks/install.yml b/roles/custom/matrix-bot-chatgpt/tasks/install.yml
index ef31df066..5265e4508 100644
--- a/roles/custom/matrix-bot-chatgpt/tasks/install.yml
+++ b/roles/custom/matrix-bot-chatgpt/tasks/install.yml
@@ -50,7 +50,7 @@
         name: "{{ matrix_bot_chatgpt_container_image }}"
         source: build
         force_source: "{{ matrix_bot_chatgpt_git_pull_results.changed 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_mailer_git_pull_results.changed }}"
+        force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_bot_chatgpt_git_pull_results.changed }}"
         build:
           dockerfile: Dockerfile
           path: "{{ matrix_bot_chatgpt_container_src_path }}"
diff --git a/roles/custom/matrix-bot-honoroit/tasks/setup_install.yml b/roles/custom/matrix-bot-honoroit/tasks/setup_install.yml
index 12d3ff1fd..faf905363 100644
--- a/roles/custom/matrix-bot-honoroit/tasks/setup_install.yml
+++ b/roles/custom/matrix-bot-honoroit/tasks/setup_install.yml
@@ -102,7 +102,7 @@
     name: "{{ matrix_bot_honoroit_docker_image }}"
     source: build
     force_source: "{{ matrix_bot_honoroit_git_pull_results.changed 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_mailer_git_pull_results.changed }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_bot_honoroit_container_image_self_build.changed }}"
     build:
       dockerfile: Dockerfile
       path: "{{ matrix_bot_honoroit_docker_src_files_path }}"
diff --git a/roles/custom/matrix-bot-matrix-registration-bot/tasks/setup_install.yml b/roles/custom/matrix-bot-matrix-registration-bot/tasks/setup_install.yml
index 655f3d275..2532ab522 100644
--- a/roles/custom/matrix-bot-matrix-registration-bot/tasks/setup_install.yml
+++ b/roles/custom/matrix-bot-matrix-registration-bot/tasks/setup_install.yml
@@ -49,7 +49,7 @@
     name: "{{ matrix_bot_matrix_registration_bot_docker_image }}"
     source: build
     force_source: "{{ matrix_bot_matrix_registration_bot_git_pull_results.changed 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_mailer_git_pull_results.changed }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_bot_matrix_registration_bot_git_pull_results.changed }}"
     build:
       dockerfile: Dockerfile
       path: "{{ matrix_bot_matrix_registration_bot_docker_src_files_path }}"
diff --git a/roles/custom/matrix-bot-matrix-reminder-bot/tasks/setup_install.yml b/roles/custom/matrix-bot-matrix-reminder-bot/tasks/setup_install.yml
index 39bf63e64..267cbaecd 100644
--- a/roles/custom/matrix-bot-matrix-reminder-bot/tasks/setup_install.yml
+++ b/roles/custom/matrix-bot-matrix-reminder-bot/tasks/setup_install.yml
@@ -69,7 +69,7 @@
     name: "{{ matrix_bot_matrix_reminder_bot_docker_image }}"
     source: build
     force_source: "{{ matrix_bot_matrix_reminder_bot_git_pull_results.changed 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_mailer_git_pull_results.changed }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_bot_matrix_reminder_bot_git_pull_results.changed }}"
     build:
       dockerfile: docker/Dockerfile
       path: "{{ matrix_bot_matrix_reminder_bot_docker_src_files_path }}"
diff --git a/roles/custom/matrix-bot-postmoogle/tasks/setup_install.yml b/roles/custom/matrix-bot-postmoogle/tasks/setup_install.yml
index ed2bcc9d6..24b62a0a2 100644
--- a/roles/custom/matrix-bot-postmoogle/tasks/setup_install.yml
+++ b/roles/custom/matrix-bot-postmoogle/tasks/setup_install.yml
@@ -72,7 +72,7 @@
     name: "{{ matrix_bot_postmoogle_docker_image }}"
     source: build
     force_source: "{{ matrix_bot_postmoogle_git_pull_results.changed 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_mailer_git_pull_results.changed }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_bot_postmoogle_git_pull_results.changed }}"
     build:
       dockerfile: Dockerfile
       path: "{{ matrix_bot_postmoogle_docker_src_files_path }}"
diff --git a/roles/custom/matrix-cactus-comments/tasks/setup_install.yml b/roles/custom/matrix-cactus-comments/tasks/setup_install.yml
index 03b97d0ad..1904a7008 100644
--- a/roles/custom/matrix-cactus-comments/tasks/setup_install.yml
+++ b/roles/custom/matrix-cactus-comments/tasks/setup_install.yml
@@ -58,7 +58,7 @@
     name: "{{ matrix_cactus_comments_docker_image }}"
     source: build
     force_source: "{{ matrix_cactus_comments_git_pull_results.changed 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_mailer_git_pull_results.changed }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_cactus_comments_git_pull_results.changed }}"
     build:
       dockerfile: Dockerfile
       path: "{{ matrix_cactus_comments_docker_src_files_path }}"
diff --git a/roles/custom/matrix-mailer/defaults/main.yml b/roles/custom/matrix-mailer/defaults/main.yml
deleted file mode 100644
index dd56f89e6..000000000
--- a/roles/custom/matrix-mailer/defaults/main.yml
+++ /dev/null
@@ -1,35 +0,0 @@
----
-# Project source code URL: https://github.com/devture/exim-relay
-
-matrix_mailer_enabled: true
-
-matrix_mailer_base_path: "{{ matrix_base_data_path }}/mailer"
-
-matrix_mailer_container_image_self_build: false
-matrix_mailer_container_image_self_build_repository_url: "https://github.com/devture/exim-relay"
-matrix_mailer_container_image_self_build_src_files_path: "{{ matrix_mailer_base_path }}/docker-src"
-matrix_mailer_container_image_self_build_version: "{{ matrix_mailer_docker_image.split(':')[1] }}"
-
-# renovate: datasource=docker depName=devture/exim-relay versioning=semver
-matrix_mailer_version: 4.97-r0-0
-matrix_mailer_docker_image: "{{ matrix_mailer_docker_image_name_prefix }}devture/exim-relay:{{ matrix_mailer_version }}"
-matrix_mailer_docker_image_name_prefix: "{{ 'localhost/' if matrix_mailer_container_image_self_build else matrix_container_global_registry_prefix }}"
-matrix_mailer_docker_image_force_pull: "{{ matrix_mailer_docker_image.endswith(':latest') }}"
-
-# The user/group that the container runs with.
-# These match the `exim` user/group within the container image.
-matrix_mailer_container_user_uid: 100
-matrix_mailer_container_user_gid: 101
-
-# A list of extra arguments to pass to the container
-matrix_mailer_container_extra_arguments: []
-
-matrix_mailer_hostname: "{{ matrix_server_fqn_matrix }}"
-
-matrix_mailer_sender_address: "matrix@{{ matrix_domain }}"
-matrix_mailer_relay_use: false
-matrix_mailer_relay_host_name: "mail.example.com"
-matrix_mailer_relay_host_port: 587
-matrix_mailer_relay_auth: false
-matrix_mailer_relay_auth_username: ""
-matrix_mailer_relay_auth_password: ""
diff --git a/roles/custom/matrix-mailer/tasks/main.yml b/roles/custom/matrix-mailer/tasks/main.yml
deleted file mode 100644
index 00fa0884e..000000000
--- a/roles/custom/matrix-mailer/tasks/main.yml
+++ /dev/null
@@ -1,17 +0,0 @@
----
-
-- tags:
-    - setup-all
-    - setup-mailer
-    - install-all
-    - install-mailer
-  block:
-    - when: matrix_mailer_enabled | bool
-      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
-
-- tags:
-    - setup-all
-    - setup-mailer
-  block:
-    - when: not matrix_mailer_enabled | bool
-      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
diff --git a/roles/custom/matrix-mailer/tasks/setup_install.yml b/roles/custom/matrix-mailer/tasks/setup_install.yml
deleted file mode 100644
index c03d0af64..000000000
--- a/roles/custom/matrix-mailer/tasks/setup_install.yml
+++ /dev/null
@@ -1,60 +0,0 @@
----
-
-- name: Ensure mailer base path exists
-  ansible.builtin.file:
-    path: "{{ item.path }}"
-    state: directory
-    mode: 0750
-    owner: "{{ matrix_user_username }}"
-    group: "{{ matrix_user_groupname }}"
-  with_items:
-    - {path: "{{ matrix_mailer_base_path }}", when: true}
-    - {path: "{{ matrix_mailer_container_image_self_build_src_files_path }}", when: "{{ matrix_mailer_container_image_self_build }}"}
-  when: item.when | bool
-
-- name: Ensure mailer environment variables file created
-  ansible.builtin.template:
-    src: "{{ role_path }}/templates/env-mailer.j2"
-    dest: "{{ matrix_mailer_base_path }}/env-mailer"
-    mode: 0640
-
-- name: Ensure exim-relay repository is present on self-build
-  ansible.builtin.git:
-    repo: "{{ matrix_mailer_container_image_self_build_repository_url }}"
-    dest: "{{ matrix_mailer_container_image_self_build_src_files_path }}"
-    version: "{{ matrix_mailer_container_image_self_build_version }}"
-    force: "yes"
-  become: true
-  become_user: "{{ matrix_user_username }}"
-  register: matrix_mailer_git_pull_results
-  when: matrix_mailer_container_image_self_build | bool
-
-- name: Ensure exim-relay Docker image is built
-  community.docker.docker_image:
-    name: "{{ matrix_mailer_docker_image }}"
-    source: build
-    force_source: "{{ matrix_mailer_git_pull_results.changed 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_mailer_git_pull_results.changed }}"
-    build:
-      dockerfile: Dockerfile
-      path: "{{ matrix_mailer_container_image_self_build_src_files_path }}"
-      pull: true
-  when: matrix_mailer_container_image_self_build | bool
-
-- name: Ensure exim-relay image is pulled
-  community.docker.docker_image:
-    name: "{{ matrix_mailer_docker_image }}"
-    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
-    force_source: "{{ matrix_mailer_docker_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_mailer_docker_image_force_pull }}"
-  when: "not matrix_mailer_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
-
-- name: Ensure matrix-mailer.service installed
-  ansible.builtin.template:
-    src: "{{ role_path }}/templates/systemd/matrix-mailer.service.j2"
-    dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-mailer.service"
-    mode: 0644
diff --git a/roles/custom/matrix-mailer/tasks/setup_uninstall.yml b/roles/custom/matrix-mailer/tasks/setup_uninstall.yml
deleted file mode 100644
index fce8a4362..000000000
--- a/roles/custom/matrix-mailer/tasks/setup_uninstall.yml
+++ /dev/null
@@ -1,25 +0,0 @@
----
-
-- name: Check existence of matrix-mailer service
-  ansible.builtin.stat:
-    path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-mailer.service"
-  register: matrix_mailer_service_stat
-
-- when: matrix_mailer_service_stat.stat.exists | bool
-  block:
-    - name: Ensure matrix-mailer is stopped
-      ansible.builtin.service:
-        name: matrix-mailer
-        state: stopped
-        enabled: false
-        daemon_reload: true
-
-    - name: Ensure matrix-mailer.service doesn't exist
-      ansible.builtin.file:
-        path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-mailer.service"
-        state: absent
-
-    - name: Ensure Matrix mailer path doesn't exist
-      ansible.builtin.file:
-        path: "{{ matrix_mailer_base_path }}"
-        state: absent
diff --git a/roles/custom/matrix-mailer/templates/env-mailer.j2 b/roles/custom/matrix-mailer/templates/env-mailer.j2
deleted file mode 100644
index eb3f86999..000000000
--- a/roles/custom/matrix-mailer/templates/env-mailer.j2
+++ /dev/null
@@ -1,9 +0,0 @@
-#jinja2: lstrip_blocks: "True"
-{% if matrix_mailer_relay_use %}
-SMARTHOST={{ matrix_mailer_relay_host_name }}::{{ matrix_mailer_relay_host_port }}
-{% endif %}
-{% if matrix_mailer_relay_auth %}
-SMTP_USERNAME={{ matrix_mailer_relay_auth_username }}
-SMTP_PASSWORD={{ matrix_mailer_relay_auth_password }}
-{% endif %}
-HOSTNAME={{ matrix_mailer_hostname }}
diff --git a/roles/custom/matrix-mailer/templates/systemd/matrix-mailer.service.j2 b/roles/custom/matrix-mailer/templates/systemd/matrix-mailer.service.j2
deleted file mode 100644
index 87d593a6f..000000000
--- a/roles/custom/matrix-mailer/templates/systemd/matrix-mailer.service.j2
+++ /dev/null
@@ -1,37 +0,0 @@
-#jinja2: lstrip_blocks: "True"
-[Unit]
-Description=Matrix mailer
-After=docker.service
-Requires=docker.service
-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 --time={{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-mailer 2>/dev/null || true'
-ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-mailer 2>/dev/null || true'
-
-# --hostname gives us a friendlier hostname than the default.
-# The real hostname is passed via a `HOSTNAME` environment variable though.
-ExecStart={{ devture_systemd_docker_base_host_command_docker }} run --rm --name matrix-mailer \
-			--log-driver=none \
-			--user={{ matrix_mailer_container_user_uid }}:{{ matrix_mailer_container_user_gid }} \
-			--cap-drop=ALL \
-			--read-only \
-			--tmpfs=/var/spool/exim:rw,noexec,nosuid,size=100m \
-			--network={{ matrix_docker_network }} \
-			--env-file={{ matrix_mailer_base_path }}/env-mailer \
-			--hostname=matrix-mailer \
-			{% for arg in matrix_mailer_container_extra_arguments %}
-			{{ arg }} \
-			{% endfor %}
-			{{ matrix_mailer_docker_image }}
-
-ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop --time={{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-mailer 2>/dev/null || true'
-ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-mailer 2>/dev/null || true'
-Restart=always
-RestartSec=30
-SyslogIdentifier=matrix-mailer
-
-[Install]
-WantedBy=multi-user.target
diff --git a/roles/custom/matrix_playbook_migration/tasks/main.yml b/roles/custom/matrix_playbook_migration/tasks/main.yml
index d6b24c395..c640ec771 100644
--- a/roles/custom/matrix_playbook_migration/tasks/main.yml
+++ b/roles/custom/matrix_playbook_migration/tasks/main.yml
@@ -21,6 +21,12 @@
   block:
     - ansible.builtin.include_tasks: "{{ role_path }}/tasks/cleanup_usr_local_bin.yml"
 
+- tags:
+    - setup-all
+    - install-all
+  block:
+    - ansible.builtin.include_tasks: "{{ role_path }}/tasks/migrate_matrix_mailer.yml"
+
 - when: devture_traefik_enabled | bool
   tags:
     - setup-all
diff --git a/roles/custom/matrix_playbook_migration/tasks/migrate_matrix_mailer.yml b/roles/custom/matrix_playbook_migration/tasks/migrate_matrix_mailer.yml
new file mode 100644
index 000000000..e1785774f
--- /dev/null
+++ b/roles/custom/matrix_playbook_migration/tasks/migrate_matrix_mailer.yml
@@ -0,0 +1,39 @@
+---
+
+# This migrates the mailer from the old path (`/matrix/mailer`) to the new path (`/matrix/exim-relay`, controlled by `exim_relay_base_path`),
+# and from the old hardcoded systemd service name (`matrix-mailer.service`) to the new one (`matrix-exim-relay.service`, controlled by `exim_relay_identifier`).
+#
+# Here, we merely disable (and stop) the old systemd service and relocate the base directory path (`/matrix/mailer`).
+# The exim-relay role itself (running later) will then ensure this data is up-to-date and will set up the new systemd service.
+
+# It only makes sense to migrate if the identifier or path are different than the default (what we were using before).
+- name: Check existence of matrix-mailer.service systemd service
+  ansible.builtin.stat:
+    path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-mailer.service"
+  register: matrix_mailer_service_stat
+
+- when: matrix_mailer_service_stat.stat.exists | bool
+  block:
+    - name: Ensure matrix-mailer.service systemd service is stopped
+      ansible.builtin.systemd:
+        name: matrix-mailer
+        state: stopped
+        enabled: false
+        daemon_reload: true
+
+    - name: Ensure matrix-mailer directory relocated
+      ansible.builtin.command:
+        cmd: "mv {{ matrix_base_data_path }}/mailer {{ exim_relay_base_path }}"
+        creates: "{{ exim_relay_base_path }}"
+        removes: "{{ matrix_base_data_path }}"
+
+    # Remove legacy env-mailer file (named `env` in the new role)
+    - name: Ensure old exim-relay environment variables file is deleted
+      ansible.builtin.file:
+        path: "{{ exim_relay_base_path }}/env-mailer"
+        state: absent
+
+    - name: Ensure matrix-mailer.service systemd service doesn't exist
+      ansible.builtin.file:
+        path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-mailer.service"
+        state: absent
diff --git a/roles/custom/matrix_playbook_migration/tasks/validate_config.yml b/roles/custom/matrix_playbook_migration/tasks/validate_config.yml
index c61a51957..538249f73 100644
--- a/roles/custom/matrix_playbook_migration/tasks/validate_config.yml
+++ b/roles/custom/matrix_playbook_migration/tasks/validate_config.yml
@@ -59,6 +59,9 @@
     - {'old': 'matrix_prosody_jitsi_max_participants', 'new': 'jitsi_prosody_max_participants'}
     - {'old': 'jitsi_require_well_known', 'new': 'jitsi_web_well_known_element_jitsi_enabled'}
     - {'old': 'jitsi_wellknown_element_jitsi_json', 'new': 'jitsi_web_well_known_element_jitsi_json'}
+    - {'old': 'exim_relay_docker_image', 'new': 'exim_relay_container_image'}
+    - {'old': 'exim_relay_docker_image_name_prefix', 'new': 'exim_relay_container_image_name_prefix'}
+    - {'old': 'exim_relay_docker_image_force_pull', 'new': 'exim_relay_container_image_force_pull'}
 
 - name: (Deprecation) Catch and report matrix_postgres variables
   ansible.builtin.fail:
@@ -74,6 +77,17 @@
       The following variables in your configuration need to be renamed: {{ vars | dict2items | selectattr('key', 'match', 'matrix_postgres_.*') | map (attribute='key') | join(', ') }}
   when: "vars | dict2items | selectattr('key', 'match', 'matrix_postgres_.*') | list | items2dict"
 
+- name: (Deprecation) Catch and report matrix_mailer_ variables
+  ansible.builtin.fail:
+    msg: |-
+      The matrix-mailer role in the playbook has been replaced with the exim-relay role (https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay).
+      The new role is pretty much the same, but uses differently named variables.
+
+      Please change your configuration (vars.yml) to rename all `matrix_mailer`-prefixed variables (`matrix_mailer_*` -> `exim_relay_*`).
+
+      The following variables in your configuration need to be renamed: {{ vars | dict2items | selectattr('key', 'match', 'matrix_mailer_.*') | map (attribute='key') | join(', ') }}
+  when: "vars | dict2items | selectattr('key', 'match', 'matrix_mailer_.*') | list | items2dict"
+
 - when: matrix_playbook_migration_matrix_prometheus_node_exporter_migration_validation_enabled | bool
   block:
     - ansible.builtin.set_fact:
diff --git a/setup.yml b/setup.yml
index 708c53f82..2a88faf05 100644
--- a/setup.yml
+++ b/setup.yml
@@ -40,7 +40,7 @@
 
     - custom/matrix-base
     - custom/matrix-dynamic-dns
-    - custom/matrix-mailer
+    - galaxy/exim_relay
 
     - role: galaxy/postgres