mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2025-11-13 13:38:55 +01:00
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 Reuseaa0591f8b0/tasks/main.ymlSigned-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 Reuseb108c8a151/docs/configuring-playbook-bridge-heisenbridge.mdSigned-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 Reuse7862fd7cdd/docs/configuring-playbook-bridge-postmoogle.mdSigned-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>
This commit is contained in:
Suguru Hirahara
GitHub
83
docs/configuring-playbook-bridge-zulip.md
Normal file
83
docs/configuring-playbook-bridge-zulip.md
Normal file
@@ -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`.
|
||||
@@ -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.
|
||||
|
||||
@@ -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/) |
|
||||
|
||||
Reference in New Issue
Block a user