Add Pantalaimon support

This is actually authored by Julian Foad here
(https://lab.trax.im/matrix/matrix-docker-ansible-deploy), but was in
need of a rebase and various adjustments caused by huge playbook
refactoring that landed in the past months.

This rework is completely untested.

Fixes https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/266

CHANGELOG.md

@@ -1,3 +1,12 @@
+# 2024-03-24
+
+## Pantalaimon support
+
+Thanks to [Julian Foad](https://matrix.to/#/@julian:foad.me.uk), the playbook can now install the [Pantalaimon](https://github.com/matrix-org/pantalaimon) E2EE aware proxy daemon for you. It's already possible to integrate it with [Draupnir](docs/configuring-playbook-bot-draupnir.md) to allow it to work in E2EE rooms - see our Draupnir docs for details.
+
+See our [Setting up Pantalaimon](docs/configuring-playbook-pantalaimon.md) documentation to get started.
+
+
 # 2024-03-05
 
 ## Support for Draupnir-for-all

README.md

@@ -172,6 +172,7 @@ Various services that don't fit any other category.
 | [Etherpad](https://etherpad.org) | x | An open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
 | [Jitsi](https://jitsi.org/) | x | An open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
 | [Cactus Comments](https://cactus.chat) | x | A federated comment system built on matrix | [Link](docs/configuring-playbook-cactus-comments.md) |
+| [Pantalaimon](https://github.com/matrix-org/pantalaimon) | x | An E2EE aware proxy daemon | [Link](docs/configuring-playbook-pantalaimon.md) |
 
 
 ## Installation

docs/configuring-playbook-bot-draupnir.md

@@ -43,14 +43,57 @@ The following command works on semi up to date Windows 10 installs and All Windo
 
 ## 4. Create a management room
 
-Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room. The room must be unencrypted since the playbook does not support installing Pantalaimon yet.
+Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
+
+If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below).
 
 Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element you can do this by going to the room's settings, clicking Advanced, and then coping the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:DOMAIN`.
 
 Finally invite the `@bot.draupnir:DOMAIN` account you created earlier into the room.
 
 
-## 5a. Adjusting the playbook configuration
+## 5. Adjusting the playbook configuration
+
+Decide whether you want Draupnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Draupnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
+
+### 5a. Configuration with E2EE support
+
+When using Pantalaimon, Draupnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+
+```yaml
+# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
+matrix_pantalaimon_enabled: true
+
+# Enable Draupnir
+matrix_bot_draupnir_enabled: true
+
+# Tell Draupnir to use Pantalaimon
+matrix_bot_draupnir_pantalaimon_use: true
+
+# User name and password for the bot. Required when using Pantalaimon.
+matrix_bot_draupnir_pantalaimon_username: "bot.draupnir"
+matrix_bot_draupnir_pantalaimon_password: ### you should create a secure password for the bot account
+
+matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+```
+
+The playbook's `group_vars` will configure other required settings. If using this role separately without the playbook, you also need to configure the two URLs that Draupnir uses to reach the homeserver, one through Pantalaimon and one "raw". This example is taken from the playbook's `group_vars`:
+
+```yaml
+# Endpoint URL that Draupnir uses to interact with the matrix homeserver (client-server API).
+# Set this to the pantalaimon URL if you're using that.
+matrix_bot_draupnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_draupnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
+
+# Endpoint URL that Draupnir could use to fetch events related to reports (client-server API and /_synapse/),
+# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
+matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+```
+
+### 5b. Configuration without E2EE support
+
+When NOT using Pantalaimon, Draupnir does not log in by itself and you must give it an access token for its bot account.
 
 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
@@ -64,7 +107,7 @@ matrix_bot_draupnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
 matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
 ```
 
-## 5b. Migrating from Mjolnir (Only required if migrating.)
+### 5c. Migrating from Mjolnir (Only required if migrating.)
 
 Replace your `matrix_bot_mjolnir` config with `matrix_bot_draupnir` config. Also disable mjolnir if you're doing migration.
 That is all you need to do due to that Draupnir can complete migration on its own.

docs/configuring-playbook-bot-mjolnir.md

@@ -37,7 +37,7 @@ The following command works on semi up to date Windows 10 installs and All Windo
 
 ## 4. Create a management room
 
-Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room. The room must be unencrypted since the playbook does not support installing Pantalaimon yet.
+Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room. The room must be unencrypted since this role does not support [using Pantalaimon](configuring-playbook-pantalaimon.md) yet.
 
 Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element you can do this by going to the room's settings, clicking Advanced, and then coping the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:DOMAIN`.
 

docs/configuring-playbook-pantalaimon.md

@@ -0,0 +1,21 @@
+# Setting up pantalaimon (optional)
+
+The playbook can install and configure the [pantalaimon](https://github.com/matrix-org/pantalaimon) E2EE aware proxy daemon for you.
+
+See the project's [documentation](https://github.com/matrix-org/pantalaimon) to learn what it does and why it might be useful to you.
+
+This role exposes Pantalaimon's API only within the container network, so bots and clients installed on the same machine can use it. In particular the [matrix-bot-draupnir](configuring-playbook-bot-draupnir.md) role and possibly others can use it.
+
+## 1. Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+
+```yaml
+matrix_pantalaimon_enabled: true
+```
+
+The default configuration should suffice. For advanced configuration, you can override the variables documented in the role's [defaults](../roles/custom/matrix-pantalaimon/defaults/main.yml).
+
+## 2. Installing
+
+After configuring the playbook, run the [installation](installing.md) command.

docs/configuring-playbook.md

@@ -105,7 +105,9 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional, advanced)
 
-- [Matrix User Verification Service](configuring-playbook-user-verification-service.md) (optional, advanced)
+- [Setting up Matrix User Verification Service](configuring-playbook-user-verification-service.md) (optional, advanced)
+
+- [Setting up Pantalaimon (E2EE aware proxy daemon)](configuring-playbook-pantalaimon.md) (optional, advanced)
 
 
 ### Bridging other networks

docs/self-building.md

@@ -40,6 +40,7 @@ Possibly outdated list of roles where self-building the Docker image is currentl
 - `matrix-bot-matrix-reminder-bot`
 - `matrix-bot-maubot`
 - `matrix-email2matrix`
+- `matrix-pantalaimon`
 
 Adding self-building support to other roles is welcome. Feel free to contribute!
 

group_vars/matrix_servers

@@ -72,7 +72,7 @@ matrix_homeserver_container_extra_arguments_auto: |
     (['--mount type=bind,src=' + matrix_appservice_discord_config_path + '/registration.yaml,dst=/matrix-appservice-discord-registration.yaml,ro'] if matrix_appservice_discord_enabled else [])
     +
     (['--mount type=bind,src=' + matrix_appservice_draupnir_for_all_config_path + '/draupnir-for-all-registration.yaml,dst=/matrix-appservice-draupnir-for-all-registration.yaml,ro'] if matrix_appservice_draupnir_for_all_enabled else [])
-    +    
+    +
     (['--mount type=bind,src=' + matrix_appservice_irc_config_path + '/registration.yaml,dst=/matrix-appservice-irc-registration.yaml,ro'] if matrix_appservice_irc_enabled else [])
     +
     (['--mount type=bind,src=' + matrix_appservice_kakaotalk_config_path + '/registration.yaml,dst=/matrix-appservice-kakaotalk-registration.yaml,ro'] if matrix_appservice_kakaotalk_enabled else [])
@@ -141,7 +141,7 @@ matrix_homeserver_app_service_config_files_auto: |
     (['/matrix-appservice-discord-registration.yaml'] if matrix_appservice_discord_enabled else [])
     +
     (['/matrix-appservice-draupnir-for-all-registration.yaml'] if matrix_appservice_draupnir_for_all_enabled else [])
-    +    
+    +
     (['/matrix-appservice-irc-registration.yaml'] if matrix_appservice_irc_enabled else [])
     +
     (['/matrix-appservice-kakaotalk-registration.yaml'] if matrix_appservice_kakaotalk_enabled else [])
@@ -275,7 +275,7 @@ devture_systemd_service_manager_services_list_auto: |
     ([{'name': 'matrix-appservice-discord.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'appservice-discord']}] if matrix_appservice_discord_enabled else [])
     +
     ([{'name': 'matrix-appservice-draupnir-for-all.service', 'priority': 4000, 'groups': ['matrix', 'bridges', 'draupnir-for-all', 'appservice-draupnir-for-all']}] if matrix_appservice_draupnir_for_all_enabled else [])
-    +    
+    +
     ([{'name': 'matrix-appservice-irc.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'appservice-irc']}] if matrix_appservice_irc_enabled else [])
     +
     ([{'name': 'matrix-appservice-kakaotalk.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'appservice-kakaotalk']}] if matrix_appservice_kakaotalk_enabled else [])
@@ -402,6 +402,8 @@ devture_systemd_service_manager_services_list_auto: |
     +
     ([{'name': (redis_identifier + '.service'), 'priority': 750, 'groups': ['matrix', 'redis']}] if redis_enabled else [])
     +
+    ([{'name': 'matrix-pantalaimon.service', 'priority': 4000, 'groups': ['matrix', 'pantalaimon']}] if matrix_pantalaimon_enabled else [])
+    +
     ([{'name': 'matrix-registration.service', 'priority': 4000, 'groups': ['matrix', 'registration', 'matrix-registration']}] if matrix_registration_enabled else [])
     +
     ([{'name': 'matrix-sliding-sync.service', 'priority': 1500, 'groups': ['matrix', 'sliding-sync']}] if matrix_sliding_sync_enabled else [])
@@ -2645,6 +2647,8 @@ matrix_bot_draupnir_enabled: false
 matrix_bot_draupnir_systemd_required_services_list_auto: |
   {{
     matrix_addons_homeserver_systemd_services_list
+    +
+    (['matrix-pantalaimon.service'] if matrix_bot_draupnir_pantalaimon_use else [])
   }}
 
 matrix_bot_draupnir_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm64'] }}"
@@ -2656,6 +2660,9 @@ matrix_bot_draupnir_container_additional_networks_auto: |-
     ([] if matrix_addons_homeserver_container_network == '' else [matrix_addons_homeserver_container_network])
   }}
 
+matrix_bot_draupnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_draupnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
+matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+
 ######################################################################
 #
 # /matrix-bot-draupnir
@@ -2705,6 +2712,32 @@ matrix_appservice_draupnir_for_all_database_password: "{{ '%s' | format(matrix_h
 ######################################################################
 
 
+######################################################################
+#
+# matrix-pantalaimon
+#
+######################################################################
+
+matrix_pantalaimon_enabled: false
+
+matrix_pantalaimon_systemd_required_services_list_auto: |
+  {{
+    matrix_addons_homeserver_systemd_services_list
+  }}
+
+matrix_pantalaimon_container_network: "{{ matrix_homeserver_container_network }}"
+
+matrix_pantalaimon_container_image_self_build: "{{ matrix_architecture not in ['amd64'] }}"
+
+matrix_pantalaimon_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+
+######################################################################
+#
+# /matrix-pantalaimon
+#
+######################################################################
+
+
 ######################################################################
 #
 # etke/backup_borg
@@ -3595,7 +3628,7 @@ devture_postgres_managed_databases_auto: |
       'username': matrix_appservice_draupnir_for_all_database_username,
       'password': matrix_appservice_draupnir_for_all_database_password,
     }] if (matrix_appservice_draupnir_for_all_enabled and matrix_appservice_draupnir_for_all_database_hostname == devture_postgres_connection_hostname) else [])
-    +    
+    +
     ([{
       'name': matrix_appservice_slack_database_name,
       'username': matrix_appservice_slack_database_username,

roles/custom/matrix-bot-draupnir/defaults/main.yml

@@ -37,15 +37,34 @@ matrix_bot_draupnir_systemd_required_services_list_custom: []
 # List of systemd services that matrix-bot-draupnir.service wants
 matrix_bot_draupnir_systemd_wanted_services_list: []
 
-# The access token for the bot user
+# Whether Draupnir should talk to the homeserver through Pantalaimon
+# If true, then other variables must be provided including pointing
+# `matrix_bot_draupnir_homeserver_url` to the Pantalaimon URL.
+matrix_bot_draupnir_pantalaimon_use: false
+
+# The access token for the bot user. Required when NOT using Pantalaimon.
+# (Otherwise provide `matrix_bot_draupnir_pantalaimon_username` and `matrix_bot_draupnir_pantalaimon_password` instead.)
 matrix_bot_draupnir_access_token: ""
 
+# User name and password for the bot. Required when using Pantalaimon.
+# (Otherwise provide `matrix_bot_draupnir_access_token` instead.)
+matrix_bot_draupnir_pantalaimon_username: "bot.draupnir"
+matrix_bot_draupnir_pantalaimon_password: ""
+
 # The room ID where people can use the bot. The bot has no access controls, so
 # anyone in this room can use the bot - secure your room!
 # This should be a room alias or room ID - not a matrix.to URL.
 # Note: draupnir is fairly verbose - expect a lot of messages from it.
 matrix_bot_draupnir_management_room: ""
 
+# Endpoint URL that Draupnir uses to interact with the matrix homeserver (client-server API).
+# Set this to the pantalaimon URL if you're using that.
+matrix_bot_draupnir_homeserver_url: ""
+
+# Endpoint URL that Draupnir could use to fetch events related to reports (client-server API and /_synapse/),
+# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
+matrix_bot_draupnir_raw_homeserver_url: ""
+
 # Disable Server ACL is used if you want to not give the bot the right to apply Server ACLs in rooms without complaints from the bot.
 # This setting is described the following way in the Configuration.
 #

roles/custom/matrix-bot-draupnir/tasks/validate_config.yml

@@ -2,9 +2,20 @@
 
 - name: Fail if required matrix-bot-draupnir variables are undefined
   ansible.builtin.fail:
-    msg: "The `{{ item }}` variable must be defined and have a non-null value."
+    msg: "The `{{ item.name }}` variable must be defined and have a non-null value."
   with_items:
-    - "matrix_bot_draupnir_access_token"
-    - "matrix_bot_draupnir_management_room"
-    - "matrix_bot_draupnir_container_network"
-  when: "vars[item] == '' or vars[item] is none"
+    - {'name': 'matrix_bot_draupnir_access_token', when: "{{ not matrix_bot_draupnir_pantalaimon_use }}"}
+    - {'name': 'matrix_bot_draupnir_management_room', when: true}
+    - {'name': 'matrix_bot_draupnir_container_network', when: true}
+    - {'name': 'matrix_bot_draupnir_homeserver_url', when: true}
+    - {'name': 'matrix_bot_draupnir_raw_homeserver_url', when: true}
+    - {'name': 'matrix_bot_draupnir_pantalaimon_username', when: "{{ matrix_bot_draupnir_pantalaimon_use }}"}
+    - {'name': 'matrix_bot_draupnir_pantalaimon_password', when: "{{ matrix_bot_draupnir_pantalaimon_use }}"}
+  when: "item.when | bool and (vars[item.name] == '' or vars[item.name] is none)"
+
+- name: Fail if inappropriate variables are defined
+  ansible.builtin.fail:
+    msg: "The `{{ item.name }}` variable must be undefined or have a null value."
+  with_items:
+    - {'name': 'matrix_bot_draupnir_access_token', when: "{{ matrix_bot_draupnir_pantalaimon_use }}"}
+  when: "item.when | bool and not (vars[item.name] == '' or vars[item.name] is none)"

roles/custom/matrix-bot-draupnir/templates/production.yaml.j2

@@ -1,32 +1,34 @@
 # Endpoint URL that Draupnir uses to interact with the matrix homeserver (client-server API),
 # set this to the pantalaimon URL if you're using that.
-homeserverUrl: "{{ matrix_homeserver_url }}"
+homeserverUrl: {{ matrix_bot_draupnir_homeserver_url | to_json }}
 
 # Endpoint URL that Draupnir could use to fetch events related to reports (client-server API and /_synapse/),
 # only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
-rawHomeserverUrl: "{{ matrix_homeserver_url }}"
+rawHomeserverUrl: {{ matrix_bot_draupnir_raw_homeserver_url | to_json }}
 
 # Matrix Access Token to use, Draupnir will only use this if pantalaimon.use is false.
-accessToken: "{{ matrix_bot_draupnir_access_token }}"
+accessToken: {{ matrix_bot_draupnir_access_token | to_json }}
 
+{% if matrix_bot_draupnir_pantalaimon_use %}
 # Options related to Pantalaimon (https://github.com/matrix-org/pantalaimon)
-#pantalaimon:
-#  # Whether or not Draupnir will use pantalaimon to access the matrix homeserver,
-#  # set to `true` if you're using pantalaimon.
-#  #
-#  # Be sure to point homeserverUrl to the pantalaimon instance.
-#  #
-#  # Draupnir will log in using the given username and password once,
-#  # then store the resulting access token in a file under dataPath.
-#  use: false
-#
-#  # The username to login with.
-#  username: draupnir
-#
-#  # The password Draupnir will login with.
-#  #
-#  # After successfully logging in once, this will be ignored, so this value can be blanked after first startup.
-#  password: your_password
+pantalaimon:
+  # Whether or not Draupnir will use pantalaimon to access the matrix homeserver,
+  # set to `true` if you're using pantalaimon.
+  #
+  # Be sure to point homeserverUrl to the pantalaimon instance.
+  #
+  # Draupnir will log in using the given username and password once,
+  # then store the resulting access token in a file under dataPath.
+  use: true
+
+  # The username to login with.
+  username: {{ matrix_bot_draupnir_pantalaimon_username | to_json }}
+
+  # The password Draupnir will login with.
+  #
+  # After successfully logging in once, this will be ignored, so this value can be blanked after first startup.
+  password: {{ matrix_bot_draupnir_pantalaimon_password | to_json }}
+{% endif %}
 
 # The path Draupnir will store its state/data in, leave default ("/data/storage") when using containers.
 dataPath: "/data"
@@ -49,7 +51,7 @@ recordIgnoredInvites: false
 #
 # Note: By default, Draupnir is fairly verbose - expect a lot of messages in this room.
 # (see verboseLogging to adjust this a bit.)
-managementRoom: "{{ matrix_bot_draupnir_management_room }}"
+managementRoom: {{ matrix_bot_draupnir_management_room | to_json }}
 
 # Deprecated and will be removed in a future version.
 # Running with verboseLogging is unsupported.
@@ -77,7 +79,7 @@ noop: false
 
 # Whether or not Draupnir should apply `m.room.server_acl` events.
 # DO NOT change this to `true` unless you are very confident that you know what you are doing.
-disableServerACL: "{{ matrix_bot_draupnir_disable_server_acl }}"
+disableServerACL: {{ matrix_bot_draupnir_disable_server_acl | to_json }}
 
 # Whether Draupnir should check member lists quicker (by using a different endpoint),
 # keep in mind that enabling this will miss invited (but not joined) users.
@@ -161,7 +163,7 @@ commands:
 
   # The default reasons to be prompted with if the reason is missing from a ban command.
   ban:
-    defaultReasons: 
+    defaultReasons:
       - "spam"
       - "brigading"
       - "harassment"

roles/custom/matrix-pantalaimon/defaults/main.yml

@@ -0,0 +1,57 @@
+---
+# E2EE aware proxy daemon for matrix clients.
+# Project source code URL: https://github.com/matrix-org/pantalaimon
+
+matrix_pantalaimon_enabled: true
+
+matrix_pantalaimon_version: "0.10.5"
+
+matrix_pantalaimon_container_image_self_build: false
+matrix_pantalaimon_container_image_self_build_repo: "https://github.com/matrix-org/pantalaimon.git"
+matrix_pantalaimon_container_image_self_build_repo_version: "{{ 'main' if matrix_pantalaimon_version == 'latest' else matrix_pantalaimon_version }}"
+
+matrix_pantalaimon_docker_image: "{{ matrix_pantalaimon_docker_image_name_prefix }}matrixdotorg/pantalaimon:v{{ matrix_pantalaimon_version }}"
+matrix_pantalaimon_docker_image_name_prefix: "{{ 'localhost/' if matrix_pantalaimon_container_image_self_build else matrix_container_global_registry_prefix }}"
+matrix_pantalaimon_docker_image_force_pull: "{{ matrix_pantalaimon_docker_image.endswith(':latest') }}"
+
+matrix_pantalaimon_base_path: "{{ matrix_base_data_path }}/pantalaimon"
+matrix_pantalaimon_data_path: "{{ matrix_pantalaimon_base_path }}/data"
+matrix_pantalaimon_container_src_files_path: "{{ matrix_pantalaimon_base_path }}/container-src"
+
+# The base container network
+matrix_pantalaimon_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_pantalaimon_container_additional_networks: "{{ matrix_pantalaimon_container_additional_networks_auto + matrix_pantalaimon_container_additional_networks_custom }}"
+matrix_pantalaimon_container_additional_networks_auto: []
+matrix_pantalaimon_container_additional_networks_custom: []
+
+# A list of extra arguments to pass to the container
+matrix_pantalaimon_container_extra_arguments: []
+
+# List of systemd services that matrix-pantalaimon.service depends on
+matrix_pantalaimon_systemd_required_services_list: "{{ matrix_pantalaimon_systemd_required_services_list_default + matrix_pantalaimon_systemd_required_services_list_auto + matrix_pantalaimon_systemd_required_services_list_custom }}"
+matrix_pantalaimon_systemd_required_services_list_default: ['docker.service']
+matrix_pantalaimon_systemd_required_services_list_auto: []
+matrix_pantalaimon_systemd_required_services_list_custom: []
+
+# List of systemd services that matrix-pantalaimon.service wants
+matrix_pantalaimon_systemd_wanted_services_list: "{{ matrix_pantalaimon_systemd_wanted_services_list_default + matrix_pantalaimon_systemd_wanted_services_list_auto + matrix_pantalaimon_systemd_wanted_services_list_custom }}"
+matrix_pantalaimon_systemd_wanted_services_list_default: []
+matrix_pantalaimon_systemd_wanted_services_list_auto: []
+matrix_pantalaimon_systemd_wanted_services_list_custom: []
+
+# Pantalaimon log level, case-insensitive (Error, Warning, Info, Debug)
+matrix_pantalaimon_log_level: Warning
+
+# Base URL where matrix-pantalaimon can reach your homeserver C-S API.
+# If the homeserver runs on the same machine, you may need to add its service to `matrix_pantalaimon_systemd_required_services_list`.
+matrix_pantalaimon_homeserver_url: ""
+
+# Default configuration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
+#
+# For a more advanced customization, you can
+# completely replace this variable with your own template.
+matrix_pantalaimon_configuration: "{{ lookup('template', 'templates/pantalaimon.conf.j2') }}"

roles/custom/matrix-pantalaimon/tasks/install.yml

@@ -0,0 +1,67 @@
+---
+
+- name: Ensure matrix-pantalaimon paths exist
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - {path: "{{ matrix_pantalaimon_base_path }}", when: true}
+    - {path: "{{ matrix_pantalaimon_data_path }}", when: true}
+    - {path: "{{ matrix_pantalaimon_container_src_files_path }}", when: "{{ matrix_pantalaimon_container_image_self_build }}"}
+  when: "item.when | bool"
+
+- name: Ensure matrix-pantalaimon config installed
+  ansible.builtin.copy:
+    content: "{{ matrix_pantalaimon_configuration }}"
+    dest: "{{ matrix_pantalaimon_data_path }}/pantalaimon.conf"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
+- name: Ensure pantalaimon container image is pulled
+  community.docker.docker_image:
+    name: "{{ matrix_pantalaimon_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_pantalaimon_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_pantalaimon_docker_image_force_pull }}"
+  when: "not matrix_pantalaimon_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 pantalaimon repository is present on self-build
+  ansible.builtin.git:
+    repo: "{{ matrix_pantalaimon_container_image_self_build_repo }}"
+    version: "{{ matrix_pantalaimon_container_image_self_build_repo_version }}"
+    dest: "{{ matrix_pantalaimon_container_src_files_path }}"
+    force: "yes"
+  become: true
+  become_user: "{{ matrix_user_username }}"
+  register: matrix_pantalaimon_git_pull_results
+  when: "matrix_pantalaimon_container_image_self_build | bool"
+
+- name: Ensure pantalaimon container image is built
+  community.docker.docker_image:
+    name: "{{ matrix_pantalaimon_docker_image }}"
+    source: build
+    force_source: "{{ matrix_pantalaimon_git_pull_results.changed }}"
+    build:
+      dockerfile: Dockerfile
+      path: "{{ matrix_pantalaimon_container_src_files_path }}"
+      pull: true
+  when: "matrix_pantalaimon_container_image_self_build | bool"
+
+- name: Ensure pantalaimon container network is created
+  community.general.docker_network:
+    name: "{{ matrix_pantalaimon_container_network }}"
+    driver: bridge
+
+- name: Ensure matrix-pantalaimon.service installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/systemd/matrix-pantalaimon.service.j2"
+    dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-pantalaimon.service"
+    mode: 0644

roles/custom/matrix-pantalaimon/tasks/main.yml

@@ -0,0 +1,20 @@
+---
+
+- tags:
+    - setup-all
+    - setup-pantalaimon
+    - install-all
+    - install-pantalaimon
+  block:
+    - when: matrix_pantalaimon_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
+
+    - when: matrix_pantalaimon_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/install.yml"
+
+- tags:
+    - setup-all
+    - setup-pantalaimon
+  block:
+    - when: not matrix_pantalaimon_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/uninstall.yml"

roles/custom/matrix-pantalaimon/tasks/uninstall.yml

@@ -0,0 +1,25 @@
+---
+
+- name: Check existence of matrix-pantalaimon service
+  ansible.builtin.stat:
+    path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-pantalaimon.service"
+  register: matrix_pantalaimon_service_stat
+
+- when: matrix_pantalaimon_service_stat.stat.exists | bool
+  block:
+    - name: Ensure matrix-pantalaimon is stopped
+      ansible.builtin.service:
+        name: matrix-pantalaimon
+        state: stopped
+        enabled: false
+        daemon_reload: true
+
+    - name: Ensure matrix-pantalaimon.service doesn't exist
+      ansible.builtin.file:
+        path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-pantalaimon.service"
+        state: absent
+
+    - name: Ensure matrix-pantalaimon paths don't exist
+      ansible.builtin.file:
+        path: "{{ matrix_pantalaimon_base_path }}"
+        state: absent

roles/custom/matrix-pantalaimon/tasks/validate_config.yml

@@ -0,0 +1,8 @@
+---
+
+- name: Fail if required variables are undefined
+  ansible.builtin.fail:
+    msg: "The `{{ item }}` variable must be defined and have a non-null value."
+  with_items:
+    - "matrix_pantalaimon_homeserver_url"
+  when: "vars[item] == '' or vars[item] is none"

roles/custom/matrix-pantalaimon/templates/pantalaimon.conf.j2

@@ -0,0 +1,10 @@
+[Default]
+LogLevel = {{ matrix_pantalaimon_log_level }}
+
+[homeserver]
+Homeserver = {{ matrix_pantalaimon_homeserver_url }}
+ListenAddress = 0.0.0.0
+ListenPort = 8009
+SSL = False
+UseKeyring = False
+IgnoreVerification = True

roles/custom/matrix-pantalaimon/templates/systemd/matrix-pantalaimon.service.j2

@@ -0,0 +1,46 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=Matrix Pantalaimon
+{% for service in matrix_pantalaimon_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_pantalaimon_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 }} kill matrix-pantalaimon 2>/dev/null || true'
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-pantalaimon 2>/dev/null || true'
+
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
+			--rm \
+			--name=matrix-pantalaimon \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--read-only \
+			--network={{ matrix_pantalaimon_container_network }} \
+			--mount type=bind,src={{ matrix_pantalaimon_data_path }},dst=/data \
+			{% for arg in matrix_pantalaimon_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_pantalaimon_docker_image }}
+
+{% for network in matrix_pantalaimon_container_additional_networks %}
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-pantalaimon
+{% endfor %}
+
+ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-pantalaimon
+
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} kill matrix-pantalaimon 2>/dev/null || true'
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-pantalaimon 2>/dev/null || true'
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-pantalaimon
+
+[Install]
+WantedBy=multi-user.target

setup.yml

@@ -123,6 +123,7 @@
     - custom/matrix-static-files
     - custom/matrix-coturn
     - custom/matrix-media-repo
+    - custom/matrix-pantalaimon
 
     - role: galaxy/auxiliary