Add MatrixZulipBridge (#4695)

* Add links to MatrixZulipBridge Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Add MatrixZulipBridge: copy matrix-bridge-heisenbridge Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Rename matrix-heisenbridge.service.j2 to matrix-matrixzulipbridge.service.j2 - Add the license header to matrix-matrixzulipbridge.service.j2 Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Replace "Heisenbridge" to "MatrixZulipBridge" to "heisenbridge" to "matrixzulipbridge", respectively Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Replace variables related to container image and version Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update comments and copyright headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update matrix-bridge-matrixzulipbridge/tasks/main.yml: add names to tasks Reuse aa0591f8b0/tasks/main.yml Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Remove configuration for identd Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Add `matrix_matrixzulipbridge_container_http_port` Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Run ansible-lint for files in tasks/ Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * Add MatrixZulipBridge to files in group_vars Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Add configuring-playbook-bridge-matrixzulipbridge.md Reuse b108c8a151/docs/configuring-playbook-bridge-heisenbridge.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Fix `matrix_matrixzulipbridge_config_media_path` Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Remove space characters Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> * Replace "matrixzulipbridge" with "zulip", etc. Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> * Remove irrelevant instruction Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> * MatrixZulipBridge → Zulip bridge Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> * Rename `@matrixzulipbridge` to `@zulipbot` Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> * 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 <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> * Set `{{ matrix_admin if matrix_admin else '' }}` to `matrix_zulip_bridge_owner` Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> * Apply the review Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> * Reuse the section about adjusting the playbook configuration on configuring-playbook-bridge-postmoogle.md Reuse 7862fd7cdd/docs/configuring-playbook-bridge-postmoogle.md Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> * Update configuring-playbook.md: sort list items Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> --------- Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5> Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org> Co-authored-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5>
2025-11-08 19:18:55 +01:00 · 2025-11-08 07:09:12 +00:00
parent 1861faf31d
commit ee976242e5
14 changed files with 520 additions and 1 deletions
--- 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
--- 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) |
--- a/docs/configuring-playbook-bridge-zulip.md
+++ b/docs/configuring-playbook-bridge-zulip.md
@@ -0,0 +1,83 @@
+<!--
+SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021 Toni Spets
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# 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:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```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`.
--- 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.
--- 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/) |
--- 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)+'$',
--- a/roles/custom/matrix-bridge-zulip/defaults/main.yml
+++ 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 }}"
--- a/roles/custom/matrix-bridge-zulip/tasks/main.yml
+++ 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"
--- a/roles/custom/matrix-bridge-zulip/tasks/setup_install.yml
+++ 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"
--- a/roles/custom/matrix-bridge-zulip/tasks/setup_uninstall.yml
+++ 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
--- a/roles/custom/matrix-bridge-zulip/tasks/validate_config.yml
+++ 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}
--- a/roles/custom/matrix-bridge-zulip/templates/labels.j2
+++ 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 }}
--- 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
@@ -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
--- 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