From ee976242e54671185098113ba2aa61611fd94865 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 8 Nov 2025 07:09:12 +0000 Subject: [PATCH] Add MatrixZulipBridge (#4695) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add links to MatrixZulipBridge Signed-off-by: Suguru Hirahara * Add MatrixZulipBridge: copy matrix-bridge-heisenbridge Signed-off-by: Suguru Hirahara * Rename matrix-heisenbridge.service.j2 to matrix-matrixzulipbridge.service.j2 - Add the license header to matrix-matrixzulipbridge.service.j2 Signed-off-by: Suguru Hirahara * Replace "Heisenbridge" to "MatrixZulipBridge" to "heisenbridge" to "matrixzulipbridge", respectively Signed-off-by: Suguru Hirahara * Replace variables related to container image and version Signed-off-by: Suguru Hirahara * Update comments and copyright headers Signed-off-by: Suguru Hirahara * Update matrix-bridge-matrixzulipbridge/tasks/main.yml: add names to tasks Reuse https://app.radicle.xyz/nodes/seed.radicle.garden/rad%3Az3EdzLb58oJYY4L17xrVpYtRPz4ej/tree/aa0591f8b0ff19cee5523ffe5d070ee062e09d62/tasks/main.yml Signed-off-by: Suguru Hirahara * Remove configuration for identd Signed-off-by: Suguru Hirahara * Add `matrix_matrixzulipbridge_container_http_port` Signed-off-by: Suguru Hirahara * Run ansible-lint for files in tasks/ Signed-off-by: Suguru Hirahara * Update `matrix_matrixzulipbridge_registration_yaml` Run `pip install matrixzulipbridge && python3 -m matrixzulipbridge --config config.yaml --generate` to generate config.yaml Signed-off-by: Suguru Hirahara * Add MatrixZulipBridge to files in group_vars Signed-off-by: Suguru Hirahara * Add configuring-playbook-bridge-matrixzulipbridge.md Reuse https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/b108c8a15165cebe346c7b16cbe181a495db6bf7/docs/configuring-playbook-bridge-heisenbridge.md Signed-off-by: Suguru Hirahara * Fix `matrix_matrixzulipbridge_config_media_path` Signed-off-by: Suguru Hirahara * Remove space characters Signed-off-by: Suguru Hirahara * Replace "matrixzulipbridge" with "zulip", etc. Signed-off-by: Suguru Hirahara * Remove irrelevant instruction Signed-off-by: Suguru Hirahara * MatrixZulipBridge → Zulip bridge Signed-off-by: Suguru Hirahara * Rename `@matrixzulipbridge` to `@zulipbot` Signed-off-by: Suguru Hirahara * Replace `matrix_bridge_zulip` with `matrix_zulip_bridge` for now Refer to https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/4695#discussion_r2485317210 Signed-off-by: Suguru Hirahara * Set `{{ matrix_admin if matrix_admin else '' }}` to `matrix_zulip_bridge_owner` Signed-off-by: Suguru Hirahara * Apply the review Signed-off-by: Suguru Hirahara * Reuse the section about adjusting the playbook configuration on configuring-playbook-bridge-postmoogle.md Reuse https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/7862fd7cddf82cc067962a6b55747c3242c05630/docs/configuring-playbook-bridge-postmoogle.md Signed-off-by: Suguru Hirahara * Update configuring-playbook.md: sort list items Signed-off-by: Suguru Hirahara --------- Signed-off-by: Suguru Hirahara Signed-off-by: Suguru Hirahara Co-authored-by: Suguru Hirahara Co-authored-by: Suguru Hirahara --- .codespellrc | 2 +- README.md | 1 + docs/configuring-playbook-bridge-zulip.md | 83 ++++++++++++ docs/configuring-playbook.md | 2 + docs/container-images.md | 1 + group_vars/matrix_servers | 60 +++++++++ .../matrix-bridge-zulip/defaults/main.yml | 122 ++++++++++++++++++ .../custom/matrix-bridge-zulip/tasks/main.yml | 29 +++++ .../tasks/setup_install.yml | 62 +++++++++ .../tasks/setup_uninstall.yml | 26 ++++ .../tasks/validate_config.yml | 14 ++ .../matrix-bridge-zulip/templates/labels.j2 | 58 +++++++++ .../systemd/matrix-zulip-bridge.service.j2 | 60 +++++++++ setup.yml | 1 + 14 files changed, 520 insertions(+), 1 deletion(-) create mode 100644 docs/configuring-playbook-bridge-zulip.md create mode 100644 roles/custom/matrix-bridge-zulip/defaults/main.yml create mode 100644 roles/custom/matrix-bridge-zulip/tasks/main.yml create mode 100644 roles/custom/matrix-bridge-zulip/tasks/setup_install.yml create mode 100644 roles/custom/matrix-bridge-zulip/tasks/setup_uninstall.yml create mode 100644 roles/custom/matrix-bridge-zulip/tasks/validate_config.yml create mode 100644 roles/custom/matrix-bridge-zulip/templates/labels.j2 create mode 100644 roles/custom/matrix-bridge-zulip/templates/systemd/matrix-zulip-bridge.service.j2 diff --git a/.codespellrc b/.codespellrc index 83ec2578c..1c1da2564 100644 --- a/.codespellrc +++ b/.codespellrc @@ -1,2 +1,2 @@ [codespell] -ignore-words-list = aNULL,brose,doub,Udo,re-use,re-used,registr +ignore-words-list = aNULL,brose,doub,Udo,re-use,re-used,registr,shema diff --git a/README.md b/README.md index 68fc4d348..4fa5954a7 100644 --- a/README.md +++ b/README.md @@ -134,6 +134,7 @@ Bridges can be used to connect your Matrix installation with third-party communi | [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) | ❌ | Bridge to SMS | [Link](docs/configuring-playbook-bridge-matrix-bridge-sms.md) | | [matrix-steam-bridge](https://github.com/jasonlaguidice/matrix-steam-bridge) | ❌ | Bridge to [Steam](https://steampowered.com/) | [Link](docs/configuring-playbook-bridge-steam.md) | | [matrix-wechat](https://github.com/duo/matrix-wechat) | ❌ | Bridge to [WeChat](https://www.wechat.com/) | [Link](docs/configuring-playbook-bridge-wechat.md) | +| [MatrixZulipBridge](https://github.com/GearKite/MatrixZulipBridge) | ❌ | Puppeting appservice bridge for [Zulip](https://zulip.com/) | [Link](docs/configuring-playbook-bridge-zulip.md) | | [Heisenbridge](https://github.com/hifi/heisenbridge) | ❌ | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-heisenbridge.md) | | [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) | ❌ | Bridge to [GroupMe](https://groupme.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-groupme.md) | | [mx-puppet-steam](https://codeberg.org/icewind/mx-puppet-steam) | ❌ | Bridge to [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) | diff --git a/docs/configuring-playbook-bridge-zulip.md b/docs/configuring-playbook-bridge-zulip.md new file mode 100644 index 000000000..93e388045 --- /dev/null +++ b/docs/configuring-playbook-bridge-zulip.md @@ -0,0 +1,83 @@ + + +# Setting up a Zulip bridge (optional) + +The playbook can install and configure [MatrixZulipBridge](https://github.com/GearKite/MatrixZulipBridge) for you. + +See the project's [documentation](https://github.com/GearKite/MatrixZulipBridge/blob/main/README.md) to learn what it does and why it might be useful to you. + +## Adjusting DNS records (optional) + +By default, this playbook installs the Zulip bridge on the `matrix.` subdomain, at the `/zulip` path (https://matrix.example.com/zulip). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section. + +If you wish to adjust it, see the section [below](#adjusting-the-zulip-bridge-url-optional) for details about DNS configuration. + +## Adjusting the playbook configuration + +To enable the Zulip bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: + +```yaml +matrix_zulip_bridge_enabled: true + +# Uncomment to add one or more admins to this bridge: +# +# matrix_zulip_bridge_owner: +# - '@yourAdminAccount:{{ matrix_domain }}' +# +# … unless you've made yourself an admin of all bots/bridges like this: +# +# matrix_admin: '@yourAdminAccount:{{ matrix_domain }}' +``` + +### Adjusting the Zulip bridge URL (optional) + +By tweaking the `matrix_zulip_bridge_hostname` and `matrix_zulip_bridge_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one. + +Example additional configuration for your `vars.yml` file: + +```yaml +# Change the default hostname and path prefix +matrix_zulip_bridge_hostname: zulip.example.com +matrix_zulip_bridge_path_prefix: / +``` + +If you've changed the default hostname, you may need to create a CNAME record for the Zulip bridge domain (`zulip.example.com`), which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + +Take a look at: + +- `roles/custom/matrix-bridge-zulip/defaults/main.yml` for some variables that you can customize via your `vars.yml` file + +## Installing + +After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below: + + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` + +The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all` + +`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too. + +## Usage + +To use the bridge, you need to start a chat with `@zulipbridge:example.com` (where `example.com` is your base domain, not the `matrix.` domain). If the bridge ignores you and a DM is not accepted then the owner setting may be wrong. + +If you encounter issues or feel lost you can join the project room at [#matrixzulipbridge:shema.lv](https://matrix.to/#/#matrixzulipbridge:shema.lv) for help. + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bridge-zulip`. diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index bd453c12e..85127a0ac 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -188,6 +188,8 @@ Bridges can be used to connect your Matrix installation with third-party communi - [Setting up WeChat bridging](configuring-playbook-bridge-wechat.md) +- [Setting up Zulip bridging](configuring-playbook-bridge-zulip.md) + ### Bots Bots provide various additional functionality to your installation. diff --git a/docs/container-images.md b/docs/container-images.md index 69b880870..f7a548343 100644 --- a/docs/container-images.md +++ b/docs/container-images.md @@ -107,6 +107,7 @@ Bridges can be used to connect your Matrix installation with third-party communi | [matrix-hookshot](configuring-playbook-bridge-hookshot.md) | [halfshot/matrix-hookshot](https://hub.docker.com/r/halfshot/matrix-hookshot) | ❌ | Bridge for generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular | | [matrix-sms-bridge](configuring-playbook-bridge-matrix-bridge-sms.md) | [folivonet/matrix-sms-bridge](https://hub.docker.com/repository/docker/folivonet/matrix-sms-bridge) | ❌ | Bridge to SMS | | [matrix-wechat](configuring-playbook-bridge-wechat.md) | [lxduo/matrix-wechat](https://hub.docker.com/r/lxduo/matrix-wechat) | ❌ | Bridge to [WeChat](https://www.wechat.com/) | +| [MatrixZulipBridge](configuring-playbook-bridge-zulip.md) | [GearKite/MatrixZulipBridge](https://ghcr.io/gearkite/matrixzulipbridge) | ❌ | Puppeting appservice bridge for [Zulip](https://zulip.com/) | | [Heisenbridge](configuring-playbook-bridge-heisenbridge.md) | [hif1/heisenbridge](https://hub.docker.com/r/hif1/heisenbridge) | ❌ | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | | [mx-puppet-groupme](configuring-playbook-bridge-mx-puppet-groupme.md) | [xangelix/mx-puppet-groupme](https://hub.docker.com/r/xangelix/mx-puppet-groupme) | ❌ | Bridge to [GroupMe](https://groupme.com/) | | [matrix-steam-bridge](configuring-playbook-bridge-steam.md) | [jasonlaguidice/matrix-steam-bridge](https://github.com/jasonlaguidice/matrix-steam-bridge/pkgs/container/matrix-steam-bridge) | ❌ | Bridge to [Steam](https://steampowered.com/) | diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index aacd8c16f..d4f24739f 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -116,6 +116,8 @@ matrix_homeserver_container_extra_arguments_auto: | + (['--mount type=bind,src=' + matrix_hookshot_base_path + '/registration.yml,dst=/hookshot-registration.yml,ro'] if matrix_hookshot_enabled else []) + + (['--mount type=bind,src=' + matrix_zulip_bridge_base_path + '/registration.yaml,dst=/matrixzulipbridge-registration.yaml,ro'] if matrix_zulip_bridge_enabled else []) + + (['--mount type=bind,src=' + matrix_mautrix_bluesky_config_path + '/registration.yaml,dst=/matrix-mautrix-bluesky-registration.yaml,ro'] if matrix_mautrix_bluesky_enabled else []) + (['--mount type=bind,src=' + matrix_mautrix_discord_config_path + '/registration.yaml,dst=/matrix-mautrix-discord-registration.yaml,ro'] if matrix_mautrix_discord_enabled else []) @@ -181,6 +183,8 @@ matrix_homeserver_app_service_config_files_auto: | + (['/hookshot-registration.yml'] if matrix_hookshot_enabled else []) + + (['/matrixzulipbridge-registration.yaml'] if matrix_zulip_bridge_enabled else []) + + (['/matrix-mautrix-bluesky-registration.yaml'] if matrix_mautrix_bluesky_enabled else []) + (['/matrix-mautrix-discord-registration.yaml'] if matrix_mautrix_discord_enabled else []) @@ -315,6 +319,8 @@ devture_systemd_service_manager_services_list_auto: | + ([{'name': 'matrix-hookshot.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'hookshot', 'bridge-hookshot']}] if matrix_hookshot_enabled else []) + + ([{'name': 'matrix-zulip-bridge.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'zulip']}] if matrix_zulip_bridge_enabled else []) + + ([{'name': 'matrix-mautrix-bluesky.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'mautrix-bluesky']}] if matrix_mautrix_bluesky_enabled else []) + ([{'name': 'matrix-mautrix-discord.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'mautrix-discord']}] if matrix_mautrix_discord_enabled else []) @@ -2288,6 +2294,55 @@ matrix_hookshot_public_hostname: "{{ matrix_server_fqn_matrix }}" # ###################################################################### +###################################################################### +# +# matrix-bridge-zulip +# +###################################################################### + +# We don't enable bridges by default. +matrix_zulip_bridge_enabled: false + +matrix_zulip_bridge_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}" + +# Set this to your Matrix ID if you want to enforce the owner, otherwise first _local_ user becomes one +matrix_zulip_bridge_owner: "{{ matrix_admin if matrix_admin else '' }}" + +matrix_zulip_bridge_systemd_required_services_list_auto: | + {{ + matrix_addons_homeserver_systemd_services_list + }} + +matrix_zulip_bridge_docker_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else matrix_zulip_bridge_docker_image_registry_prefix_upstream_default }}" + +matrix_zulip_bridge_container_network: "{{ matrix_addons_container_network }}" + +matrix_zulip_bridge_container_additional_networks_auto: |- + {{ + ( + ([] if matrix_addons_homeserver_container_network == '' else [matrix_addons_homeserver_container_network]) + + + [matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_zulip_bridge_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else [] + ) | unique + }} + +matrix_zulip_bridge_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}" +matrix_zulip_bridge_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}" +matrix_zulip_bridge_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}" +matrix_zulip_bridge_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}" + +matrix_zulip_bridge_appservice_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'zulip.as.tok', rounds=655555) | to_uuid }}" + +matrix_zulip_bridge_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'zulip.hs.tok', rounds=655555) | to_uuid }}" + +matrix_zulip_bridge_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}" + +###################################################################### +# +# /matrix-bridge-zulip +# +###################################################################### + ###################################################################### # # matrix-bridge-mx-puppet-steam @@ -4921,6 +4976,11 @@ matrix_synapse_admin_config_asManagedUsers_auto: | '^@hbirc_[a-zA-Z0-9]+:'+(matrix_domain | regex_escape)+'$', ] if matrix_heisenbridge_enabled else []) + + ([ + '^@zulipbot:'+(matrix_domain | regex_escape)+'$', + '^@zulip_[a-zA-Z0-9]+:'+(matrix_domain | regex_escape)+'$', + ] if matrix_zulip_bridge_enabled else []) + + ([ '^@hookshot:'+(matrix_domain | regex_escape)+'$', '^@_github_[a-zA-Z0-9]+:'+(matrix_domain | regex_escape)+'$', diff --git a/roles/custom/matrix-bridge-zulip/defaults/main.yml b/roles/custom/matrix-bridge-zulip/defaults/main.yml new file mode 100644 index 000000000..c6fc8fb9c --- /dev/null +++ b/roles/custom/matrix-bridge-zulip/defaults/main.yml @@ -0,0 +1,122 @@ +# SPDX-FileCopyrightText: 2021 - 2022 Toni Spets +# SPDX-FileCopyrightText: 2022 - 2023 Nikita Chernyi +# SPDX-FileCopyrightText: 2022 - 2025 Slavi Pantaleev +# SPDX-FileCopyrightText: 2022 MDAD project contributors +# SPDX-FileCopyrightText: 2022 Marko Weltzer +# SPDX-FileCopyrightText: 2023 Samuel Meenzen +# SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara +# +# SPDX-License-Identifier: AGPL-3.0-or-later + +--- +# MatrixZulipBridge is a puppeting appservice bridge for Zulip +# Project source code URL: https://github.com/GearKite/MatrixZulipBridge + +matrix_zulip_bridge_enabled: true + +matrix_zulip_bridge_scheme: https +matrix_zulip_bridge_hostname: "{{ matrix_server_fqn_matrix }}" +matrix_zulip_bridge_path_prefix: "/zulip" + +# renovate: datasource=docker depName=ghcr.io/gearkite/matrixzulipbridge +matrix_zulip_bridge_version: v0.4.1 +matrix_zulip_bridge_docker_image: "{{ matrix_zulip_bridge_docker_image_registry_prefix }}gearkite/matrixzulipbridge:{{ matrix_zulip_bridge_version }}" +matrix_zulip_bridge_docker_image_registry_prefix: "{{ matrix_zulip_bridge_docker_image_registry_prefix_upstream }}" +matrix_zulip_bridge_docker_image_registry_prefix_upstream: "{{ matrix_zulip_bridge_docker_image_registry_prefix_upstream_default }}" +matrix_zulip_bridge_docker_image_registry_prefix_upstream_default: ghcr.io/ +matrix_zulip_bridge_docker_image_force_pull: "{{ matrix_zulip_bridge_docker_image.endswith(':latest') }}" + +matrix_zulip_bridge_base_path: "{{ matrix_base_data_path }}/zulip" + +matrix_zulip_bridge_container_network: "" + +# The port number in the container +matrix_zulip_bridge_container_http_port: 9898 + +matrix_zulip_bridge_container_additional_networks: "{{ matrix_zulip_bridge_container_additional_networks_auto + matrix_zulip_bridge_container_additional_networks_custom }}" +matrix_zulip_bridge_container_additional_networks_auto: [] +matrix_zulip_bridge_container_additional_networks_custom: [] + +# Controls how long to wait for the container to stop gracefully before killing it. +# We use a small value here, because this container does not seem to handle the SIGTERM signal. +matrix_zulip_bridge_container_stop_grace_time_seconds: 1 + +# matrix_zulip_bridge_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_zulip_bridge_container_labels_additional_labels`. +matrix_zulip_bridge_container_labels_traefik_enabled: true +matrix_zulip_bridge_container_labels_traefik_docker_network: "{{ matrix_zulip_bridge_container_network }}" +matrix_zulip_bridge_container_labels_traefik_hostname: "{{ matrix_zulip_bridge_hostname }}" +matrix_zulip_bridge_container_labels_traefik_path_prefix: "{{ matrix_zulip_bridge_path_prefix }}" +matrix_zulip_bridge_container_labels_traefik_entrypoints: web-secure +matrix_zulip_bridge_container_labels_traefik_tls_certResolver: default # noqa var-naming + +# Controls if the media router is enabled +matrix_zulip_bridge_container_labels_traefik_media_enabled: true +matrix_zulip_bridge_container_labels_traefik_media_hostname: "{{ matrix_zulip_bridge_container_labels_traefik_hostname }}" +# The path prefix must either be `/` or not end with a slash (e.g. `/zulip`). +matrix_zulip_bridge_container_labels_traefik_media_path_prefix: "{{ '' if matrix_zulip_bridge_container_labels_traefik_path_prefix == '/' else (matrix_zulip_bridge_container_labels_traefik_path_prefix) }}/_bridge_zulip/media" +matrix_zulip_bridge_container_labels_traefik_media_rule: "Host(`{{ matrix_zulip_bridge_container_labels_traefik_media_hostname }}`){% if matrix_zulip_bridge_container_labels_traefik_media_path_prefix != '/' %} && PathPrefix(`{{ matrix_zulip_bridge_container_labels_traefik_media_path_prefix }}`){% endif %}" +matrix_zulip_bridge_container_labels_traefik_media_priority: 0 +matrix_zulip_bridge_container_labels_traefik_media_entrypoints: "{{ matrix_zulip_bridge_container_labels_traefik_entrypoints }}" +matrix_zulip_bridge_container_labels_traefik_media_tls: "{{ matrix_zulip_bridge_container_labels_traefik_media_entrypoints != 'web' }}" +matrix_zulip_bridge_container_labels_traefik_media_tls_certResolver: "{{ matrix_zulip_bridge_container_labels_traefik_tls_certResolver }}" # noqa var-naming + +# matrix_zulip_bridge_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_zulip_bridge_container_labels_additional_labels: | +# my.label=1 +# another.label="here" +matrix_zulip_bridge_container_labels_additional_labels: '' + +# A list of extra arguments to pass to the container +matrix_zulip_bridge_container_extra_arguments: [] + +# List of systemd services that service depends on. +matrix_zulip_bridge_systemd_required_services_list: "{{ matrix_zulip_bridge_systemd_required_services_list_default + matrix_zulip_bridge_systemd_required_services_list_auto + matrix_zulip_bridge_systemd_required_services_list_custom }}" +matrix_zulip_bridge_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}" +matrix_zulip_bridge_systemd_required_services_list_auto: [] +matrix_zulip_bridge_systemd_required_services_list_custom: [] + +# List of systemd services that service wants +matrix_zulip_bridge_systemd_wanted_services_list: [] + +matrix_zulip_bridge_homeserver_url: "" + +matrix_zulip_bridge_appservice_token: '' +matrix_zulip_bridge_homeserver_token: '' + +matrix_zulip_bridge_config_media_url: "{{ matrix_zulip_bridge_scheme }}://{{ matrix_zulip_bridge_hostname }}" +# This matches the hardcoded `DEFAULT_MEDIA_PATH` in MatrixZulipBridge, but uses `matrix_zulip_bridge_path_prefix` as the path prefix. +# See: https://github.com/GearKite/MatrixZulipBridge/blob/2ba51f3da2ad8bd33460c953ef91a9cfc585a2d4/matrixzulipbridge/__main__.py#L87 +matrix_zulip_bridge_config_media_path: "{{ matrix_zulip_bridge_container_labels_traefik_media_path_prefix }}/v3/download/{netloc}{path}{filename}" +matrix_zulip_bridge_config_media_key: "{{ matrix_zulip_bridge_homeserver_token }}" +matrix_zulip_bridge_config_displayname: "MatrixZulipBridge" + +matrix_zulip_bridge_registration_yaml_bridge_zulip: + media_url: "{{ matrix_zulip_bridge_config_media_url }}" + media_path: "{{ matrix_zulip_bridge_config_media_path }}" + media_key: "{{ matrix_zulip_bridge_config_media_key }}" + displayname: "{{ matrix_zulip_bridge_config_displayname }}" + +# Default registration file consumed by both the homeserver and MatrixZulipBridge. +# Besides registration information, it contains configuration (see the Zulip bridge key). +matrix_zulip_bridge_registration_yaml: + id: zulipbridge + url: http://matrix-zulip-bridge:{{ matrix_zulip_bridge_container_http_port }} + as_token: "{{ matrix_zulip_bridge_appservice_token }}" + hs_token: "{{ matrix_zulip_bridge_homeserver_token }}" + rate_limited: false + sender_localpart: zulipbridge + namespaces: + users: + - regex: '@zulip_.*' + exclusive: true + aliases: [] + rooms: [] + matrixzulipbridge: "{{ matrix_zulip_bridge_registration_yaml_bridge_zulip }}" + +matrix_zulip_bridge_registration: "{{ matrix_zulip_bridge_registration_yaml | from_yaml }}" diff --git a/roles/custom/matrix-bridge-zulip/tasks/main.yml b/roles/custom/matrix-bridge-zulip/tasks/main.yml new file mode 100644 index 000000000..392023b63 --- /dev/null +++ b/roles/custom/matrix-bridge-zulip/tasks/main.yml @@ -0,0 +1,29 @@ +# SPDX-FileCopyrightText: 2021 Toni Spets +# SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev +# SPDX-FileCopyrightText: 2022 Marko Weltzer +# SPDX-FileCopyrightText: 2025 Suguru Hirahara +# +# SPDX-License-Identifier: AGPL-3.0-or-later + +--- +- name: Perform the Zulip bridge installation tasks + when: matrix_zulip_bridge_enabled | bool + tags: + - setup-all + - setup-bridge-zulip + - install-all + - install-bridge-zulip + block: + - name: Validate the Zulip bridge configuration + ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml" + - name: Install the Zulip bridge + ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml" + +- name: Perform the Zulip bridge uninstallation tasks + when: not matrix_zulip_bridge_enabled | bool + tags: + - setup-all + - setup-bridge-zulip + block: + - name: Uninstall the Zulip bridge + ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml" diff --git a/roles/custom/matrix-bridge-zulip/tasks/setup_install.yml b/roles/custom/matrix-bridge-zulip/tasks/setup_install.yml new file mode 100644 index 000000000..f05ba91fc --- /dev/null +++ b/roles/custom/matrix-bridge-zulip/tasks/setup_install.yml @@ -0,0 +1,62 @@ +# SPDX-FileCopyrightText: 2021 Toni Spets +# SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev +# SPDX-FileCopyrightText: 2022 Jim Myhrberg +# SPDX-FileCopyrightText: 2022 Marko Weltzer +# SPDX-FileCopyrightText: 2022 Nikita Chernyi +# SPDX-FileCopyrightText: 2022 Sebastian Gumprich +# SPDX-FileCopyrightText: 2024 David Mehren +# +# SPDX-License-Identifier: AGPL-3.0-or-later + +--- +- name: Ensure the Zulip bridge image is pulled + community.docker.docker_image: + name: "{{ matrix_zulip_bridge_docker_image }}" + source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}" + force_source: "{{ matrix_zulip_bridge_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_zulip_bridge_docker_image_force_pull }}" + register: result + retries: "{{ devture_playbook_help_container_retries_count }}" + delay: "{{ devture_playbook_help_container_retries_delay }}" + until: result is not failed + +- name: Ensure the Zulip bridge paths exist + ansible.builtin.file: + path: "{{ item }}" + state: directory + mode: "0750" + owner: "{{ matrix_user_name }}" + group: "{{ matrix_group_name }}" + with_items: + - "{{ matrix_zulip_bridge_base_path }}" + +- name: Ensure the Zulip bridge registration.yaml installed if provided + ansible.builtin.copy: + content: "{{ matrix_zulip_bridge_registration | to_nice_yaml(indent=2, width=999999) }}" + dest: "{{ matrix_zulip_bridge_base_path }}/registration.yaml" + mode: "0644" + owner: "{{ matrix_user_name }}" + group: "{{ matrix_group_name }}" + +- name: Ensure the Zulip bridge support files installed + ansible.builtin.template: + src: "{{ role_path }}/templates/{{ item }}.j2" + dest: "{{ matrix_zulip_bridge_base_path }}/{{ item }}" + mode: "0640" + owner: "{{ matrix_user_name }}" + group: "{{ matrix_group_name }}" + with_items: + - labels + +- name: Ensure the Zulip bridge container network is created + community.general.docker_network: + enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}" + name: "{{ matrix_zulip_bridge_container_network }}" + driver: bridge + driver_options: "{{ devture_systemd_docker_base_container_networks_driver_options }}" + +- name: Ensure matrix-zulip-bridge.service installed + ansible.builtin.template: + src: "{{ role_path }}/templates/systemd/matrix-zulip-bridge.service.j2" + dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-zulip-bridge.service" + mode: "0644" diff --git a/roles/custom/matrix-bridge-zulip/tasks/setup_uninstall.yml b/roles/custom/matrix-bridge-zulip/tasks/setup_uninstall.yml new file mode 100644 index 000000000..5ae51b283 --- /dev/null +++ b/roles/custom/matrix-bridge-zulip/tasks/setup_uninstall.yml @@ -0,0 +1,26 @@ +# SPDX-FileCopyrightText: 2021 - 2022 Slavi Pantaleev +# SPDX-FileCopyrightText: 2021 Michael Sasser +# SPDX-FileCopyrightText: 2021 Toni Spets +# SPDX-FileCopyrightText: 2022 Marko Weltzer +# +# SPDX-License-Identifier: AGPL-3.0-or-later + +--- +- name: Check existence of matrix-bridge-zulip service + ansible.builtin.stat: + path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-zulip-bridge.service" + register: matrix_zulip_bridge_service_stat + +- when: matrix_zulip_bridge_service_stat.stat.exists | bool + block: + - name: Ensure matrix-bridge-zulip is stopped + ansible.builtin.service: + name: matrix-bridge-zulip + state: stopped + enabled: false + daemon_reload: true + + - name: Ensure matrix-zulip-bridge.service doesn't exist + ansible.builtin.file: + path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-zulip-bridge.service" + state: absent diff --git a/roles/custom/matrix-bridge-zulip/tasks/validate_config.yml b/roles/custom/matrix-bridge-zulip/tasks/validate_config.yml new file mode 100644 index 000000000..f7be63e07 --- /dev/null +++ b/roles/custom/matrix-bridge-zulip/tasks/validate_config.yml @@ -0,0 +1,14 @@ +# SPDX-FileCopyrightText: 2024 Slavi Pantaleev +# SPDX-FileCopyrightText: 2024 Suguru Hirahara +# +# SPDX-License-Identifier: AGPL-3.0-or-later + +--- +- name: Fail if required the Zulip bridge 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_zulip_bridge_container_network", when: true} + - {"name": "matrix_zulip_bridge_homeserver_url", when: true} diff --git a/roles/custom/matrix-bridge-zulip/templates/labels.j2 b/roles/custom/matrix-bridge-zulip/templates/labels.j2 new file mode 100644 index 000000000..a41889f71 --- /dev/null +++ b/roles/custom/matrix-bridge-zulip/templates/labels.j2 @@ -0,0 +1,58 @@ +{# +SPDX-FileCopyrightText: 2024 Slavi Pantaleev + +SPDX-License-Identifier: AGPL-3.0-or-later +#} + +{% if matrix_zulip_bridge_container_labels_traefik_enabled %} +traefik.enable=true + +{% if matrix_zulip_bridge_container_labels_traefik_docker_network %} +traefik.docker.network={{ matrix_zulip_bridge_container_labels_traefik_docker_network }} +{% endif %} + +traefik.http.services.matrix-zulip-bridge.loadbalancer.server.port={{ matrix_zulip_bridge_container_http_port }} + +{% set middlewares = [] %} + +{% if matrix_zulip_bridge_container_labels_traefik_path_prefix != '/' %} +traefik.http.middlewares.matrix-bridge-zulip-strip-prefix.stripprefix.prefixes={{ matrix_zulip_bridge_container_labels_traefik_path_prefix }} +{% set middlewares = middlewares + ['matrix-bridge-zulip-strip-prefix'] %} +{% endif %} + +{% if matrix_zulip_bridge_container_labels_traefik_media_enabled %} +########################################################################## +# # +# Media # +# # +########################################################################## + +traefik.http.routers.matrix-bridge-zulip-media.rule={{ matrix_zulip_bridge_container_labels_traefik_media_rule }} + +{% if matrix_zulip_bridge_container_labels_traefik_media_priority | int > 0 %} +traefik.http.routers.matrix-bridge-zulip-media.priority={{ matrix_zulip_bridge_container_labels_traefik_media_priority }} +{% endif %} + +{% if middlewares | length > 0 %} +traefik.http.routers.matrix-bridge-zulip-media.middlewares={{ middlewares | join(',') }} +{% endif %} + +traefik.http.routers.matrix-bridge-zulip-media.service=matrix-bridge-zulip +traefik.http.routers.matrix-bridge-zulip-media.entrypoints={{ matrix_zulip_bridge_container_labels_traefik_entrypoints }} + +traefik.http.routers.matrix-bridge-zulip-media.tls={{ matrix_zulip_bridge_container_labels_traefik_media_tls | to_json }} +{% if matrix_zulip_bridge_container_labels_traefik_media_entrypoints %} +traefik.http.routers.matrix-bridge-zulip-media.tls.certResolver={{ matrix_zulip_bridge_container_labels_traefik_media_tls_certResolver }} +{% endif %} + +########################################################################## +# # +# /Media # +# # +########################################################################## +{% endif %} + + +{% endif %} + +{{ matrix_zulip_bridge_container_labels_additional_labels }} diff --git a/roles/custom/matrix-bridge-zulip/templates/systemd/matrix-zulip-bridge.service.j2 b/roles/custom/matrix-bridge-zulip/templates/systemd/matrix-zulip-bridge.service.j2 new file mode 100644 index 000000000..15f05f4b3 --- /dev/null +++ b/roles/custom/matrix-bridge-zulip/templates/systemd/matrix-zulip-bridge.service.j2 @@ -0,0 +1,60 @@ +{# +SPDX-FileCopyrightText: 2021 Toni Spets +SPDX-FileCopyrightText: 2022 - 2025 Slavi Pantaleev +SPDX-FileCopyrightText: 2025 Suguru Hirahara + +SPDX-License-Identifier: AGPL-3.0-or-later +#} + +[Unit] +Description=a puppeting appservice bridge for Zulip +{% for service in matrix_zulip_bridge_systemd_required_services_list %} +Requires={{ service }} +After={{ service }} +{% endfor %} +{% for service in matrix_zulip_bridge_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_docker }} stop -t {{ matrix_zulip_bridge_container_stop_grace_time_seconds }} matrix-bridge-zulip +ExecStartPre=-{{ devture_systemd_docker_base_host_command_docker }} rm matrix-bridge-zulip + +ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \ + --rm \ + --name=matrix-bridge-zulip \ + --log-driver=none \ + --user={{ matrix_user_uid }}:{{ matrix_user_gid }} \ + --cap-drop=ALL \ + --network={{ matrix_zulip_bridge_container_network }} \ + --mount type=bind,src={{ matrix_zulip_bridge_base_path }},dst=/config \ + --label-file={{ matrix_zulip_bridge_base_path }}/labels \ + {% for arg in matrix_zulip_bridge_container_extra_arguments %} + {{ arg }} \ + {% endfor %} + {{ matrix_zulip_bridge_docker_image }} \ + {% if matrix_zulip_bridge_owner %} + -o {{ matrix_zulip_bridge_owner }} \ + {% endif %} + --config /config/registration.yaml \ + --listen-address 0.0.0.0 \ + --listen-port {{ matrix_zulip_bridge_container_http_port }} \ + {{ matrix_zulip_bridge_homeserver_url }} + +{% for network in matrix_zulip_bridge_container_additional_networks %} +ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-bridge-zulip +{% endfor %} + +ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-bridge-zulip + +ExecStop=-{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ matrix_zulip_bridge_container_stop_grace_time_seconds }} matrix-bridge-zulip +ExecStop=-{{ devture_systemd_docker_base_host_command_docker }} rm matrix-bridge-zulip +Restart=always +RestartSec=30 +SyslogIdentifier=matrix-bridge-zulip + +[Install] +WantedBy=multi-user.target diff --git a/setup.yml b/setup.yml index b763384e6..e4547d212 100644 --- a/setup.yml +++ b/setup.yml @@ -82,6 +82,7 @@ - custom/matrix-bridge-steam - custom/matrix-bridge-heisenbridge - custom/matrix-bridge-hookshot + - custom/matrix-bridge-zulip - custom/matrix-bot-matrix-reminder-bot - custom/matrix-bot-matrix-registration-bot - custom/matrix-bot-maubot