mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-06-25 18:57:50 +02:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: mirror:element-call-integration
Branches Tags
mirror:master mirror:renovate/zeratax-matrix-registration-0.x mirror:element-call-stack mirror:element-call-integration mirror:synapse-cache-tuning mirror:HarHarLinks/hookshot-encryption
..
compare: mirror:c198cf16fa6a61766bf4a0622f62b3bbe9731680
Branches Tags
mirror:master mirror:renovate/zeratax-matrix-registration-0.x mirror:element-call-stack mirror:element-call-integration mirror:synapse-cache-tuning mirror:HarHarLinks/hookshot-encryption

3 Commits
element-ca ... c198cf16fa

Author SHA1 Message Date
Slavi Pantaleev
c198cf16fa Add comment for the matrix_client_element_logout_redirect_url variable 2024-12-23 21:03:29 +02:00
Slavi Pantaleev
1fc4d175ac Simplify logout_redirect_url templating and make it safer 
Using `to_json` to make it safer.

Judging by the code here 0b24d33c64/src/Lifecycle.ts (L1026-L1032)
it doesn't seem like it leaving `logout_redirect_url` empty will hurt, so this patch removes the `if` block.
 2024-12-23 21:02:21 +02:00
Philippe Villanueva
b62302d547 Add logout_redirect_url var and option templating for matrix element client 2024-12-23 16:21:10 +01:00
1450 changed files with 23075 additions and 38346 deletions
Expand all files Collapse all files

4
.config/ansible-lint.yml
View File

@ -1,7 +1,3 @@
# SPDX-FileCopyrightText: 2022 - 2023 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
use_default_rules: true

5
.github/FUNDING.yml vendored
View File

@ -1,8 +1,3 @@
# SPDX-FileCopyrightText: 2020 - 2021 Slavi Pantaleev
# SPDX-FileCopyrightText: 2022 Marko Weltzer
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
# These are supported funding model platforms

4
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -11,7 +11,7 @@ assignees: ''
A clear and concise description of what the bug is.
<!--
NOTE: This Ansible playbook installs tens of separate services. If you're having a problem with a specific one, it is likely that the problem is with the service itself. You may wish to report that problem at the source, upstream.
NOTE: This Ansible playbook installs tens of separate services. If you're having a problem with a specific service, it is likely that the problem is not with our deployment method, but with the service itself. You may wish to report that problem at the source, upstream, and not to us
-->
**To Reproduce**
@ -34,7 +34,7 @@ A clear and concise description of what you expected to happen.
**Ansible:**
If your problem appears to be with Ansible, tell us:
- where you run Ansible — e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
- where you run Ansible -- e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
- what version of Ansible you're running (see `ansible --version`)
<!--

4
.github/ISSUE_TEMPLATE/bug_report.md.license vendored
View File

@ -1,4 +0,0 @@
SPDX-FileCopyrightText: 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later

4
.github/ISSUE_TEMPLATE/config.yml vendored
View File

@ -1,7 +1,3 @@
# SPDX-FileCopyrightText: 2024 Suguru Hirahara
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
blank_issues_enabled: false
contact_links:

4
.github/ISSUE_TEMPLATE/feature_request.md vendored
View File

@ -13,9 +13,7 @@ A clear and concise description of what the problem is. Ex. I'm always frustrate
<!--
NOTE: When submitting feature requests, be aware that:
- This Ansible playbook installs tens of separate services. If you're having a problem with a specific one, it is likely that the problem is with the service itself. You may wish to report that problem at the source, upstream.
- This playbook intends to focus solely on Matrix and Matrix-related services. If your request is not specific to them, you may as well to consider to submit it to the mash-playbook project: https://github.com/mother-of-all-self-hosting/mash-playbook
- This Ansible playbook installs tens of separate services. If you're having a problem with a specific service or you'd like some functionality added to it, it is likely that the problem is not with our deployment method, but with the service itself. You may wish to report that problem at the source, upstream, and not to us.
- This is a community project with no financial backing. The easiest way to get a feature into this project is to just develop it yourself.
-->

4
.github/ISSUE_TEMPLATE/feature_request.md.license vendored
View File

@ -1,4 +0,0 @@
SPDX-FileCopyrightText: 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later

2
.github/ISSUE_TEMPLATE/i-need-help.md vendored
View File

@ -28,7 +28,7 @@ Make sure to remove any secret values before posting your vars.yml file publicly
**Ansible:**
If your problem appears to be with Ansible, tell us:
- where you run Ansible — e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
- where you run Ansible -- e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
- what version of Ansible you're running (see `ansible --version`)
**Problem description**:

4
.github/ISSUE_TEMPLATE/i-need-help.md.license vendored
View File

@ -1,4 +0,0 @@
SPDX-FileCopyrightText: 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later

4
.github/dependabot.yaml vendored
View File

@ -1,7 +1,3 @@
# SPDX-FileCopyrightText: 2022 Marko Weltzer
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
version: 2
updates:

6
.github/workflows/close-stale-issues.yml vendored
View File

@ -1,7 +1,3 @@
# SPDX-FileCopyrightText: 2024 Suguru Hirahara
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
name: 'Close stale issues and PRs'
on: # yamllint disable-line rule:truthy
@ -25,7 +21,7 @@ jobs:
# Issues/PRs
######################################################################
exempt-assignees: 'spantaleev,aine-etke'
operations-per-run: 500
operations-per-run: 100
# Use this to do a dry run from a pull request
# debug-only: true
######################################################################

6
.github/workflows/matrix.yml vendored
View File

@ -1,9 +1,3 @@
# SPDX-FileCopyrightText: 2022 Marko Weltzer
# SPDX-FileCopyrightText: 2022 Nikita Chernyi
# SPDX-FileCopyrightText: 2022 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
name: Matrix CI

20
.github/workflows/reuse.yml vendored
View File

@ -1,20 +0,0 @@
# SPDX-FileCopyrightText: 2022 Free Software Foundation Europe e.V. <https://fsfe.org>
#
# SPDX-License-Identifier: CC0-1.0
---
name: REUSE Compliance Check
on: [push, pull_request] # yamllint disable-line rule:truthy
permissions:
contents: read
jobs:
reuse-compliance-check:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: REUSE Compliance Check
uses: fsfe/reuse-action@v5

450
CHANGELOG.md
View File

@ -1,209 +1,3 @@
# 2025-03-15
## Element Call support
The playbook now supports [Element Call](https://github.com/element-hq/element-call) as an optional feature. Thanks to [wjbeckett](https://github.com/wjbeckett) for getting us started via [PR#3562](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3562).
Element Call is a native Matrix video conferencing application developed by [Element](https://element.io/) that has the goal of replacing [Jitsi](./docs/configuring-playbook-jitsi.md) and the old WebRTC stack used in previous Element versions.
💡 For now, Element Call is only supported with the [Synapse](docs/configuring-playbook-synapse.md) homeserver (with [federation](docs/configuring-playbook-federation.md) enabled) and [Element Web](docs/configuring-playbook-client-element-web.md) and Element X mobile clients. See the [Prerequisites](docs/configuring-playbook-element-call.md#prerequisites) section of the [Element Call documentation](docs/configuring-playbook-element-call.md) for more details.
To get started, see the [Configuring Element Call](docs/configuring-playbook-element-call.md) documentation page.
# 2025-03-08
## 6️⃣ IPv6 support enablement recommended by default
Our [default example configuration](./examples/vars.yml) and [Configuring DNS](./docs/configuring-dns.md) guides now recommend enabling [IPv6](https://en.wikipedia.org/wiki/IPv6) support. We recommend that everyone enables IPv6 support for their Matrix server, even if they don't have IPv6 connectivity yet.
Our new [Configuring IPv6](./docs/configuring-ipv6.md) documentation page has more details about the playbook's IPv6 support.
**Existing playbook users** will **need to do some manual work** to enable IPv6 support. This consists of:
- enabling IPv6 support for the Docker container networks:
- add `devture_systemd_docker_base_ipv6_enabled: true` to their `vars.yml` configuration file
- stop all services (`just stop-all`)
- delete all container networks on the server: `docker network rm $(docker network ls -q)`
- re-run the playbook fully: `just install-all`
- [configuring IPv6 (`AAAA`) DNS records](./docs/configuring-ipv6.md#configuring-dns-records-for-ipv6)
# 2025-02-26
## 🪦 Bye-bye, Email2Matrix
The [Email2Matrix](./docs/configuring-playbook-email2matrix.md) service has been superseded by the [Postmoogle](./docs/configuring-playbook-bridge-postmoogle.md) bridge for a long time now and was completely removed from the playbook today.
If you still have the Email2Matrix component installed on your Matrix server, the playbook can no longer help you uninstall it and you will need to do it manually as described in the [Uninstalling Email2Matrix manually](./docs/configuring-playbook-email2matrix.md#uninstalling-email2matrix-manually) section of the documentation. The playbook will warn you if there are any `matrix_email2matrix_*` variables still remaining in your configuration.
# 2025-02-23
## The playbook defaults to exposing the Coturn STUN port (3478) over UDP once again
Recently, we made the playbook [default to exposing the Coturn STUN port (3478) only over TCP](#the-playbook-now-defaults-to-exposing-the-coturn-stun-port-3478-only-over-tcp) to reduce the severity of DDoS amplification/reflection attacks.
It seems like old Element clients on mobile devices only support talking to the STUN port over UDP, not TCP.
To accommodate such ancient clients, we're now **reversing this change** and **defaulting to exposing the Coturn STUN port (3478) over UDP once again**.
In light of this new information, you have 2 options:
1. **If you already adapted to the previous change and would like to adapt to this change one again**:
- make sure the `3478/udp` port is whitelisted in your external firewall (if you have one) once again.
2. **If you don't care about old Element clients and wish to reduce the severity of DDoS amplification/reflection attacks**:
- Consider closing the STUN/UDP port with the following configuration:
```yaml
matrix_coturn_container_stun_plain_host_bind_port_udp: ""
```
- Consider keeping `3478/udp` blocked in your external firewall (if you have one)
# 2025-02-21
## Docker daemon options are no longer adjusted when IPv6 is enabled
We landed [initial IPv6 support](#initial-work-on-ipv6-support) in the past via a `devture_systemd_docker_base_ipv6_enabled` variable that one had to toggle to `true`.
This variable did **2 different things at once**:
- ensured that container networks were created with IPv6 being enabled
- adjusted the Docker daemon's configuration to set `experimental: true` and `ip6tables: true` (a necessary prerequisite for creating IPv6-enabled networks)
Since Docker 27.0.1's [changes to how it handles IPv6](https://docs.docker.com/engine/release-notes/27/#ipv6), **adjusting the Docker daemon's configuration is no longer necessary**, because:
- `ip6tables` defaults to `true` for everyone
- `ip6tables` is out of the experimental phase, so `experimental` is no longer necessary
In light of this, we're introducing a new variable (`devture_systemd_docker_base_ipv6_daemon_options_changing_enabled`) for controlling if IPv6 should be force-enabled in the Docker daemon's configuration options.
Since most people should be on a modern enough Docker daemon version which doesn't require such changes, this variable defaults to `false`.
This change affects you like this:
- ✅ if you're **not explicitly enabling IPv6** (via `devture_systemd_docker_base_ipv6_enabled` in your configuration): you're unaffected
- ❓ if you're **explicitly enabling IPv6** (via `devture_systemd_docker_base_ipv6_enabled` in your configuration):
- ✅ .. and you're on a modern enough Docker version (which you most likely are): the playbook will no longer mess with your Docker daemon options. You're unaffected.
- 🔧 .. and you're on an old Docker version, you **are affected** and need to use the following configuration to restore the old behavior:
```yml
# Force-enable IPv6 by changing the Docker daemon's options.
# This is necessary for Docker < 27.0.1, but not for newer versions.
devture_systemd_docker_base_ipv6_daemon_options_changing_enabled: true
# Request that individual container networks are created with IPv6 enabled.
devture_systemd_docker_base_ipv6_enabled: true
```
## Support for bridging to Bluesky via mautrix-bluesky
Thanks to [Zepmann](https://github.com/Zepmann), the playbook now supports bridging to [Bluesky](https://bsky.app/) via [mautrix-bluesky](https://github.com/mautrix/bluesky).
To learn more, see our [Setting up mautrix-bluesky](./docs/configuring-playbook-bridge-mautrix-bluesky.md) documentation page.
# 2025-02-19
## The playbook now defaults to exposing the Coturn STUN port (3478) only over TCP
We've previously done some work to **decrease the severity** of DDoS amplification attacks done through the [Coturn](./docs/configuring-playbook-turn.md)'s STUN port (2.8x -> 1.6x) as reported in [coturn: Lower DDoS amplification/reflection factor from 2.8 to 1.6 #2592](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2592).
To **completely eliminate the problem** of DDoS amplification attacks done through the [Coturn](./docs/configuring-playbook-turn.md) STUN port even further (read more about this in [this article](https://stormwall.network/resources/blog/protect-against-ddos-based-on-stun-exploit)), the playbook now **disables exposure of the Coturn STUN port (`3478`) over UDP**. This is a bit heavy-handed, but is probably the only way to completely eliminate the problem.
The playbook now **only exposes the Coturn STUN port (`3478`) over TCP by default**.
💡 Users may wish to further remove the (now unnnecessary) firewall rule allowing access to `3478/udp`.
If you'd like the Coturn STUN port to be exposed over UDP like before, you can revert to the previous behavior by using the following configuration in your `vars.yml` file:
```yaml
matrix_coturn_container_stun_plain_host_bind_port_udp: "3478"
```
> [!WARNING]
> People running Coturn directly on the `host` network (using `matrix_coturn_container_network: host`) will still have the STUN port exposed over UDP, as port exposure is done directly via Coturn and not via Docker. In such cases, the playbook cannot prevent `3478/udp` port exposure and you'd need to do it in another way (separate firewall rule, etc).
# 2025-02-17
## FluffyChat Web suport
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook now supports [FluffyChat Web](https://github.com/krille-chan/fluffychat) as an additional Matrix client you can self-host.
To learn more, see our [Setting up FluffyChat Web](docs/configuring-playbook-client-fluffychat-web.md) documentation page.
# 2025-02-03
## The mautrix-hangouts bridge has been removed from the playbook
The [mautrix-hangouts](./docs/configuring-playbook-bridge-mautrix-hangouts.md) bridge has been deprecated in the playbook since December 2024 and finally got completely removed from the playbook in February 2025.
This is because Google Hangouts has been discontinued since the 1st of November 2022.
The playbook will let you know if you're using any `matrix_mautrix_hangouts_*` variables. You'll need to remove them from `vars.yml` and potentially [uninstall the bridge manually](./docs/configuring-playbook-bridge-mautrix-hangouts.md#uninstalling-the-bridge-manually).
# 2025-01-27
## Redis and KeyDB are no longer part of the playbook
**TLDR**: The playbook now exclusively uses Valkey as its Redis-compatible memorystore implementation, removing support for Redis and KeyDB. Most users are unaffected by this change unless they explicitly configured Redis or KeyDB variables. Only users that were explicitly definining `redis_*` or `keydb_*` variables will need to update their configuration to use `valkey_*` variables instead.
The playbook has gone through several iterations of memorystore implementations:
1. It initially used Redis, auto-installing it when needed by features/services
2. [Switched to KeyDB](#backward-compatibility-break-the-playbook-now-defaults-to-keydb-instead-of-redis) as the default, while keeping Redis support for those who wished to remain on Redis
3. [Switched to Valkey](#backward-compatibility-break-the-playbook-now-defaults-to-valkey-instead-of-keydb) due to [KeyDB issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3544), while keeping Redis and KeyDB support, for those who wished to remain on them
To reduce configuration complexity and maintenance overhead, we are now:
- removing Redis and KeyDB support entirely
- using Valkey as the sole Redis-compatible memorystore implementation
To update your configuration:
- **Most users** don't need to do anything
- **Users that were explicitly sticking to Redis/KeyDB** need to update their `vars.yml` to use `valkey_*` variables instead
# 2025-01-19
## conduwuit support
Thanks to [Virkkunen](https://github.com/Virkkunen), we now have optional experimental [conduwuit](https://conduwuit.puppyirl.gay/) homeserver support for new installations.
conduwuit is a fork of [Conduit](./docs/configuring-playbook-conduit.md), which the playbook also supports. See [Differences from upstream Conduit](https://conduwuit.puppyirl.gay/differences.html).
Existing installations do **not** need to be updated. **Synapse is still the default homeserver implementation** installed by the playbook.
To try out conduwuit, we recommend that you **use a new server**. Refer to our [Configuring conduwuit](./docs/configuring-playbook-conduwuit.md) guide for details.
**The homeserver implementation of an existing server cannot be changed** (e.g. from Synapse/Conduit/Dendrite to conduwuit) without data loss.
# 2025-01-14
## (Backward Compatibility Break) Synapse v1.122.0 requires Postgres v13
The Synapse homeserver [requires Postgres v13 or newer](https://github.com/element-hq/synapse/issues/18034).
If you've been maintaining your setup for a while and you haven't been doing [Postgres upgrades](docs/maintenance-postgres.md#upgrading-postgresql), you may be on an old version of Postgres. The easiest way to check is to see the contents of the `/matrix/postgres/data/PG_VERSION` file.
If you're on a Postgres version older than v13, you need to [upgrade your Postgres setup](docs/maintenance-postgres.md#upgrading-postgresql) or Synapse will produce an error on startup.
If you're using an external Postgres server (not installed by this playbook), you'll need to figure out how to upgrade it yourself.
If you're not ready to upgrade your Postgres setup yet, you can temporarily remain on an old Synapse version by adding the following configuration to your `vars.yml` file:
```yaml
# Pinning to the last Synapse version which supports Postgres v11 and v12.
matrix_synapse_version: v1.121.1
```
# 2024-11-26
## (Backward Compatibility Break) Synapse now defaults to enabling authenticated media
@ -231,11 +25,11 @@ You can disable authenticated media at any time by setting `matrix_synapse_enabl
The playbook used to install Redis or KeyDB if services have a need for a Redis-compatible implementation ([enabling worker support for Synapse](docs/configuring-playbook-synapse.md#load-balancing-with-workers), [enabling Hookshot encryption](docs/configuring-playbook-bridge-hookshot.md#end-to-bridge-encryption), etc.).
Earlier this year, we switched from Redis to KeyDB — see [(Backward Compatibility Break) The playbook now defaults to KeyDB, instead of Redis](#backward-compatibility-break-the-playbook-now-defaults-to-keydb-instead-of-redis).
Earlier this year, we switched from Redis to KeyDB - see [(Backward Compatibility Break) The playbook now defaults to KeyDB, instead of Redis](#backward-compatibility-break-the-playbook-now-defaults-to-keydb-instead-of-redis).
Because Valkey seems to be a better successor to Redis (than KeyDB) and likely doesn't suffer from [issues like this one](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3544), we now replace KeyDB with Valkey.
Valkey (like KeyDB and Redis in the past) is an implicitly enabled dependency — you don't need custom configuration in `vars.yml` to enable it.
Valkey (like KeyDB and Redis in the past) is an implicitly enabled dependency - you don't need custom configuration in `vars.yml` to enable it.
Next time your run the playbook (via the `setup-all` tag), **KeyDB will be automatically uninstalled and replaced with Valkey**. Some Synapse downtime may occur while the switch happens.
@ -357,7 +151,7 @@ As always, the playbook would let you know about this and point out any variable
## Support for baibot
The playbook now supports installing [baibot](./docs/configuring-playbook-bot-baibot.md) (pronounced bye-bot) — a [Matrix](https://matrix.org/) bot developed by [etke.cc](https://etke.cc/) that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you. 🤖
The playbook now supports installing [baibot](./docs/configuring-playbook-bot-baibot.md) (pronounced bye-bot) - a [Matrix](https://matrix.org/) bot developed by [etke.cc](https://etke.cc/) that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you. 🤖
It supports [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/chatgpt/) models, as well as many other [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md).
@ -369,15 +163,15 @@ To get started, see the [Setting up baibot](./docs/configuring-playbook-bot-baib
The playbook now installs [etke.cc](https://etke.cc/)'s [fork](https://github.com/etkecc/synapse-admin) of [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) (originally developed by [Awesome-Technologies](https://github.com/Awesome-Technologies)). This fork is a drop-in replacement for the original software.
The creation of the fork has been provoked by users frequently encountering issues with the original synapse-admin software, such as unintentionally deleting their one-and-only admin user account (fixed [here](https://github.com/etkecc/synapse-admin/pull/1) and also contributed upstream [here](https://github.com/Awesome-Technologies/synapse-admin/pull/608) — to no avail for now). Since its inception, [a bunch of other quality-of-life improvements](https://github.com/etkecc/synapse-admin?tab=readme-ov-file#changes) have been made to the fork.
The creation of the fork has been provoked by users frequently encountering issues with the original synapse-admin software, such as unintentionally deleting their one-and-only admin user account (fixed [here](https://github.com/etkecc/synapse-admin/pull/1) and also contributed upstream [here](https://github.com/Awesome-Technologies/synapse-admin/pull/608) - to no avail for now). Since its inception, [a bunch of other quality-of-life improvements](https://github.com/etkecc/synapse-admin?tab=readme-ov-file#changes) have been made to the fork.
If upstream synapse-admin picks up the pace and improves, the etke.cc fork may disappear and the playbook may switch to the original software again. Until that time comes, we believe that etke.cc's fork is the better software to use right now.
If you'd like to switch back to the original synapse-admin software, you can do so by adding the following configuration to your `vars.yml` file:
```yaml
matrix_synapse_admin_docker_image: "{{ matrix_synapse_admin_docker_image_registry_prefix }}awesometechnologies/synapse-admin:{{ matrix_synapse_admin_version }}"
matrix_synapse_admin_docker_image_registry_prefix_upstream: docker.io/
matrix_synapse_admin_docker_image: "{{ matrix_synapse_admin_docker_image_name_prefix }}awesometechnologies/synapse-admin:{{ matrix_synapse_admin_version }}"
matrix_synapse_admin_docker_image_name_prefix: "{{ 'localhost/' if matrix_synapse_admin_container_image_self_build else matrix_container_global_registry_prefix }}"
matrix_synapse_admin_version: 0.10.3
@ -440,7 +234,7 @@ matrix_corporal_version: 2.8.0
## synapse-usage-exporter support
Thanks to [Michael Hollister](https://github.com/Michael-Hollister) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/), the playbook can now set up [synapse-usage-exporter](https://github.com/loelkes/synapse-usage-exporter) — a small [Flask](https://flask.palletsprojects.com)-based webservice which can capture usage statistics from Synapse (via HTTP `PUT`) and then make them available for Prometheus to scrape.
Thanks to [Michael Hollister](https://github.com/Michael-Hollister) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/), the playbook can now set up [synapse-usage-exporter](https://github.com/loelkes/synapse-usage-exporter) - a small [Flask](https://flask.palletsprojects.com)-based webservice which can capture usage statistics from Synapse (via HTTP `PUT`) and then make them available for Prometheus to scrape.
To learn more see our [Enabling synapse-usage-exporter for Synapse usage statistics](docs/configuring-playbook-synapse-usage-exporter.md) documentation page.
@ -471,7 +265,7 @@ If you're using the playbook's Traefik instance to reverse-proxy to some other s
If you've tweaked any of this playbook's `_path_prefix` variables and made them use a regular expression, you will now need to make additional adjustments. The playbook makes extensive use of `PathPrefix()` matchers in Traefik rules and `PathPrefix` does not support regular expressions anymore. To work around it, you may now need to override a whole `_traefik_rule` variable and switch it from [`PathPrefix` to `PathRegexp`](https://doc.traefik.io/traefik/routing/routers/#path-pathprefix-and-pathregexp).
If you're not using [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) (the only role we had to tweak to adapt it to Traefik v3), you **may potentially downgrade to Traefik v2** (if necessary) by adding `traefik_verison: v2.11.4` to your configuration. People using `matrix-media-repo` cannot downgrade this way, because `matrix-media-repo` has been adjusted to use `PathRegexp` — a [routing matcher](https://doc.traefik.io/traefik/v2.11/routing/routers/#rule) that Traefik v2 does not understand.
If you're not using [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) (the only role we had to tweak to adapt it to Traefik v3), you **may potentially downgrade to Traefik v2** (if necessary) by adding `traefik_verison: v2.11.4` to your configuration. People using `matrix-media-repo` cannot downgrade this way, because `matrix-media-repo` has been adjusted to use `PathRegexp` - a [routing matcher](https://doc.traefik.io/traefik/v2.11/routing/routers/#rule) that Traefik v2 does not understand.
### HTTP/3 is enabled by default
@ -542,7 +336,7 @@ When generating new webhooks, you should start seeing the new URLs being used.
**For now**, **both** old URLs (`/hookshot/webhooks/:hookId`) and new URLs (`/hookshot/webhooks/webhook/:hookId`) **continue to work**, so your webhooks will not break just yet.
However, **we recommend that you update all your old webhook URLs** (configured in other systems) to include the new `/webhook` path component, so that future Hookshot changes (whenever they come) will not break your webhooks. You don't need to do anything on the Hookshot side — you merely need to reconfigure the remote systems that use your webhook URLs.
However, **we recommend that you update all your old webhook URLs** (configured in other systems) to include the new `/webhook` path component, so that future Hookshot changes (whenever they come) will not break your webhooks. You don't need to do anything on the Hookshot side - you merely need to reconfigure the remote systems that use your webhook URLs.
# 2024-06-22
@ -604,7 +398,7 @@ It should be noted that:
## 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.
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.
@ -624,9 +418,9 @@ The documentation page for [Draupnir for all](./docs/configuring-playbook-appser
## Support for bridging to Facebook/Messenger via the new mautrix-meta bridge
The [mautrix-facebook](./docs/configuring-playbook-bridge-mautrix-facebook.md) and [mautrix-instagram](./docs/configuring-playbook-bridge-mautrix-instagram.md) bridges are being [superseded by a new bridge](https://github.com/mautrix/facebook/issues/332) — the [mautrix-meta](https://github.com/mautrix/meta) bridge.
The [mautrix-facebook](./docs/configuring-playbook-bridge-mautrix-facebook.md) and [mautrix-instagram](./docs/configuring-playbook-bridge-mautrix-instagram.md) bridges are being [superseded by a new bridge](https://github.com/mautrix/facebook/issues/332) - the [mautrix-meta](https://github.com/mautrix/meta) bridge.
The playbook now supports the new mautrix-meta bridge — a single bridge, which can run in different modes and bridge to Messenger (via [Facebook](https://facebook.com/), Facebook over [Tor](https://www.torproject.org/) or via [Messenger](https://messenger.com/)) and [Instagram](https://instagram.com/). The playbook makes this bridge available via 2 separate Ansible roles, allowing you to easily run 2 instances of mautrix-meta, for bridging to both services at the same time.
The playbook now supports the new mautrix-meta bridge - a single bridge, which can run in different modes and bridge to Messenger (via [Facebook](https://facebook.com/), Facebook over [Tor](https://www.torproject.org/) or via [Messenger](https://messenger.com/)) and [Instagram](https://instagram.com/). The playbook makes this bridge available via 2 separate Ansible roles, allowing you to easily run 2 instances of mautrix-meta, for bridging to both services at the same time.
If you're using mautrix-facebook or mautrix-instagram right now, **you can still continue using the old bridges, but may wish to change to the new bridge implementations**. See:
@ -647,9 +441,9 @@ The playbook has always used a very conservative cache factor (`matrix_synapse_c
The playbook now uses **a 20x larger cache factor** (currently `10`), adjusts a few other cache-related variables, and **enables cache auto-tuning** via the following variables:
- `matrix_synapse_cache_autotuning_max_cache_memory_usage` — defaults to 1/8 of total RAM with a cap of 2GB; values are specified in bytes
- `matrix_synapse_cache_autotuning_target_cache_memory_usage` — defaults to 1/16 of total RAM with a cap of 1GB; values are specified in bytes
- `matrix_synapse_cache_autotuning_min_cache_ttl` — defaults to `30s`
- `matrix_synapse_cache_autotuning_max_cache_memory_usage` - defaults to 1/8 of total RAM with a cap of 2GB; values are specified in bytes
- `matrix_synapse_cache_autotuning_target_cache_memory_usage` - defaults to 1/16 of total RAM with a cap of 1GB; values are specified in bytes
- `matrix_synapse_cache_autotuning_min_cache_ttl` - defaults to `30s`
These values should be good defaults for most servers, but may change over time as we experiment further.
@ -662,7 +456,7 @@ Refer to our new [Tuning caches and cache autotuning](docs/maintenance-synapse.m
This only affects people who are [Serving a static website at the base domain](./docs/configuring-playbook-base-domain-serving.md#serving-a-static-website-at-the-base-domain), but not managing its `index.html` through the playbook.
That is, for people who have `matrix_static_files_file_index_html_enabled: false` in their `vars.yml` configuration, the playbook has a new default behavior. Since the playbook is not managing the `index.html` file, it will default to a more sensible way of handling the base domain — redirecting `https://example.com/` to `https://matrix.example.com/`, instead of serving a 404 page.
That is, for people who have `matrix_static_files_file_index_html_enabled: false` in their `vars.yml` configuration, the playbook has a new default behavior. Since the playbook is not managing the `index.html` file, it will default to a more sensible way of handling the base domain - redirecting `https://example.com/` to `https://matrix.example.com/`, instead of serving a 404 page.
If you are managing your static website by yourself (by dropping files into `/matrix/static-files/public` somehow), then you probably don't wish for such redirection to happen. You can disable it by adding `matrix_static_files_container_labels_base_domain_root_path_redirection_enabled: false` to your `vars.yml` configuration file.
@ -686,7 +480,7 @@ To get started, refer to our [Specialized workers](./docs/configuring-playbook-s
A few months ago, the [Element](https://element.io/) company has [announced](https://element.io/blog/element-to-adopt-agplv3/) that their work on the Synapse homeserver would no longer be available under the permissive [Apache-2.0 license](https://www.apache.org/licenses/LICENSE-2.0), but only under:
- the [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) free-software license — the same license that this Ansible playbook has always used
- the [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) free-software license - the same license that this Ansible playbook has always used
- a proprietary license, for those wishing for Element to [sell them an exception](https://gnu.org/philosophy/selling-exceptions.html) to the AGPLv3 license
You can also learn more in [this post](https://matrix.org/blog/2023/11/06/future-of-synapse-dendrite/) by the Matrix Foundation.
@ -717,7 +511,7 @@ matrix_synapse_version: v1.98.0
Notes:
- if you had already upgraded Synapse to `v1.99.0` by running this playbook, you will still be able to downgrade to `v1.98.0`, because both releases use the same database schema version (`SCHEMA_COMPAT_VERSION = 83` — see [here for v1.98.0](https://github.com/element-hq/synapse/blob/v1.98.0/synapse/storage/schema/__init__.py#L131-L134) and [here for v1.99.0](https://github.com/element-hq/synapse/blob/v1.99.0/synapse/storage/schema/__init__.py#L137-L140)). More details on Synapse's database schema are available [here](https://element-hq.github.io/synapse/develop/development/database_schema.html). It appears that there are no new database migrations introduced in `v1.99.0`, so going back to the older release is possible. This is not guaranteed to hold true for future Synapse releases, so if you're seeing this early-enough, consider pinning the version and organization before re-running the playbook and getting upgraded to the latest version
- if you had already upgraded Synapse to `v1.99.0` by running this playbook, you will still be able to downgrade to `v1.98.0`, because both releases use the same database schema version (`SCHEMA_COMPAT_VERSION = 83` - see [here for v1.98.0](https://github.com/element-hq/synapse/blob/v1.98.0/synapse/storage/schema/__init__.py#L131-L134) and [here for v1.99.0](https://github.com/element-hq/synapse/blob/v1.99.0/synapse/storage/schema/__init__.py#L137-L140)). More details on Synapse's database schema are available [here](https://element-hq.github.io/synapse/develop/development/database_schema.html). It appears that there are no new database migrations introduced in `v1.99.0`, so going back to the older release is possible. This is not guaranteed to hold true for future Synapse releases, so if you're seeing this early-enough, consider pinning the version and organization before re-running the playbook and getting upgraded to the latest version
- running an outdated homeserver exposes you to security issues and incompatibilities. Only consider doing this as a short-term solution.
@ -735,14 +529,14 @@ As of [#204](https://github.com/the-draupnir-project/Draupnir/pull/204) Draupnir
### Backstory on `matrix-nginx-proxy`
We gather here today to celebrate the loss of a once-beloved component in our stack — `matrix-nginx-proxy`. It's been our [nginx](https://nginx.org/)-based reverse-proxy of choice since the [first commit](https://github.com/spantaleev/matrix-docker-ansible-deploy/tree/87f5883f2455fb115457b65f267f17de305c053c) of this playbook, 7 years ago.
We gather here today to celebrate the loss of a once-beloved component in our stack - `matrix-nginx-proxy`. It's been our [nginx](https://nginx.org/)-based reverse-proxy of choice since the [first commit](https://github.com/spantaleev/matrix-docker-ansible-deploy/tree/87f5883f2455fb115457b65f267f17de305c053c) of this playbook, 7 years ago.
For 6 years, `matrix-nginx-proxy` has been the front-most reverse-proxy in our setup (doing SSL termination, etc.). After [transitioning to Traefik last year](#traefik-is-the-default-reverse-proxy-now), `matrix-nginx-proxy` took a step back. Nevertheless, since it was so ingrained into the playbook, it still remained in use — even if only internally. Despite our warnings of its imminent death, many of you have indubitably continued to use it instead of Traefik. Its suffering continued for too long, because it served many different purposes and massive effort was required to transition them to others.
For 6 years, `matrix-nginx-proxy` has been the front-most reverse-proxy in our setup (doing SSL termination, etc.). After [transitioning to Traefik last year](#traefik-is-the-default-reverse-proxy-now), `matrix-nginx-proxy` took a step back. Nevertheless, since it was so ingrained into the playbook, it still remained in use - even if only internally. Despite our warnings of its imminent death, many of you have indubitably continued to use it instead of Traefik. Its suffering continued for too long, because it served many different purposes and massive effort was required to transition them to others.
To us, `matrix-nginx-proxy` was:
- an [nginx](https://nginx.org/)-based reverse-proxy
- an Ansible role organizing the work of [certbot](https://certbot.eff.org/) — retrieving free [Let's Encrypt](https://letsencrypt.org/) SSL certificates for `matrix-nginx-proxy` and for the [coturn TURN server](./docs/configuring-playbook-turn.md)
- an Ansible role organizing the work of [certbot](https://certbot.eff.org/) - retrieving free [Let's Encrypt](https://letsencrypt.org/) SSL certificates for `matrix-nginx-proxy` and for the [Coturn TURN server](./docs/configuring-playbook-turn.md)
- a central component for reverse-proxying to the [long list of services](./docs/configuring-playbook.md) supported by the playbook. As such, it became a dependency that all these services had to inject themselves into during runtime
- an intermediary through which addons (bridges, bots) communicated with the homeserver. Going through an intermediary (instead of directly talking to the homeserver) is useful when certain components (like [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) or [matrix-corporal](./docs/configuring-playbook-matrix-corporal.md)) are enabled, because it lets these services "steal routes" from the homeserver
- a webserver for serving the `/.well-known/matrix` static files (generated by the `matrix-base` role until now)
@ -753,7 +547,7 @@ Talk about a jack of all trades! The [UNIX philosophy](https://en.wikipedia.org/
On a related note, we also had a large chain of reverse-proxies in the mix. In the worst case, it was something like this: (Traefik -> `matrix-nginx-proxy:8080` -> `matrix-nginx-proxy:12080` -> `matrix-synapse-reverse-proxy-companion:8008` -> `matrix-synapse:8008`).
Due to complexity and the playbook's flexibility (trying to accommodate a mix of tens of components), many layers of indirection were necessary. We do like reverse-proxies, but… not quite enough to enjoy going through a chain of ~4 of them before reaching the target service.
Due to complexity and the playbook's flexibility (trying to accommodate a mix of tens of components), many layers of indirection were necessary. We do like reverse-proxies, but.. not quite enough to enjoy going through a chain of ~4 of them before reaching the target service.
After **a ton of work** in the last weeks (200+ commits, which changed 467 files - 8684 insertions and 8913 deletions), **we're finally saying goodbye** to `matrix-nginx-proxy`.
@ -767,9 +561,9 @@ This reduces "network" hops (improving performance) and also decreases the numbe
### Traefik now has an extra job
Previously, **Traefik had a single purpose** — being the main reverse-proxy. It was either front-most (terminating SSL, etc.) or you were [fronting Traefik with your own other reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy). In any case — it had this central (yet decentralized) job.
Previously, **Traefik had a single purpose** - being the main reverse-proxy. It was either front-most (terminating SSL, etc.) or you were [fronting Traefik with your own other reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy). In any case - it had this central (yet decentralized) job.
Now, **Traefik has one more role** — it serves as an intermediary which allows addon services (bridges, bots, etc.) to communicate with the homeserver. As mentioned above, such an intermediary service is not strictly necessary in all kinds of setups, but more complex setups (including [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) or [matrix-corporal](./docs/configuring-playbook-matrix-corporal.md)) benefit from it.
Now, **Traefik has one more role** - it serves as an intermediary which allows addon services (bridges, bots, etc.) to communicate with the homeserver. As mentioned above, such an intermediary service is not strictly necessary in all kinds of setups, but more complex setups (including [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) or [matrix-corporal](./docs/configuring-playbook-matrix-corporal.md)) benefit from it.
To perform this new role, Traefik now has a new internal [entrypoint](https://doc.traefik.io/traefik/routing/entrypoints/) called `matrix-internal-matrix-client-api`. All homeservers (Conduit, Dendrite, Synapse and even `matrix-synapse-reverse-proxy-companion`) and homeserver-related core services ([matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md), [matrix-corporal](./docs/configuring-playbook-matrix-corporal.md) and potentially others) register their routes (using [container labels](https://docs.docker.com/config/labels-custom-metadata/)) not only on the public entrypoints (`web-secure`, `matrix-federation`), but also on this new internal entrypoint.
@ -804,7 +598,7 @@ If you don't do these changes (switching from `traefik_additional_entrypoints_au
### Supported reverse proxy types are now fewer
This section is for people using a more custom reverse-proxy setup — those having `matrix_playbook_reverse_proxy_type` set to a value different than the default (`playbook-managed-traefik`).
This section is for people using a more custom reverse-proxy setup - those having `matrix_playbook_reverse_proxy_type` set to a value different than the default (`playbook-managed-traefik`).
Previously, we allowed you to set `matrix_playbook_reverse_proxy_type` to 7 different values to accommodate various reverse-proxy setups.
@ -827,9 +621,9 @@ If you were using these values as a way to stay away from Traefik, you now have
Now that `matrix-nginx-proxy` is not in the mix, it became easier to clear out some other long-overdue technical debt.
Since the very beginning of this playbook, all playbook services were connected to a single (shared) `matrix` container network. Later on, some additional container networks appeared, but most services (database, etc.) still remained in the `matrix` container network. This meant that any random container in this network could try to talk (or attack) the Postgres database operating in the same `matrix` network.
Since the very beginning of this playbook, all playbook services were connected to a single (shared) `matrix` container network. Later on, some additional container networks appeared, but most services (database, etc.) still remained in the `matrix` container network. This meant that any random container in this network could try to talk (or attack) the Postgres database operating in the same `matrix` network.
Moving components (especially the database) into other container networks was difficult — it required changes to many other components to ensure correct connectivity.
Moving components (especially the database) into other container networks was difficult - it required changes to many other components to ensure correct connectivity.
All the hard work has been done now. We've added much more isolation between services by splitting them up into separate networks (`matrix-homeserver`, `matrix-addons`, `matrix-monitoring`, `matrix-exim-relay`, etc). Components are only joined to the networks they need and should (for the most part) not be able to access unrelated things.
@ -843,11 +637,11 @@ This section is for people who are exposing monitoring metrics publicly, to be c
Previously, `matrix-nginx-proxy` was potentially password-protecting all `/metrics/*` endpoints with the same username and password (specified as plain-text in your `vars.yml` configuration file).
From now on, there are new variables for doing roughly the same — `matrix_metrics_exposure_enabled`, `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`. See the [Prometheus & Grafana](./docs/configuring-playbook-prometheus-grafana.md) docs page for details.
From now on, there are new variables for doing roughly the same - `matrix_metrics_exposure_enabled`, `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`. See the [Prometheus & Grafana](./docs/configuring-playbook-prometheus-grafana.md) docs page for details.
`matrix-nginx-proxy` is not acting as a "global guardian" anymore. Now, each role provides its own metrics exposure and protection by registering with Traefik. Nevertheless, all roles are wired (via playbook configuration in `group_vars/matrix_servers`) to obey these new `matrix_metrics_exposure_*` variables. We've eliminated the centralization, but have kept the ease of use. Now, you can also do per-service password-protection (with different credentials), should you need to do that for some reason.
The playbook will tell you about all variables that you need to migrate during runtime, so rest assured — you shouldn't be able to miss anything!
The playbook will tell you about all variables that you need to migrate during runtime, so rest assured - you shouldn't be able to miss anything!
### Matrix static files
@ -867,9 +661,9 @@ We believe that using Traefik provides way too many benefits to worry about this
The heaviest part of running a Matrix homeserver is all the slow and potentially inefficient things the homeserver (e.g. Synapse) is doing. These things affect performance much more than whatever reverse-proxy is in front. Your server will die the same way by joining the famously large **Matrix HQ** room, no matter which reverse-proxy you put in front.
Even our previously mentioned benchmarks (yielding ~1300 rps) are synthetic — hitting a useless `/_matrix/client/versions` endpoint. Real-use does much more than this.
Even our previously mentioned benchmarks (yielding ~1300 rps) are synthetic - hitting a useless `/_matrix/client/versions` endpoint. Real-use does much more than this.
If this is still not convincing enough for you and you want the best possible performance, consider [Fronting Traefik with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) (thus having the slowest part — SSL termination — happen elsewhere) or [Using no reverse-proxy on the Matrix side at all](./docs/configuring-playbook-own-webserver.md#using-no-reverse-proxy-on-the-matrix-side-at-all). The playbook will not get in your way of doing that, but these options may make your life much harder. Performance comes at a cost, after all.
If this is still not convincing enough for you and you want the best possible performance, consider [Fronting Traefik with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) (thus having the slowest part - SSL termination - happen elsewhere) or [Using no reverse-proxy on the Matrix side at all](./docs/configuring-playbook-own-webserver.md#using-no-reverse-proxy-on-the-matrix-side-at-all). The playbook will not get in your way of doing that, but these options may make your life much harder. Performance comes at a cost, after all.
### Migration procedure
@ -881,7 +675,7 @@ The updated playbook will automatically perform some migration tasks for you:
3. It will delete the `/matrix/ssl` directory and all files within it. You can disable this behavior by adding `matrix_playbook_migration_matrix_ssl_uninstallation_enabled: false` to your `vars.yml` configuration file. If you have some important certificates there for some reason, take them out or temporarily disable removal of these files until you do.
4. It will tell you about all variables (`matrix_nginx_proxy_*` and many others — even from other roles) that have changed during this large nginx-elimination upgrade. You can disable this behavior by adding `matrix_playbook_migration_matrix_nginx_proxy_elimination_variable_transition_checks_enabled: false` to your `vars.yml` configuration file.
4. It will tell you about all variables (`matrix_nginx_proxy_*` and many others - even from other roles) that have changed during this large nginx-elimination upgrade. You can disable this behavior by adding `matrix_playbook_migration_matrix_nginx_proxy_elimination_variable_transition_checks_enabled: false` to your `vars.yml` configuration file.
5. It will tell you about any leftover `matrix_nginx_proxy_*` variables in your `vars.yml` file. You can disable this behavior by adding `matrix_playbook_migration_matrix_nginx_proxy_leftover_variable_validation_checks_enabled: false` to your `vars.yml` configuration file.
@ -1004,17 +798,17 @@ The playbook should **automatically migrate your mautrix-signal installation to
**TDLR**: if your Matrix server is federating (which it mostly likely is, unless you've [disabled federation](docs/configuring-playbook-federation.md#disabling-federation)), your public rooms will not only be joinable across federation (as they've always been), but from now on will be discoverable (made available as a list across federation). We're changing this by flipping the value for Synapse's `allow_public_rooms_over_federation` setting to `true`, going against the upstream default. Servers that disable federation are not affected. Servers that have public rooms which are not published to the room directory are also not affected.
We generally try to stick to the default configuration for Synapse (and all other components), unless these defaults seem wrong or harmful. One such previous case from a few months ago was us [Enabling `forget_rooms_on_leave` by default for Synapse](#enabling-forget_rooms_on_leave-by-default-for-synapse) — the default value was making Synapse more wasteful of resources by default.
We generally try to stick to the default configuration for Synapse (and all other components), unless these defaults seem wrong or harmful. One such previous case from a few months ago was us [Enabling `forget_rooms_on_leave` by default for Synapse](#enabling-forget_rooms_on_leave-by-default-for-synapse) - the default value was making Synapse more wasteful of resources by default.
Today, we're going against upstream defaults again and flipping the `allow_public_rooms_over_federation` configuration option to `true`. This way, public rooms on your server will be made discoverable by others via federation, using the [`GET /_matrix/federation/v1/publicRooms` of the Server-Server API](https://spec.matrix.org/v1.8/server-server-api/#get_matrixfederationv1publicrooms).
The upstream Synapse default is `false` (disabled), so that public rooms are not exposed for other servers to discover (learn about their existence). Nevertheless, even if these rooms are not exposed (listed) for discovery, they are **still joinable** by anyone who knows their address or is invited to the room by an existing member.
**We go against the upstream default** in an effort to make Matrix federation more useful — a public room should be globally public — not only joinable, but also discoverable across federation.
**We go against the upstream default** in an effort to make Matrix federation more useful - a public room should be globally public - not only joinable, but also discoverable across federation.
The **historical reasoning** behind this change is as follows:
- `allow_public_rooms_over_federation` seems to have been enabled by default for Synapse until v1.7.0 (~2019), just like we believe it should be for a globally-federating network — rooms should be joinable and discoverable across federation.
- `allow_public_rooms_over_federation` seems to have been enabled by default for Synapse until v1.7.0 (~2019), just like we believe it should be for a globally-federating network - rooms should be joinable and discoverable across federation.
- In Synapse v1.7.0 (~2019), `allow_public_rooms_over_federation` [got disabled](https://github.com/element-hq/synapse/blob/e9069c9f919685606506f04527332e83fbfa44d9/docs/upgrade.md?plain=1#L1877-L1891) by default in a [security-by-obscurity](https://en.wikipedia.org/wiki/Security_through_obscurity) workaround for misconfigured servers. See the [Avoiding unwelcome visitors on private Matrix servers](https://matrix.org/blog/2019/11/09/avoiding-unwelcome-visitors-on-private-matrix-servers/) `matrix.org` blog article. We believe that people wishing for a truly private server, should [disable federation](docs/configuring-playbook-federation.md#disabling-federation), instead of having a fully-federating server and trying to hide its public rooms. We also provide other workarounds below. We (and the Synapse team, obviously) believe that Matrix should federate by default, so federating the public room list seems to make sense.
@ -1024,7 +818,7 @@ Here are **actions you may wish to take** as a result of this change:
- (recommended) embrace the new default. If your Matrix server is federating, your public rooms have always been joinable across federation anyway. Exposing the list of public rooms does no harm and more-so does good by contributing to the usefulness of the Matrix network by facilitating room discovery.
- (switch to a better way of doings things on your semi-private server) The problem that the Synapse team appears to have solved by flipping the `allow_public_rooms_over_federation` default in Synapse v1.7.0 seems to for "mostly private" servers, which federate and have a bunch of rooms made public (and published in their room directory) in an effort to allow people on the same homeserver to easily find and join them (self-onboarding). With the introduction of Matrix Spaces, you can reorganize your flow around spaces — you can auto-join your users to a Matrix Space (via Synapse's `auto_join_rooms` setting — controlled by our `matrix_synapse_auto_join_rooms` variable), then add a bunch of rooms to the space and make them joinable by people belonging to the space. That is to say, do not make rooms public and do not publish them to the room directory unless they are really public. Instead, use other mechanisms for semi-public rooms or private rooms. One alternative is to stick to what you're doing (public rooms published to your rooms directory) but having a `m.federate: true` flag set during creation (clients like Element Web have a nice UI checkbox for this) to explicitly disable federation for them.
- (switch to a better way of doings things on your semi-private server) The problem that the Synapse team appears to have solved by flipping the `allow_public_rooms_over_federation` default in Synapse v1.7.0 seems to for "mostly private" servers, which federate and have a bunch of rooms made public (and published in their room directory) in an effort to allow people on the same homeserver to easily find and join them (self-onboarding). With the introduction of Matrix Spaces, you can reorganize your flow around spaces - you can auto-join your users to a Matrix Space (via Synapse's `auto_join_rooms` setting - controlled by our `matrix_synapse_auto_join_rooms` variable), then add a bunch of rooms to the space and make them joinable by people belonging to the space. That is to say, do not make rooms public and do not publish them to the room directory unless they are really public. Instead, use other mechanisms for semi-public rooms or private rooms. One alternative is to stick to what you're doing (public rooms published to your rooms directory) but having a `m.federate: true` flag set during creation (clients like Element Web have a nice UI checkbox for this) to explicitly disable federation for them.
- (keeping the old behavior) if you wish to keep doing what you're doing (keeping your Matrix server federating, but hiding its public rooms list), add `matrix_synapse_allow_public_rooms_over_federation: false` to your `vars.yml` configuration. This restores the old behavior. You may also consider [disabling federation](docs/configuring-playbook-federation.md#disabling-federation) completely instead of relying on security-by-obscurity measures.
@ -1083,7 +877,7 @@ Thanks to [Shreyas Ajjarapu](https://github.com/shreyasajj)'s efforts, the playb
## matrix-media-repo support
Thanks to [Michael Hollister](https://github.com/Michael-Hollister) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/), the playbook can now set up [matrix-media-repo](https://github.com/turt2live/matrix-media-repo) — an alternative way to store homeserver media files, powered by a homeserver-independent implementation which supports S3 storage, IPFS, deduplication and other advanced features.
Thanks to [Michael Hollister](https://github.com/Michael-Hollister) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/), the playbook can now set up [matrix-media-repo](https://github.com/turt2live/matrix-media-repo) - an alternative way to store homeserver media files, powered by a homeserver-independent implementation which supports S3 storage, IPFS, deduplication and other advanced features.
To learn more see our [Storing Matrix media files using matrix-media-repo](docs/configuring-playbook-matrix-media-repo.md) documentation page.
@ -1107,7 +901,7 @@ If you'd like to go back to the old behavior, add the following to your configur
**TLDR**: the `matrix-jitsi` role is now included from the [ansible-role-jitsi](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi) repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook). Some variables have been renamed. All functionality remains intact.
The `matrix-jitsi` role has been relocated in its own repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) project — an Ansible playbook for self-hosting [a growing list of FOSS software](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md). If hosting a Jitsi stack on the Matrix server itself did not stand right with you or you always wanted to host most stuff, you can now use this new playbook to do so.
The `matrix-jitsi` role has been relocated in its own repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) project - an Ansible playbook for self-hosting [a growing list of FOSS software](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md). If hosting a Jitsi stack on the Matrix server itself did not stand right with you or you always wanted to host most stuff, you can now use this new playbook to do so.
As part of the extraction process of this role out of the Matrix playbook, a few other things improved:
@ -1137,7 +931,7 @@ This change was already applied a while before this entry, but as some users wer
**TLDR**: the `matrix-prometheus` role is now included from the [ansible-role-prometheus](https://github.com/mother-of-all-self-hosting/ansible-role-prometheus) repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook). Some variables have been renamed. All functionality remains intact.
The `matrix-prometheus` role has been relocated in its own repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) project — an Ansible playbook for self-hosting [a growing list of FOSS software](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md). If hosting a Prometheus stack on the Matrix server itself did not stand right with you or you always wanted to host most stuff, you can now use this new playbook to do so.
The `matrix-prometheus` role has been relocated in its own repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) project - an Ansible playbook for self-hosting [a growing list of FOSS software](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md). If hosting a Prometheus stack on the Matrix server itself did not stand right with you or you always wanted to host most stuff, you can now use this new playbook to do so.
Extracting the Prometheus role out of this Matrix playbook required huge internal refactoring to the way the Prometheus configuration (scraping jobs) is generated. If you notice any breakage after upgrading, let us know.
@ -1156,7 +950,7 @@ If you're making use of Prometheus via this playbook, you will need to update va
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up [rust-synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state)'s `synapse_auto_compressor` tool to run periodically.
If enabled, `synapse_auto_compressor` runs on a schedule and compresses your Synapse database's `state_groups` table. It was possible to run `rust-synapse-compress-state` manually via the playbook even before — see [Compressing state with rust-synapse-compress-state](docs/maintenance-synapse.md#compressing-state-with-rust-synapse-compress-state). However, using `synapse_auto_compressor` is better, because:
If enabled, `synapse_auto_compressor` runs on a schedule and compresses your Synapse database's `state_groups` table. It was possible to run `rust-synapse-compress-state` manually via the playbook even before - see [Compressing state with rust-synapse-compress-state](docs/maintenance-synapse.md#compressing-state-with-rust-synapse-compress-state). However, using `synapse_auto_compressor` is better, because:
- it runs on a more up-to-date version of `rust-synapse-compress-state`
- it's a set-it-and-forget-it tool that you can enable and never have to deal with manual compression anymore
@ -1220,7 +1014,7 @@ Until now, we've been doing the migration gradually and keeping full backward co
- Traefik managed by the user in another way
- another reverse-proxy on the same host (`127.0.0.1` port exposure)
- another reverse-proxy on another host (`0.0.0.0` port exposure)
- `matrix-nginx-proxy` — an `nginx` container managed by the playbook
- `matrix-nginx-proxy` - an `nginx` container managed by the playbook
- `nginx` webserver operated by the user, running without a container on the same server
Each change we do and each new feature that comes in needs to support all these different ways of reverse-proxying. Because `matrix-nginx-proxy` was the default and pretty much everyone was (and still is) using it, means that new PRs also come with `matrix-nginx-proxy` as their main focus and Traefik as an afterthought, which means we need to spend hours fixing up Traefik support.
@ -1337,7 +1131,7 @@ You need to **update your roles** (`just roles` or `make roles`) regardless of w
### Motivation for redoing our reverse-proxy setup
The playbook has supported various reverse-proxy setups for a long time. We have various configuration variables (`matrix_nginx_proxy_enabled`, various `_host_bind_port` variables, etc.) which allow the playbook to adapt to these different setups. The whole situation was messy though — hard to figure out and with lots of variables to toggle to make things work as you'd expect — huge **operational complexity**.
The playbook has supported various reverse-proxy setups for a long time. We have various configuration variables (`matrix_nginx_proxy_enabled`, various `_host_bind_port` variables, etc.) which allow the playbook to adapt to these different setups. The whole situation was messy though - hard to figure out and with lots of variables to toggle to make things work as you'd expect - huge **operational complexity**.
We love containers, proven by the fact that **everything** that this playbook manages runs in a container. Yet, we weren't allowing people to easily host other web-exposed containers alongside Matrix services on the same server. We were using `matrix-nginx-proxy` (our integrated [nginx](https://nginx.org/) server), which was handling web-exposure and SSL termination for our own services, but we **weren't helping you with all your other containers**.
@ -1352,19 +1146,19 @@ Others still, wanted to run Matrix locally (no SSL certificates), regardless of
Despite this operational complexity, things worked and were reasonably flexible to adapt to all these situations.
When using `matrix-nginx-proxy` as is, we still had another problem — one of **internal playbook complexity**. Too many services need to be web-exposed (port 80/443, SSL certificates). Because of this, they all had to integrate with the `matrix-nginx-proxy` role. Tens of different roles explicitly integrating with `matrix-nginx-proxy` is not what we call clean. The `matrix-nginx-proxy` role contains variables for many of these roles (yikes). Other roles were more decoupled from it and were injecting configuration into `matrix-nginx-proxy` at runtime — see all the `inject_into_nginx_proxy.yml` task files in this playbook (more decoupled, but still… yikes).
When using `matrix-nginx-proxy` as is, we still had another problem - one of **internal playbook complexity**. Too many services need to be web-exposed (port 80/443, SSL certificates). Because of this, they all had to integrate with the `matrix-nginx-proxy` role. Tens of different roles explicitly integrating with `matrix-nginx-proxy` is not what we call clean. The `matrix-nginx-proxy` role contains variables for many of these roles (yikes). Other roles were more decoupled from it and were injecting configuration into `matrix-nginx-proxy` at runtime - see all the `inject_into_nginx_proxy.yml` task files in this playbook (more decoupled, but still.. yikes).
The next problem is one of **efficiency, interoperability and cost-saving**. We're working on other playbooks:
- [vaultwarden-docker-ansible-deploy](https://github.com/spantaleev/vaultwarden-docker-ansible-deploy) for hosting the [Vaultwarden](https://github.com/dani-garcia/vaultwarden) server — an alternative implementation of the [Bitwarden](https://bitwarden.com/) password manager
- [gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy) — for hosting the [Gitea](https://gitea.io/) git source code hosting service
- [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy) — for hosting the [Nextcloud](https://nextcloud.com/) groupware platform
- [vaultwarden-docker-ansible-deploy](https://github.com/spantaleev/vaultwarden-docker-ansible-deploy) for hosting the [Vaultwarden](https://github.com/dani-garcia/vaultwarden) server - an alternative implementation of the [Bitwarden](https://bitwarden.com/) password manager
- [gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy) - for hosting the [Gitea](https://gitea.io/) git source code hosting service
- [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy) - for hosting the [Nextcloud](https://nextcloud.com/) groupware platform
We'd love for users to be able to **seamlessly use all these playbooks (and others, even) against a single server**. We don't want `matrix-nginx-proxy` to have a monopoly on port `80`/`443` and make it hard for other services to join in on the party. Such a thing forces people into running multiple servers (one for each service), which does provide nice security benefits, but is costly and ineffiecient. We'd like to make self-hosting these services cheap and easy.
These other playbooks have been using [Traefik](https://traefik.io/) as their default reverse-proxy for a long time. They can all coexist nicely together (as an example, see the [Interoperability](https://github.com/spantaleev/nextcloud-docker-ansible-deploy/blob/master/docs/configuring-playbook-interoperability.md) documentation for the [Nextcloud playbook](https://github.com/spantaleev/nextcloud-docker-ansible-deploy)). Now that this playbook is gaining Traefik support, it will be able to interoperate with them. If you're going this way, make sure to have the Matrix playbook install Traefik and have the others use `*_reverse_proxy_type: other-traefik-container`.
Finally, at [etke.cc — a managed Matrix server hosting service](https://etke.cc) (built on top of this playbook, and coincidentally [turning 2 years old today](https://etke.cc/news/upsyw4ykbtgmwhz8k7ukldx0zbbfq-fh0iqi3llixi0/) 🎉), we're allowing people to host some additional services besides Matrix components. Exposing these services to the web requires ugly hacks and configuration files being dropped into `/matrix/nginx-proxy/conf.d`. We believe that everything should run in independent containers and be exposed to the web via a Traefik server, without a huge Ansible role like `matrix-nginx-proxy` that everything else needs to integrate with.
Finally, at [etke.cc - a managed Matrix server hosting service](https://etke.cc) (built on top of this playbook, and coincidentally [turning 2 years old today](https://etke.cc/news/upsyw4ykbtgmwhz8k7ukldx0zbbfq-fh0iqi3llixi0/) 🎉), we're allowing people to host some additional services besides Matrix components. Exposing these services to the web requires ugly hacks and configuration files being dropped into `/matrix/nginx-proxy/conf.d`. We believe that everything should run in independent containers and be exposed to the web via a Traefik server, without a huge Ansible role like `matrix-nginx-proxy` that everything else needs to integrate with.
### How do these changes fix all these problems?
@ -1394,6 +1188,8 @@ Unless we have some regression, **existing `matrix-nginx-proxy` users should be
```yaml
matrix_playbook_reverse_proxy_type: playbook-managed-traefik
traefik_config_certificatesResolvers_acme_email: YOUR_EMAIL_ADDRESS
```
You may still need to keep certain old `matrix_nginx_proxy_*` variables (like `matrix_nginx_proxy_base_domain_serving_enabled`), even when using Traefik. For now, we recommend keeping all `matrix_nginx_proxy_*` variables just in case. In the future, reliance on `matrix-nginx-proxy` will be removed.
@ -1404,7 +1200,7 @@ Switching to Traefik will obtain new SSL certificates from Let's Encrypt (stored
Treafik directly reverse-proxies to **some** services right now, but for most other services it goes through `matrix-nginx-proxy` (e.g. Traefik -> `matrix-nginx-proxy` -> [Ntfy](docs/configuring-playbook-ntfy.md)). So, even if you opt into Traefik, you'll still see `matrix-nginx-proxy` being installed in local-only mode. This will improve with time.
Some services (like [coturn](docs/configuring-playbook-turn.md) and [Postmoogle](docs/configuring-playbook-bridge-postmoogle.md)) cannot be reverse-proxied to directly from Traefik, so they require direct access to SSL certificate files extracted out of Traefik. The playbook does this automatically thanks to a new [com.devture.ansible.role.traefik_certs_dumper](https://github.com/devture/com.devture.ansible.role.traefik_certs_dumper) role utilizing the [traefik-certs-dumper](https://github.com/ldez/traefik-certs-dumper) tool.
Some services (like [Coturn](docs/configuring-playbook-turn.md) and [Postmoogle](docs/configuring-playbook-bridge-postmoogle.md)) cannot be reverse-proxied to directly from Traefik, so they require direct access to SSL certificate files extracted out of Traefik. The playbook does this automatically thanks to a new [com.devture.ansible.role.traefik_certs_dumper](https://github.com/devture/com.devture.ansible.role.traefik_certs_dumper) role utilizing the [traefik-certs-dumper](https://github.com/ldez/traefik-certs-dumper) tool.
Our Traefik setup mostly works, but certain esoteric features may not work. If you have a default setup, we expect you to have a good experience.
@ -1427,7 +1223,7 @@ You can help by:
- **explicitly switching your server to Traefik** right now (see example configuration in [How do I explicitly switch to Traefik right now?](#how-do-i-explicitly-switch-to-traefik-right-now) above), testing, reporting troubles
- **adding native Traefik support to a role** (requires adding Traefik labels, etc.) — for inspiration, see these roles ([prometheus_node_exporter](https://github.com/mother-of-all-self-hosting/ansible-role-prometheus-node-exporter), [prometheus_postgres_exporter](https://github.com/mother-of-all-self-hosting/ansible-role-prometheus-postgres-exporter)) and how they're hooked into the playbook via [group_vars/matrix_servers](group_vars/matrix_servers).
- **adding native Traefik support to a role** (requires adding Traefik labels, etc.) - for inspiration, see these roles ([prometheus_node_exporter](https://github.com/mother-of-all-self-hosting/ansible-role-prometheus-node-exporter), [prometheus_postgres_exporter](https://github.com/mother-of-all-self-hosting/ansible-role-prometheus-postgres-exporter)) and how they're hooked into the playbook via [group_vars/matrix_servers](group_vars/matrix_servers).
- **adding reverse-proxying examples for nginx users** in `examples/nginx`. People who insist on using their own `nginx` server on the same Matrix host, can run Traefik in local-only mode (`traefik_config_entrypoint_web_secure_enabled: false`) and reverse-proxy to the Traefik server
@ -1464,29 +1260,29 @@ Other roles which aren't strictly related to Matrix are likely to follow this fa
# 2023-01-26
## coturn can now use host-networking
## Coturn can now use host-networking
Large coturn deployments (with a huge range of ports specified via `matrix_coturn_turn_udp_min_port` and `matrix_coturn_turn_udp_max_port`) experience a huge slowdown with how Docker publishes all these ports (setting up firewall forwarding rules), which leads to a very slow coturn service startup and shutdown.
Large Coturn deployments (with a huge range of ports specified via `matrix_coturn_turn_udp_min_port` and `matrix_coturn_turn_udp_max_port`) experience a huge slowdown with how Docker publishes all these ports (setting up firewall forwarding rules), which leads to a very slow Coturn service startup and shutdown.
Such deployments don't need to run coturn within a private container network anymore. coturn can now run with host-networking by using configuration like this:
Such deployments don't need to run Coturn within a private container network anymore. Coturn can now run with host-networking by using configuration like this:
```yaml
matrix_coturn_container_network: host
```
With such a configuration, **Docker no longer needs to configure thousands of firewall forwarding rules** each time coturn starts and stops. This, however, means that **you will need to ensure these ports are open** in your firewall yourself.
With such a configuration, **Docker no longer needs to configure thousands of firewall forwarding rules** each time Coturn starts and stops. This, however, means that **you will need to ensure these ports are open** in your firewall yourself.
Thanks to us [tightening coturn security](#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues), running coturn with host-networking should be safe and not expose neither other services running on the host, nor other services running on the local network.
Thanks to us [tightening Coturn security](#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues), running Coturn with host-networking should be safe and not expose neither other services running on the host, nor other services running on the local network.
## (Backward Compatibility) Tightening coturn security can lead to connectivity issues
## (Backward Compatibility) Tightening Coturn security can lead to connectivity issues
**TLDR**: users who run and access their Matrix server on a private network (likely a small minority of users) may experience connectivity issues with our new default coturn blocklists. They may need to override `matrix_coturn_denied_peer_ips` and remove some IP ranges from it.
**TLDR**: users who run and access their Matrix server on a private network (likely a small minority of users) may experience connectivity issues with our new default Coturn blocklists. They may need to override `matrix_coturn_denied_peer_ips` and remove some IP ranges from it.
Inspired by [this security article](https://www.rtcsec.com/article/cve-2020-26262-bypass-of-coturns-access-control-protection/), we've decided to make use of coturn's `denied-peer-ip` functionality to prevent relaying network traffic to certain private IP subnets. This ensures that your coturn server won't accidentally try to forward traffic to certain services running on your local networks. We run coturn in a container and in a private container network by default, which should prevent such access anyway, but having additional block layers in place is better.
Inspired by [this security article](https://www.rtcsec.com/article/cve-2020-26262-bypass-of-coturns-access-control-protection/), we've decided to make use of Coturn's `denied-peer-ip` functionality to prevent relaying network traffic to certain private IP subnets. This ensures that your Coturn server won't accidentally try to forward traffic to certain services running on your local networks. We run Coturn in a container and in a private container network by default, which should prevent such access anyway, but having additional block layers in place is better.
If you access your Matrix server from a local network and need coturn to relay to private IP addresses, you may observe that relaying is now blocked due to our new default `denied-peer-ip` lists (specified in `matrix_coturn_denied_peer_ips`). If you experience such connectivity problems, consider overriding this setting in your `vars.yml` file and removing certain networks from it.
If you access your Matrix server from a local network and need Coturn to relay to private IP addresses, you may observe that relaying is now blocked due to our new default `denied-peer-ip` lists (specified in `matrix_coturn_denied_peer_ips`). If you experience such connectivity problems, consider overriding this setting in your `vars.yml` file and removing certain networks from it.
We've also added `no-multicast-peers` to the default coturn configuration, but we don't expect this to cause trouble for most people.
We've also added `no-multicast-peers` to the default Coturn configuration, but we don't expect this to cause trouble for most people.
# 2023-01-21
@ -1510,16 +1306,16 @@ Other roles which aren't strictly related to Matrix are likely to follow this fa
We've previously used [make](https://www.gnu.org/software/make/) for easily running some playbook commands (e.g. `make roles` which triggers `ansible-galaxy`, see [Makefile](Makefile)). Our `Makefile` is still around and you can still run these commands.
In addition, we've added support for running commands via [just](https://github.com/casey/just) — a more modern command-runner alternative to `make`. Instead of `make roles`, you can now run `just roles` to accomplish the same.
In addition, we've added support for running commands via [just](https://github.com/casey/just) - a more modern command-runner alternative to `make`. Instead of `make roles`, you can now run `just roles` to accomplish the same.
Our [justfile](justfile) already defines some additional helpful **shortcut** commands that weren't part of our `Makefile`. Here are some examples:
- `just install-all` to trigger the much longer `ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start` command
- `just install-all --ask-vault-pass` — commands also support additional arguments (`--ask-vault-pass` will be appended to the above installation command)
- `just run-tags install-mautrix-slack,start` — to run specific playbook tags
- `just start-all` — (re-)starts all services
- `just stop-group postgres` — to stop only the Postgres service
- `just register-user alice secret-password yes` — registers an `alice` user with the `secret-password` password and admin access (admin = `yes`)
- `just install-all --ask-vault-pass` - commands also support additional arguments (`--ask-vault-pass` will be appended to the above installation command)
- `just run-tags install-mautrix-slack,start` - to run specific playbook tags
- `just start-all` - (re-)starts all services
- `just stop-group postgres` - to stop only the Postgres service
- `just register-user alice secret-password yes` - registers an `alice` user with the `secret-password` password and admin access (admin = `yes`)
Additional helpful commands and shortcuts may be defined in the future.
@ -1539,7 +1335,7 @@ Thanks to [Cody Neiman](https://github.com/xangelix)'s efforts, the playbook now
## ChatGPT support
Thanks to [@bertybuttface](https://github.com/bertybuttface), the playbook can now help you set up [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) — a bot through which you can talk to the [ChatGPT](https://openai.com/blog/chatgpt/) model.
Thanks to [@bertybuttface](https://github.com/bertybuttface), the playbook can now help you set up [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) - a bot through which you can talk to the [ChatGPT](https://openai.com/blog/chatgpt/) model.
See our [Setting up matrix-bot-chatgpt](docs/configuring-playbook-bot-chatgpt.md) documentation to get started.
@ -1548,7 +1344,7 @@ See our [Setting up matrix-bot-chatgpt](docs/configuring-playbook-bot-chatgpt.md
## matrix-postgres-backup has been replaced by the ansible-role-postgres-backup external role
Just like we've [replaced Postgres with an external role](#matrix-postgres-has-been-replaced-by-the-comdevtureansiblerolepostgres-external-role) on 2022-11-28, we're now replacing `matrix-postgres-backup` with an external role — [com.devture.ansible.role.postgres_backup](https://github.com/mother-of-all-self-hosting/ansible-role-postgres_backup).
Just like we've [replaced Postgres with an external role](#matrix-postgres-has-been-replaced-by-the-comdevtureansiblerolepostgres-external-role) on 2022-11-28, we're now replacing `matrix-postgres-backup` with an external role - [com.devture.ansible.role.postgres_backup](https://github.com/mother-of-all-self-hosting/ansible-role-postgres_backup).
You'll need to rename your `matrix_postgres_backup`-prefixed variables such that they use a `postgres_backup` prefix.
@ -1557,7 +1353,7 @@ You'll need to rename your `matrix_postgres_backup`-prefixed variables such that
## matrix-postgres has been replaced by the ansible-role-postgres external role
**TLDR**: the tasks that install the integrated Postgres server now live in an external role — [ansible-role-postgres](https://github.com/mother-of-all-self-hosting/ansible-role-postgres). You'll need to run `make roles` to install it, and to also rename your `matrix_postgres`-prefixed variables to use a `devture_postgres` prefix (e.g. `matrix_postgres_connection_password` -> `postgres_connection_password`). All your data will still be there! Some scripts have moved (`/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`).
**TLDR**: the tasks that install the integrated Postgres server now live in an external role - [ansible-role-postgres](https://github.com/mother-of-all-self-hosting/ansible-role-postgres). You'll need to run `make roles` to install it, and to also rename your `matrix_postgres`-prefixed variables to use a `devture_postgres` prefix (e.g. `matrix_postgres_connection_password` -> `postgres_connection_password`). All your data will still be there! Some scripts have moved (`/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`).
The `matrix-postgres` role that has been part of the playbook for a long time has been replaced with the [ansible-role-postgres](https://github.com/mother-of-all-self-hosting/ansible-role-postgres) role. This was done as part of our work to [use external roles for some things](#the-playbook-now-uses-external-roles-for-some-things) for better code re-use and maintainability.
@ -1568,7 +1364,7 @@ The new role is an upgraded version of the old `matrix-postgres` role with these
You'll need to run `make roles` to install the new role. You would also need to rename your `matrix_postgres`-prefixed variables to use a `devture_postgres` prefix.
Note: the systemd service still remains the same — `matrix-postgres.service`. Your data will still be in `/matrix/postgres`, etc. Postgres-related scripts will be moved to `/matrix/postgres/bin` (`/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`, etc). Also see [The playbook no longer installs scripts in /usr/local/bin](#the-playbook-no-longer-installs-scripts-in-usrlocalbin).
Note: the systemd service still remains the same - `matrix-postgres.service`. Your data will still be in `/matrix/postgres`, etc. Postgres-related scripts will be moved to `/matrix/postgres/bin` (`/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`, etc). Also see [The playbook no longer installs scripts in /usr/local/bin](#the-playbook-no-longer-installs-scripts-in-usrlocalbin).
## The playbook no longer installs scripts to /usr/local/bin
@ -1619,20 +1415,20 @@ The Docker SDK for Python (named `docker-python`, `python-docker`, etc. on the d
If you're hitting issues with Docker installation or Docker SDK for Python installation, consider reporting bugs or contributing to these other projects.
These additional roles are downloaded into the playbook directory (to `roles/galaxy`) via an `ansible-galaxy …` command. `make roles` is an easy shortcut for invoking the `ansible-galaxy` command to download these roles.
These additional roles are downloaded into the playbook directory (to `roles/galaxy`) via an `ansible-galaxy ..` command. `make roles` is an easy shortcut for invoking the `ansible-galaxy` command to download these roles.
# 2022-11-20
## (Backward Compatibility Break) Changing how reverse-proxying to Synapse works — now via a `matrix-synapse-reverse-proxy-companion` service
## (Backward Compatibility Break) Changing how reverse-proxying to Synapse works - now via a `matrix-synapse-reverse-proxy-companion` service
**TLDR**: There's now a `matrix-synapse-reverse-proxy-companion` nginx service, which helps with reverse-proxying to Synapse and its various worker processes (if workers are enabled), so that `matrix-nginx-proxy` can be relieved of this role. `matrix-nginx-proxy` still remains as the public SSL-terminating reverse-proxy in the playbook. `matrix-synapse-reverse-proxy-companion` is just one more reverse-proxy thrown into the mix for convenience. People with a more custom reverse-proxying configuration may be affected — see [Webserver configuration](#webserver-configuration) below.
**TLDR**: There's now a `matrix-synapse-reverse-proxy-companion` nginx service, which helps with reverse-proxying to Synapse and its various worker processes (if workers are enabled), so that `matrix-nginx-proxy` can be relieved of this role. `matrix-nginx-proxy` still remains as the public SSL-terminating reverse-proxy in the playbook. `matrix-synapse-reverse-proxy-companion` is just one more reverse-proxy thrown into the mix for convenience. People with a more custom reverse-proxying configuration may be affected - see [Webserver configuration](#webserver-configuration) below.
### Background
Previously, `matrix-nginx-proxy` forwarded requests to Synapse directly. When Synapse is running in worker mode, the reverse-proxying configuration is more complicated (different requests need to go to different Synapse worker processes). `matrix-nginx-proxy` had configuration for sending each URL endpoint to the correct Synapse worker responsible for handling it. However, sometimes people like to disable `matrix-nginx-proxy` (for whatever reason) as detailed in [Using your own webserver, instead of this playbook's nginx proxy](docs/configuring-playbook-own-webserver.md).
Because `matrix-nginx-proxy` was so central to request forwarding, when it was disabled and Synapse was running with workers enabled, there was nothing which could forward requests to the correct place anymore… which caused [problems such as this one affecting Dimension](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2090).
Because `matrix-nginx-proxy` was so central to request forwarding, when it was disabled and Synapse was running with workers enabled, there was nothing which could forward requests to the correct place anymore.. which caused [problems such as this one affecting Dimension](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2090).
### Solution
@ -1644,7 +1440,7 @@ From now on, `matrix-nginx-proxy` is relieved of its function of reverse-proxyin
- `matrix-synapse-reverse-proxy-companion:8008` for Synapse Client-Server API traffic
- `matrix-synapse-reverse-proxy-companion:8048` for Synapse Server-Server (Federation) API traffic
- simplify `matrix-nginx-proxy` configuration — it now only needs to send requests to `matrix-synapse-reverse-proxy-companion` or `matrix-dendrite`, etc., without having to worry about workers
- simplify `matrix-nginx-proxy` configuration - it now only needs to send requests to `matrix-synapse-reverse-proxy-companion` or `matrix-dendrite`, etc., without having to worry about workers
- allow reverse-proxying to Synapse, even if `matrix-nginx-proxy` is disabled
@ -1660,7 +1456,7 @@ Various services (like Dimension, etc.) still talk to Synapse via `matrix-nginx-
- if you're using your own `nginx` webserver running on the server, you shouldn't be affected. The `/matrix/nginx/conf.d` configuration and exposed ports that you're relying on will automatically be updated in a way that should work
- if you're using another local webserver (e.g. Apache, etc.) and haven't changed any ports (`matrix_*_host_bind_port` definitions), you shouldn't be affected. You're likely sending Matrix traffic to `127.0.0.1:8008` and `127.0.0.1:8048`. These ports (`8008` and `8048`) will still be exposed on `127.0.0.1` by default — just not by the `matrix-synapse` container from now on, but by the `matrix-synapse-reverse-proxy-companion` container instead
- if you're using another local webserver (e.g. Apache, etc.) and haven't changed any ports (`matrix_*_host_bind_port` definitions), you shouldn't be affected. You're likely sending Matrix traffic to `127.0.0.1:8008` and `127.0.0.1:8048`. These ports (`8008` and `8048`) will still be exposed on `127.0.0.1` by default - just not by the `matrix-synapse` container from now on, but by the `matrix-synapse-reverse-proxy-companion` container instead
- if you've been exposing `matrix-synapse` ports (`matrix_synapse_container_client_api_host_bind_port`, etc.) manually, you should consider exposing `matrix-synapse-reverse-proxy-companion` ports instead
@ -1696,7 +1492,7 @@ Starting now, the playbook is composed of 2 types of Ansible roles:
- those downloaded from other sources (using [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to `roles/galaxy`, based on the [`requirements.yml` file](requirements.yml)). These roles are maintained by us or by other people from the Ansible community.
We're doing this for greater code-reuse (across Ansible playbooks, including our own related playbooks [gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy) and [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy)) and decreased maintenance burden. Until now, certain features were copy-pasted across playbooks or were maintained separately in each one, with improvements often falling behind. We've also tended to do too much by ourselves — installing Docker on the server from our `matrix-base` role, etc. — something that we'd rather not do anymore by switching to the [geerlingguy.docker](https://galaxy.ansible.com/geerlingguy/docker) role.
We're doing this for greater code-reuse (across Ansible playbooks, including our own related playbooks [gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy) and [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy)) and decreased maintenance burden. Until now, certain features were copy-pasted across playbooks or were maintained separately in each one, with improvements often falling behind. We've also tended to do too much by ourselves - installing Docker on the server from our `matrix-base` role, etc. - something that we'd rather not do anymore by switching to the [geerlingguy.docker](https://galaxy.ansible.com/geerlingguy/docker) role.
Some variable names will change during the transition to having more and more external (galaxy) roles. There's a new `custom/matrix_playbook_migration` role added to the playbook which will tell you about these changes each time you run the playbook.
@ -1709,7 +1505,7 @@ Some variable names will change during the transition to having more and more ex
**`synapse-s3-storage-provider` support is very new and still relatively untested. Using it may cause data loss.**
You can now store your Synapse media repository files on Amazon S3 (or another S3-compatible object store) using [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) — a media provider for Synapse (Python module), which should work faster and more reliably than our previous [Goofys](docs/configuring-playbook-s3-goofys.md) implementation (Goofys will continue to work).
You can now store your Synapse media repository files on Amazon S3 (or another S3-compatible object store) using [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) - a media provider for Synapse (Python module), which should work faster and more reliably than our previous [Goofys](docs/configuring-playbook-s3-goofys.md) implementation (Goofys will continue to work).
This is not just for initial installations. Users with existing files (stored in the local filesystem) can also migrate their files to `synapse-s3-storage-provider`.
@ -1741,7 +1537,7 @@ With the new Synapse-customization feature in the playbook, we use the original
## matrix-ldap-registration-proxy support
Thanks to [@TheOneWithTheBraid](https://github.com/TheOneWithTheBraid), we now support installing [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) — a proxy which handles Matrix registration requests and forwards them to LDAP.
Thanks to [@TheOneWithTheBraid](https://github.com/TheOneWithTheBraid), we now support installing [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) - a proxy which handles Matrix registration requests and forwards them to LDAP.
See our [Setting up matrix-ldap-registration-proxy](docs/configuring-playbook-matrix-ldap-registration-proxy.md) documentation to get started.
@ -1833,7 +1629,7 @@ Below we'll discuss **potential backward incompatibilities**.
## Cactus Comments support
Thanks to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s), the playbook can now set up [Cactus Comments](https://cactus.chat) — federated comment system for the web based on Matrix.
Thanks to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s), the playbook can now set up [Cactus Comments](https://cactus.chat) - federated comment system for the web based on Matrix.
See our [Setting up Cactus Comments](docs/configuring-playbook-cactus-comments.md) documentation to get started.
@ -1842,7 +1638,7 @@ See our [Setting up Cactus Comments](docs/configuring-playbook-cactus-comments.m
## Postmoogle email bridge support
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up the new [Postmoogle](https://github.com/etkecc/postmoogle) email bridge. Postmoogle is like the [Email2Matrix bridge](https://github.com/devture/email2matrix) (also [already supported by the playbook](docs/configuring-playbook-email2matrix.md)), but more capable and with the intention to soon support *sending* emails, not just receiving.
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up the new [Postmoogle](https://github.com/etkecc/postmoogle) email bridge. Postmoogle is like the [email2matrix bridge](https://github.com/devture/email2matrix) (also [already supported by the playbook](docs/configuring-playbook-email2matrix.md)), but more capable and with the intention to soon support *sending* emails, not just receiving.
See our [Setting up Postmoogle email bridging](docs/configuring-playbook-bridge-postmoogle.md) documentation to get started.
@ -1888,7 +1684,7 @@ Thanks to [MdotAmaan](https://github.com/MdotAmaan)'s efforts, the playbook now
## matrix-appservice-kakaotalk support
The playbook now supports bridging to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) via [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) — a bridge based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code. Thanks to [hnarjis](https://github.com/hnarjis) for helping us add support for this!
The playbook now supports bridging to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) via [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) - a bridge based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code. Thanks to [hnarjis](https://github.com/hnarjis) for helping us add support for this!
See our [Setting up Appservice Kakaotalk bridging](docs/configuring-playbook-bridge-appservice-kakaotalk.md) documentation to get started.
@ -1897,7 +1693,7 @@ See our [Setting up Appservice Kakaotalk bridging](docs/configuring-playbook-bri
## maubot support
Thanks to [Stuart Mumford (@Cadair)](https://github.com/cadair) for starting ([PR #373](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/373) and [PR #622](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/622)) and to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s) for finishing up (in [PR #1894](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1894)), the playbook can now help you set up [maubot](https://github.com/maubot/maubot) — a plugin-based Matrix bot system.
Thanks to [Stuart Mumford (@Cadair)](https://github.com/cadair) for starting ([PR #373](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/373) and [PR #622](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/622)) and to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s) for finishing up (in [PR #1894](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1894)), the playbook can now help you set up [maubot](https://github.com/maubot/maubot) - a plugin-based Matrix bot system.
See our [Setting up maubot](docs/configuring-playbook-bot-maubot.md) documentation to get started.
@ -1961,7 +1757,7 @@ See our [Setting up the ntfy push notifications server](docs/configuring-playboo
**If you're using node-exporter** (`matrix_prometheus_node_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_node_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.example.com/metrics/node-exporter`.
**If you're using [postgres-exporter](docs/configuring-playbook-prometheus-grafana.md#enable-metrics-and-graphs-for-postgres-optional)** (`prometheus_postgres_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_services_proxy_connect_prometheus_postgres_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.example.com/metrics/postgres-exporter`.
**If you're using [postgres-exporter](docs/configuring-playbook-prometheus-postgres.md)** (`prometheus_postgres_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_services_proxy_connect_prometheus_postgres_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.example.com/metrics/postgres-exporter`.
**If you're using Synapse** and would like to collect its metrics from an external Prometheus server, you may find that:
@ -2038,7 +1834,7 @@ See our [Setting up Buscarron](docs/configuring-playbook-bot-buscarron.md) docum
## matrix-registration-bot support
Thanks to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s), the playbook can now help you set up [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) — a bot that is used to create and manage registration tokens for a Matrix server.
Thanks to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s), the playbook can now help you set up [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) - a bot that is used to create and manage registration tokens for a Matrix server.
See our [Setting up matrix-registration-bot](docs/configuring-playbook-bot-matrix-registration-bot.md) documentation to get started.
@ -2080,7 +1876,7 @@ When self-building, the playbook used to `git clone` repositories (into `/matrix
If you're on a non-`amd64` architecture (that is, you're overriding `matrix_architecture` in your `vars.yml` file) or you have enabled self-building for some service (e.g. `matrix_*_self_build: true`), you're certainly building some container images from source and have `docker-src` directories with mixed permissions lying around in various `/matrix/SERVICE` directories.
The playbook *could* correct these permissions automatically, but that requires additional Ansible tasks in some ~45 different places — something that takes considerable effort. So we ask users observing errors related to `docker-src` directories to correct the problem manually by **running this command on the Matrix server** (which deletes all `/matrix/*/docker-src` directories): `find /matrix -maxdepth 2 -name 'docker-src' | xargs rm -rf`
The playbook *could* correct these permissions automatically, but that requires additional Ansible tasks in some ~45 different places - something that takes considerable effort. So we ask users observing errors related to `docker-src` directories to correct the problem manually by **running this command on the Matrix server** (which deletes all `/matrix/*/docker-src` directories): `find /matrix -maxdepth 2 -name 'docker-src' | xargs rm -rf`
# 2022-03-17
@ -2167,7 +1963,7 @@ We're excited to gain support for other homeserver implementations, like [Condui
## Honoroit bot support
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now help you set up [Honoroit](https://github.com/etkecc/honoroit) — a helpdesk bot.
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now help you set up [Honoroit](https://github.com/etkecc/honoroit) - a helpdesk bot.
See our [Setting up Honoroit](docs/configuring-playbook-bot-honoroit.md) documentation to get started.
@ -2176,7 +1972,7 @@ See our [Setting up Honoroit](docs/configuring-playbook-bot-honoroit.md) documen
## Cinny support
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook now supports [Cinny](https://cinny.in/) — a new simple, elegant and secure Matrix client.
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook now supports [Cinny](https://cinny.in/) - a new simple, elegant and secure Matrix client.
By default, we still install Element Web. Still, people who'd like to try Cinny out can now install it via the playbook.
@ -2230,7 +2026,7 @@ To get started with bridging to LinkedIn, see [Setting up Beeper LinkedIn bridgi
# 2021-08-20
# Sygnal upgraded — ARM support and no longer requires a database
# Sygnal upgraded - ARM support and no longer requires a database
The [Sygnal](docs/configuring-playbook-sygnal.md) push gateway has been upgraded from `v0.9.0` to `v0.10.1`.
@ -2245,7 +2041,7 @@ The new version is also available for the ARM architecture. It also no longer re
## Hydrogen support
Thanks to [Aaron Raimist](https://github.com/aaronraimist), the playbook now supports [Hydrogen](https://github.com/vector-im/hydrogen-web) — a new lightweight Matrix client with legacy and mobile browser support.
Thanks to [Aaron Raimist](https://github.com/aaronraimist), the playbook now supports [Hydrogen](https://github.com/vector-im/hydrogen-web) - a new lightweight Matrix client with legacy and mobile browser support.
By default, we still install Element Web, as Hydrogen is still not fully-featured. Still, people who'd like to try Hydrogen out can now install it via the playbook.
@ -2263,9 +2059,9 @@ Additional details are available in [Setting up Heisenbridge bouncer-style IRC b
# 2021-04-16
## Disabling TLSv1 and TLSv1.1 for coturn
## Disabling TLSv1 and TLSv1.1 for Coturn
To improve security, we've [removed TLSv1 and TLSv1.1 support](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/999) from our default [coturn](https://github.com/coturn/coturn) configuration.
To improve security, we've [removed TLSv1 and TLSv1.1 support](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/999) from our default [Coturn](https://github.com/coturn/coturn) configuration.
If you need to support old clients, you can re-enable both (or whichever one you need) with the following configuration:
@ -2281,7 +2077,7 @@ matrix_coturn_tls_v1_1_enabled: true
Thanks to [foxcris](https://github.com/foxcris), the playbook can now make automated local Postgres backups on a fixed schedule using [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local).
Additional details are available in [Setting up Postgres backup](docs/configuring-playbook-postgres-backup.md).
Additional details are available in [Setting up postgres backup](docs/configuring-playbook-postgres-backup.md).
# 2021-04-03
@ -2335,7 +2131,7 @@ After [lots and lots of work](https://github.com/spantaleev/matrix-docker-ansibl
Having support for workers makes the playbook suitable for larger homeserver deployments.
Our setup is not yet perfect (we don't support all types of workers; scaling some of them (like `pusher`, `federation_sender`) beyond a single instance is not yet supported). Still, it's a great start and can already power homeservers with thousands of users, like the [Matrix deployment at TU Dresden](https://doc.matrix.tu-dresden.de/en/) discussed in [Matrix Live S06E09 — TU Dresden on their Matrix deployment](https://www.youtube.com/watch?v=UHJX2pmT2gk).
Our setup is not yet perfect (we don't support all types of workers; scaling some of them (like `pusher`, `federation_sender`) beyond a single instance is not yet supported). Still, it's a great start and can already power homeservers with thousands of users, like the [Matrix deployment at TU Dresden](https://doc.matrix.tu-dresden.de/en/) discussed in [Matrix Live S06E09 - TU Dresden on their Matrix deployment](https://www.youtube.com/watch?v=UHJX2pmT2gk).
By default, workers are disabled and Synapse runs as a single process (homeservers don't necessarily need the complexity and increased memory requirements of running a worker-based setup).
@ -2403,7 +2199,7 @@ To migrate to the new setup, expect a few minutes of downtime, while you follow
matrix_postgres_connection_password: 'YOUR_POSTGRES_PASSWORD_HERE'
```
… where `YOUR_POSTGRES_PASSWORD_HERE` is to be replaced with the password you generated during step #2.
.. where `YOUR_POSTGRES_PASSWORD_HERE` is to be replaced with the password you generated during step #2.
4. Stop all services: `ansible-playbook -i inventory/hosts setup.yml --tags=stop`
5. Log in to the server via SSH. The next commands will be performed there.
@ -2415,7 +2211,7 @@ To migrate to the new setup, expect a few minutes of downtime, while you follow
CREATE ROLE matrix LOGIN SUPERUSER PASSWORD 'YOUR_POSTGRES_PASSWORD_HERE';
```
… where `YOUR_POSTGRES_PASSWORD_HERE` is to be replaced with the password you generated during step #2.
.. where `YOUR_POSTGRES_PASSWORD_HERE` is to be replaced with the password you generated during step #2.
9. Execute the following queries as you see them (no modifications necessary, so you can just **paste them all at once**):
@ -2486,7 +2282,7 @@ You have 3 ways to proceed:
- stop the bridge (`systemctl stop matrix-mautrix-facebook`)
- create a new `matrix_mautrix_facebook` Postgres database for it
- run [pgloader](https://pgloader.io/) manually (we import this bridge's data using default settings and it works well)
- define `matrix_mautrix_facebook_database_*` variables in your `vars.yml` file (credentials, etc.) — you can find their defaults in `roles/custom/matrix-mautrix-facebook/defaults/main.yml`
- define `matrix_mautrix_facebook_database_*` variables in your `vars.yml` file (credentials, etc.) - you can find their defaults in `roles/custom/matrix-mautrix-facebook/defaults/main.yml`
- switch the bridge to Postgres (`matrix_mautrix_facebook_database_engine: 'postgres'` in your `vars.yml` file)
- re-run the playbook (`--tags=setup-all,start`) and ensure the bridge works (`systemctl status matrix-mautrix-facebook` and `journalctl -fu matrix-mautrix-facebook`)
- send a `login` message to the Facebook bridge bot again
@ -2575,7 +2371,7 @@ Moving all services to Postgres brings a few **benefits** to us:
- **improved performance**
- **improved compatibility**. Most bridges are deprecating SQLite/nedb support or offer less features when not on Postgres.
- **easier backups**. It's still some effort to take a proper backup (Postgres dump + various files, keys), but a Postgres dump now takes you much further.
- we're now **more prepared to introduce other services** that need a Postgres database — [Dendrite](https://github.com/matrix-org/dendrite), the [mautrix-signal](https://github.com/tulir/mautrix-signal) bridge (existing [pull request](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/686)), etc.
- we're now **more prepared to introduce other services** that need a Postgres database - [Dendrite](https://github.com/matrix-org/dendrite), the [mautrix-signal](https://github.com/tulir/mautrix-signal) bridge (existing [pull request](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/686)), etc.
### Key takeway
@ -2725,7 +2521,7 @@ If you have have an existing setup, it's likely running on an older Postgres ver
## matrix-registration support
The playbook can now help you set up [matrix-registration](https://github.com/ZerataX/matrix-registration) — an application that lets you keep your Matrix server's registration private, but still allow certain users (those having a unique registration link) to register by themselves.
The playbook can now help you set up [matrix-registration](https://github.com/ZerataX/matrix-registration) - an application that lets you keep your Matrix server's registration private, but still allow certain users (those having a unique registration link) to register by themselves.
See our [Setting up matrix-registration](docs/configuring-playbook-matrix-registration.md) documentation page to get started.
@ -2828,7 +2624,7 @@ See our [Setting up Matrix SMS bridging](docs/configuring-playbook-bridge-matrix
User Directory search requests used to go to the ma1sd identity server by default, which queried its own stores and the Synapse database.
ma1sd current has [a security issue](https://github.com/ma1uta/ma1sd/issues/44), which made it leak information about all users — including users created by bridges, etc.
ma1sd current has [a security issue](https://github.com/ma1uta/ma1sd/issues/44), which made it leak information about all users - including users created by bridges, etc.
Until the issue gets fixed, we're making User Directory search not go to ma1sd by default. You **need to re-run the playbook and restart services to apply this workaround**.
@ -2839,12 +2635,12 @@ Until the issue gets fixed, we're making User Directory search not go to ma1sd b
## Newer IRC bridge (with potential breaking change)
This upgrades matrix-appservice-irc from 0.14.1 to 0.16.0. Upstream
made a change to how you define manual mappings. If you added a
This upgrades matrix-appservice-irc from 0.14.1 to 0.16.0. Upstream
made a change to how you define manual mappings. If you added a
`mapping` to your configuration, you will need to update it accoring
to the [upstream
instructions](https://github.com/matrix-org/matrix-appservice-irc/blob/master/CHANGELOG.md#0150-2020-02-05). If you did not include `mappings` in your configuration for IRC, no
change is necessary. `mappings` is not part of the default
change is necessary. `mappings` is not part of the default
configuration.
@ -2883,7 +2679,7 @@ To make your Jitsi server more private, see the [configure internal Jitsi authen
Thanks to [Marcel Partap](https://github.com/eMPee584)'s efforts, the [mxisd](https://github.com/kamax-io/mxisd) identity server, which has been deprecated for a long time, has finally been replaced by [ma1sd](https://github.com/ma1uta/ma1sd), a compatible fork.
**If you're using the default playbook configuration**, you don't need to do anything — your mxisd installation will be replaced with ma1sd and all existing data will be migrated automatically the next time you run the playbook.
**If you're using the default playbook configuration**, you don't need to do anything -- your mxisd installation will be replaced with ma1sd and all existing data will be migrated automatically the next time you run the playbook.
**If you're doing something more special** (defining custom `matrix_mxisd_*` variables), the playbook will ask you to rename them to `matrix_ma1sd_*`. You're also encouraged to test that ma1sd works well for such a more custom setup.
@ -2980,7 +2776,7 @@ Learn more in [Setting up Appservice Webhooks bridging](docs/configuring-playboo
Double Puppeting can now be easily enabled for all Mautrix bridges supported by the playbook (Facebook, Hangouts, Whatsapp, Telegram).
This is possible due to those bridges' integration with [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) — yet another component that this playbook can install for you.
This is possible due to those bridges' integration with [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) - yet another component that this playbook can install for you.
To get started, following the playbook's documentation for the bridge you'd like to configure.
@ -3234,10 +3030,10 @@ Likewise, data is now also stored in a subdirectory (`/matrix/mautrix-telegram/d
Also, we're now following the default configuration for the Telegram bridge, so some default configuration values are different:
- `edits_as_replies` (used to be `false`, now `true`) — previously replies were not sent over to Matrix at all; ow they are sent over as a reply to the original message
- `inline_images` (used to be `true`, now `false`) — this has to do with captioned images. Inline-image (included caption) are said to exhibit troubles on Riot iOS. When `false`, the caption arrives on the Matrix side as a separate message.
- `authless_portals` (used to be `false`, now `true`) — creating portals from the Telegram side is now possible
- `whitelist_group_admins` (used to be `false`, now `true`) — allows Telegram group admins to use the bot commands
- `edits_as_replies` (used to be `false`, now `true`) - previously replies were not sent over to Matrix at all; ow they are sent over as a reply to the original message
- `inline_images` (used to be `true`, now `false`) - this has to do with captioned images. Inline-image (included caption) are said to exhibit troubles on Riot iOS. When `false`, the caption arrives on the Matrix side as a separate message.
- `authless_portals` (used to be `false`, now `true`) - creating portals from the Telegram side is now possible
- `whitelist_group_admins` (used to be `false`, now `true`) - allows Telegram group admins to use the bot commands
If the new values are not to your liking, use `matrix_mautrix_telegram_configuration_extension_yaml` to specify an override (refer to `matrix_mautrix_telegram_configuration_yaml` to figure out which variable goes where).
@ -3278,7 +3074,7 @@ Likewise, data is now also stored in a subdirectory (`/matrix/mautrix-facebook/d
Until now, various roles supported a `matrix_*_expose_port` variable, which would expose their container's port to the host. This was mostly useful for reverse-proxying manually (in case `matrix-nginx-proxy` was disabled). It could also be used for installing some playbook services (e.g. bridges, etc.) and wiring them to a separate (manual) Matrix setup.
`matrix_*_expose_port` variables were not granular enough — sometimes they would expose one port, other times multiple. They also didn't provide control over **where** to expose (to which port number and to which network interface), because they would usually hardcode something like `127.0.0.1:8080`.
`matrix_*_expose_port` variables were not granular enough - sometimes they would expose one port, other times multiple. They also didn't provide control over **where** to expose (to which port number and to which network interface), because they would usually hardcode something like `127.0.0.1:8080`.
All such variables have been superseded by a better (more flexible) way to do it.
@ -3388,11 +3184,11 @@ We've also started building our own Docker image of Ansible ([devture/ansible](h
# 2019-03-19
## TLS support for coturn
## TLS support for Coturn
We've added TLS support to the coturn TURN server installed by the playbook by default. The certificates from the Matrix domain will be used for the coturn server.
We've added TLS support to the Coturn TURN server installed by the playbook by default. The certificates from the Matrix domain will be used for the Coturn server.
This feature is enabled by default for new installations. To make use of TLS support for your existing Matrix server's coturn, make sure to rebuild both coturn and Synapse:
This feature is enabled by default for new installations. To make use of TLS support for your existing Matrix server's Coturn, make sure to rebuild both Coturn and Synapse:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-coturn,setup-synapse,start
@ -3402,9 +3198,9 @@ People who have an extra firewall (besides the iptables firewall, which Docker m
People who build their own custom playbook from our roles should be aware that:
- the `matrix-coturn` role and actually starting coturn (e.g. `--tags=start`), requires that certificates are already put in place. For this reason, it's usually a good idea to have the `matrix-coturn` role execute after `matrix-nginx-proxy` (which retrieves the certificates).
- the `matrix-coturn` role and actually starting Coturn (e.g. `--tags=start`), requires that certificates are already put in place. For this reason, it's usually a good idea to have the `matrix-coturn` role execute after `matrix-nginx-proxy` (which retrieves the certificates).
- there are a few variables that can help you enable TLS support for coturn. See the `matrix-coturn` section in [group_vars/matrix-servers](./group_vars/matrix-servers).
- there are a few variables that can help you enable TLS support for Coturn. See the `matrix-coturn` section in [group_vars/matrix-servers](./group_vars/matrix-servers).
# 2019-03-12
@ -3486,11 +3282,11 @@ Matrix is undergoing a lot of changes as it matures towards Synapse v1.0. The fi
If you've been using this playbook successfully until now, you'd be aware that we've been doing [Server Delegation](docs/howto-server-delegation.md) using a `_matrix._tcp` DNS SRV record (as per [Configuring DNS](docs/configuring-dns.md)).
Due to changes related to certificate file requirements that will affect us at Synapse v1.0, we'll have to stop using a **`_matrix._tcp` DNS SRV record in the future** (when Synapse goes to v1.0 — around 5th of March 2019). We **still need to keep the SRV record for now**, for backward compatibility with older Synapse versions (lower than v0.99).
Due to changes related to certificate file requirements that will affect us at Synapse v1.0, we'll have to stop using a **`_matrix._tcp` DNS SRV record in the future** (when Synapse goes to v1.0 - around 5th of March 2019). We **still need to keep the SRV record for now**, for backward compatibility with older Synapse versions (lower than v0.99).
**What you need to do now** is make use of this transitional Synapse v0.99 release to **prepare your federation settings for the future**. You have 2 choices to prepare yourself for compatibility with the future Synapse v1.0:
- (recommended) set up [Server Delegation via a well-known file](docs/howto-server-delegation.md#server-delegation-via-a-well-known-file), unless you are affected by the [Downsides of well-known-based Server Delegation](docs/howto-server-delegation.md#downsides-of-well-known-based-server-delegation). If you had previously set up the well-known `client` file, depending on how you've done it, it may be that there is nothing new required of you (besides [upgrading](docs/maintenance-upgrading-services.md)). After upgrading, you can [run a self-check](docs/maintenance-and-troubleshooting.md#how-to-check-if-services-work), which will tell you if you need to do anything extra with regard to setting up [Server Delegation via a well-known file](docs/howto-server-delegation.md#server-delegation-via-a-well-known-file). After some time, when most people have upgraded to Synapse v0.99 and older releases have disappeared, be prepared to drop your `_matrix._tcp` SRV record.
- (recommended) set up [Server Delegation via a well-known file](docs/howto-server-delegation.md#server-delegation-via-a-well-known-file), unless you are affected by the [Downsides of well-known-based Server Delegation](docs/howto-server-delegation.md#downsides-of-well-known-based-server-delegation). If you had previously set up the well-known `client` file, depending on how you've done it, it may be that there is nothing new required of you (besides [upgrading](docs/maintenance-upgrading-services.md)). After upgrading, you can [run a self-check](docs/maintenance-checking-services.md), which will tell you if you need to do anything extra with regard to setting up [Server Delegation via a well-known file](docs/howto-server-delegation.md#server-delegation-via-a-well-known-file). After some time, when most people have upgraded to Synapse v0.99 and older releases have disappeared, be prepared to drop your `_matrix._tcp` SRV record.
- (more advanced) if the [Downsides of well-known-based Server Delegation](docs/howto-server-delegation.md#downsides-of-well-known-based-server-delegation) are not to your liking, **as an alternative**, you can set up [Server Delegation via a DNS SRV record](docs/howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced). In such a case, you get to keep using your existing `_matrix._tcp` DNS SRV record forever and need to NOT set up a `/.well-known/matrix/server` file. Don't forget that you need to do certificate changes though. Follow the guide at [Server Delegation via a DNS SRV record](docs/howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced).
@ -3521,7 +3317,7 @@ When using:
## Running container processes as non-root, without capabilities and read-only
To improve security, this playbook no longer starts container processes as the `root` user. Most containers were dropping privileges anyway, but we were trusting them with `root` privileges until they would do that. Not anymore — container processes now start as a non-root user (usually `matrix`) from the get-go.
To improve security, this playbook no longer starts container processes as the `root` user. Most containers were dropping privileges anyway, but we were trusting them with `root` privileges until they would do that. Not anymore -- container processes now start as a non-root user (usually `matrix`) from the get-go.
For additional security, various capabilities are also dropped (see [why it's important](https://github.com/projectatomic/atomic-site/issues/203)) for all containers.
@ -3542,7 +3338,7 @@ Using the [devture/exim-relay](https://hub.docker.com/r/devture/exim-relay) cont
## (BC Break) Making the playbook's roles more independent of one another
The following change **affects people running a more non-standard setup** — external Postgres or using our roles in their own other playbook.
The following change **affects people running a more non-standard setup** - external Postgres or using our roles in their own other playbook.
**Most users don't need to do anything**, besides becoming aware of the new glue variables file [`group_vars/matrix-servers`](group_vars/matrix-servers).
Because people like using the playbook's components independently (outside of this playbook) and because it's much better for maintainability, we've continued working on separating them. Still, we'd like to offer a turnkey solution for running a fully-featured Matrix server, so this playbook remains important for wiring up the various components.
@ -3807,14 +3603,14 @@ From now on, Riot's configuration setting `disable_guests` would be set to `true
## Self-check maintenance command
The playbook can now [check if services are configured correctly](docs/maintenance-and-troubleshooting.md#how-to-check-if-services-work).
The playbook can now [check if services are configured correctly](docs/maintenance-checking-services.md).
# 2018-10-05
## Presence tracking made configurable
The playbook can now enable/disable user presence-status tracking in Synapse, through the playbook's `matrix_synapse_use_presence` variable (having a default value of `true` — enabled).
The playbook can now enable/disable user presence-status tracking in Synapse, through the playbook's `matrix_synapse_use_presence` variable (having a default value of `true` - enabled).
If users participate in large rooms with many other servers, disabling presence will decrease server load significantly.
@ -3834,7 +3630,7 @@ Changing that value allows you to potentially decrease RAM usage or to increase
`--log-driver=none` is used for all Docker containers now.
All these containers are started through systemd anyway and get logged in journald, so there's no need for Docker to be logging the same thing using the default `json-file` driver. Doing that was growing `/var/lib/docker/containers/…` infinitely until service/container restart.
All these containers are started through systemd anyway and get logged in journald, so there's no need for Docker to be logging the same thing using the default `json-file` driver. Doing that was growing `/var/lib/docker/containers/..` infinitely until service/container restart.
As a result of this, things like `docker logs matrix-synapse` won't work anymore. `journalctl -u matrix-synapse` is how one can see the logs.

14
CHANGELOG.md.license
View File

@ -1,14 +0,0 @@
SPDX-FileCopyrightText: 2018 - 2024 MDAD project contributors
SPDX-FileCopyrightText: 2018 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2018 Aaron Raimist
SPDX-FileCopyrightText: 2019 Thomas Kuehne
SPDX-FileCopyrightText: 2020 John Goerzen
SPDX-FileCopyrightText: 2020 Julian Foad
SPDX-FileCopyrightText: 2021 Agustin Ferrario
SPDX-FileCopyrightText: 2021 Dan Arnfield
SPDX-FileCopyrightText: 2022 Jost Alemann
SPDX-FileCopyrightText: 2023 Felix Stupp
SPDX-FileCopyrightText: 2023 Julian-Samuel Gebühr
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later

121
LICENSES/CC0-1.0.txt
View File

@ -1,121 +0,0 @@
Creative Commons Legal Code
CC0 1.0 Universal
CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
HEREUNDER.
Statement of Purpose
The laws of most jurisdictions throughout the world automatically confer
exclusive Copyright and Related Rights (defined below) upon the creator
and subsequent owner(s) (each and all, an "owner") of an original work of
authorship and/or a database (each, a "Work").
Certain owners wish to permanently relinquish those rights to a Work for
the purpose of contributing to a commons of creative, cultural and
scientific works ("Commons") that the public can reliably and without fear
of later claims of infringement build upon, modify, incorporate in other
works, reuse and redistribute as freely as possible in any form whatsoever
and for any purposes, including without limitation commercial purposes.
These owners may contribute to the Commons to promote the ideal of a free
culture and the further production of creative, cultural and scientific
works, or to gain reputation or greater distribution for their Work in
part through the use and efforts of others.
For these and/or other purposes and motivations, and without any
expectation of additional consideration or compensation, the person
associating CC0 with a Work (the "Affirmer"), to the extent that he or she
is an owner of Copyright and Related Rights in the Work, voluntarily
elects to apply CC0 to the Work and publicly distribute the Work under its
terms, with knowledge of his or her Copyright and Related Rights in the
Work and the meaning and intended legal effect of CC0 on those rights.
1. Copyright and Related Rights. A Work made available under CC0 may be
protected by copyright and related or neighboring rights ("Copyright and
Related Rights"). Copyright and Related Rights include, but are not
limited to, the following:
i. the right to reproduce, adapt, distribute, perform, display,
communicate, and translate a Work;
ii. moral rights retained by the original author(s) and/or performer(s);
iii. publicity and privacy rights pertaining to a person's image or
likeness depicted in a Work;
iv. rights protecting against unfair competition in regards to a Work,
subject to the limitations in paragraph 4(a), below;
v. rights protecting the extraction, dissemination, use and reuse of data
in a Work;
vi. database rights (such as those arising under Directive 96/9/EC of the
European Parliament and of the Council of 11 March 1996 on the legal
protection of databases, and under any national implementation
thereof, including any amended or successor version of such
directive); and
vii. other similar, equivalent or corresponding rights throughout the
world based on applicable law or treaty, and any national
implementations thereof.
2. Waiver. To the greatest extent permitted by, but not in contravention
of, applicable law, Affirmer hereby overtly, fully, permanently,
irrevocably and unconditionally waives, abandons, and surrenders all of
Affirmer's Copyright and Related Rights and associated claims and causes
of action, whether now known or unknown (including existing as well as
future claims and causes of action), in the Work (i) in all territories
worldwide, (ii) for the maximum duration provided by applicable law or
treaty (including future time extensions), (iii) in any current or future
medium and for any number of copies, and (iv) for any purpose whatsoever,
including without limitation commercial, advertising or promotional
purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
member of the public at large and to the detriment of Affirmer's heirs and
successors, fully intending that such Waiver shall not be subject to
revocation, rescission, cancellation, termination, or any other legal or
equitable action to disrupt the quiet enjoyment of the Work by the public
as contemplated by Affirmer's express Statement of Purpose.
3. Public License Fallback. Should any part of the Waiver for any reason
be judged legally invalid or ineffective under applicable law, then the
Waiver shall be preserved to the maximum extent permitted taking into
account Affirmer's express Statement of Purpose. In addition, to the
extent the Waiver is so judged Affirmer hereby grants to each affected
person a royalty-free, non transferable, non sublicensable, non exclusive,
irrevocable and unconditional license to exercise Affirmer's Copyright and
Related Rights in the Work (i) in all territories worldwide, (ii) for the
maximum duration provided by applicable law or treaty (including future
time extensions), (iii) in any current or future medium and for any number
of copies, and (iv) for any purpose whatsoever, including without
limitation commercial, advertising or promotional purposes (the
"License"). The License shall be deemed effective as of the date CC0 was
applied by Affirmer to the Work. Should any part of the License for any
reason be judged legally invalid or ineffective under applicable law, such
partial invalidity or ineffectiveness shall not invalidate the remainder
of the License, and in such case Affirmer hereby affirms that he or she
will not (i) exercise any of his or her remaining Copyright and Related
Rights in the Work or (ii) assert any associated claims and causes of
action with respect to the Work, in either case contrary to Affirmer's
express Statement of Purpose.
4. Limitations and Disclaimers.
a. No trademark or patent rights held by Affirmer are waived, abandoned,
surrendered, licensed or otherwise affected by this document.
b. Affirmer offers the Work as-is and makes no representations or
warranties of any kind concerning the Work, express, implied,
statutory or otherwise, including without limitation warranties of
title, merchantability, fitness for a particular purpose, non
infringement, or the absence of latent or other defects, accuracy, or
the present or absence of errors, whether or not discoverable, all to
the greatest extent permissible under applicable law.
c. Affirmer disclaims responsibility for clearing rights of other persons
that may apply to the Work or any use thereof, including without
limitation any person's Copyright and Related Rights in the Work.
Further, Affirmer disclaims responsibility for obtaining any necessary
consents, permissions or other rights required for any use of the
Work.
d. Affirmer understands and acknowledges that Creative Commons is not a
party to this document and has no duty or obligation with respect to
this CC0 or use of the Work.

4
Makefile
View File

@ -1,7 +1,3 @@
# SPDX-FileCopyrightText: 2022 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
.PHONY: roles lint
help: ## Show this help.

51
README.md
View File

@ -1,4 +1,4 @@
[![Support room on Matrix](https://img.shields.io/matrix/matrix-docker-ansible-deploy:devture.com.svg?label=%23matrix-docker-ansible-deploy%3Adevture.com&logo=matrix&style=for-the-badge&server_fqdn=matrix.devture.com)](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) [![donate](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/s.pantaleev/donate) [![REUSE status](https://api.reuse.software/badge/github.com/spantaleev/matrix-docker-ansible-deploy)](https://api.reuse.software/info/github.com/spantaleev/matrix-docker-ansible-deploy)
[![Support room on Matrix](https://img.shields.io/matrix/matrix-docker-ansible-deploy:devture.com.svg?label=%23matrix-docker-ansible-deploy%3Adevture.com&logo=matrix&style=for-the-badge&server_fqdn=matrix.devture.com)](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) [![donate](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/s.pantaleev/donate)
# Matrix (An open network for secure, decentralized communication) server setup using Ansible and Docker
@ -52,8 +52,7 @@ The homeserver is the backbone of your Matrix system. Choose one from the follow
| ---- | -------- | ----------- | ------------- |
| [Synapse](https://github.com/element-hq/synapse) | ✅ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network | [Link](docs/configuring-playbook-synapse.md) |
| [Conduit](https://conduit.rs) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Conduit is a lightweight open-source server implementation of the Matrix Specification with a focus on easy setup and low system requirements | [Link](docs/configuring-playbook-conduit.md) |
| [conduwuit](https://conduwuit.puppyirl.gay/) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. conduwuit is a fork of Conduit. | [Link](docs/configuring-playbook-conduwuit.md) |
| [Dendrite](https://github.com/element-hq/dendrite) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse. | [Link](docs/configuring-playbook-dendrite.md) |
| [Dendrite](https://github.com/matrix-org/dendrite) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse. | [Link](docs/configuring-playbook-dendrite.md) |
### Clients
@ -65,7 +64,6 @@ Web clients for Matrix that you can host on your own domains.
| [Hydrogen](https://github.com/element-hq/hydrogen-web) | ❌ | Lightweight Matrix client with legacy and mobile browser support | [Link](docs/configuring-playbook-client-hydrogen.md) |
| [Cinny](https://github.com/ajbura/cinny) | ❌ | Simple, elegant and secure web client | [Link](docs/configuring-playbook-client-cinny.md) |
| [SchildiChat Web](https://schildi.chat/) | ❌ | Based on Element Web, with a more traditional instant messaging experience | [Link](docs/configuring-playbook-client-schildichat-web.md) |
| [FluffyChat Web](https://fluffychat.im/) | ❌ | The cutest messenger in Matrix | [Link](docs/configuring-playbook-client-fluffychat-web.md) |
### Server Components
@ -74,14 +72,12 @@ Services that run on the server to make the various parts of your installation w
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [PostgreSQL](https://www.postgresql.org/)| ✅ | Database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible. | [Link](docs/configuring-playbook-external-postgres.md) |
| [coturn](https://github.com/coturn/coturn) | ✅ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
| [Traefik](https://doc.traefik.io/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. [Using your own webserver](docs/configuring-playbook-own-webserver.md) is also possible. | [Link](docs/configuring-playbook-traefik.md) |
| [Coturn](https://github.com/coturn/coturn) | ✅ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
| [Traefik](https://doc.traefik.io/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md) | [Link](docs/configuring-playbook-traefik.md) |
| [Let's Encrypt](https://letsencrypt.org/) | ✅ | Free SSL certificate, which secures the connection to all components | [Link](docs/configuring-playbook-ssl-certificates.md) |
| [Exim](https://www.exim.org/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | [Link](docs/configuring-playbook-email.md) |
| [ma1sd](https://github.com/ma1uta/ma1sd) | ❌ | Matrix Identity Server | [Link](docs/configuring-playbook-ma1sd.md)
| [ddclient](https://github.com/linuxserver/docker-ddclient) | ❌ | Dynamic DNS | [Link](docs/configuring-playbook-dynamic-dns.md) |
| [LiveKit Server](https://github.com/livekit/livekit) | ❌ | WebRTC server for audio/video calls | [Link](docs/configuring-playbook-livekit-server.md) |
| [Livekit JWT Service](https://github.com/livekit/livekit-jwt-service) | ❌ | JWT service for integrating [Element Call](./configuring-playbook-element-call.md) with [LiveKit Server](./configuring-playbook-livekit-server.md) | [Link](docs/configuring-playbook-livekit-jwt-service.md) |
### Authentication
@ -92,10 +88,10 @@ Extend and modify how users are authenticated on your homeserver.
| [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) (advanced) | ❌ | REST authentication password provider module | [Link](docs/configuring-playbook-rest-auth.md) |
|[matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) (advanced) | ❌ | Password provider module | [Link](docs/configuring-playbook-shared-secret-auth.md) |
| [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) (advanced) | ❌ | LDAP Auth password provider module | [Link](docs/configuring-playbook-ldap-auth.md) |
| [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) (advanced) | ❌ | Proxy that handles Matrix registration requests and forwards them to LDAP | [Link](docs/configuring-playbook-matrix-ldap-registration-proxy.md) |
| [matrix-registration](https://github.com/ZerataX/matrix-registration) | ❌ | Simple python application to have a token based Matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
| [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) | ❌ | Service to verify details of a user based on an Open ID token | [Link](docs/configuring-playbook-user-verification-service.md) |
| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | Spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
| [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) (advanced) | ❌ | A proxy that handles Matrix registration requests and forwards them to LDAP. | [Link](docs/configuring-playbook-matrix-ldap-registration-proxy.md) |
| [matrix-registration](https://github.com/ZerataX/matrix-registration) | ❌ | A simple python application to have a token based Matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
| [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (UVS) | ❌ | Service to verify details of a user based on an Open ID token | [Link](docs/configuring-playbook-user-verification-service.md) |
| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | A spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
### File Storage
@ -105,7 +101,7 @@ Use alternative file storage to the default `media_store` folder.
| ---- | -------- | ----------- | ------------- |
| [Goofys](https://github.com/kahing/goofys) | ❌ | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3-goofys.md) |
| [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) | ❌ | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3.md) |
| [matrix-media-repo](https://github.com/turt2live/matrix-media-repo) | ❌ | Highly customizable multi-domain media repository for Matrix. Intended for medium to large deployments, this media repo de-duplicates media while being fully compliant with the specification. | [Link](docs/configuring-playbook-matrix-media-repo.md) |
| [matrix-media-repo](https://github.com/turt2live/matrix-media-repo) | ❌ | matrix-media-repo is a highly customizable multi-domain media repository for Matrix. Intended for medium to large deployments, this media repo de-duplicates media while being fully compliant with the specification. | [Link](docs/configuring-playbook-matrix-media-repo.md) |
### Bridges
@ -119,7 +115,6 @@ Bridges can be used to connect your Matrix installation with third-party communi
| [mautrix-gmessages](https://github.com/mautrix/gmessages) | ❌ | Bridge to [Google Messages](https://messages.google.com/) | [Link](docs/configuring-playbook-bridge-mautrix-gmessages.md) |
| [mautrix-whatsapp](https://github.com/mautrix/whatsapp) | ❌ | Bridge to [WhatsApp](https://www.whatsapp.com/) | [Link](docs/configuring-playbook-bridge-mautrix-whatsapp.md) |
| [mautrix-wsproxy](https://github.com/mautrix/wsproxy) | ❌ | Bridge to Android SMS or Apple iMessage | [Link](docs/configuring-playbook-bridge-mautrix-wsproxy.md) |
| [mautrix-bluesky](https://github.com/mautrix/bluesky) | ❌ | Bridge to [Bluesky](https://bsky.social/) | [Link](docs/configuring-playbook-bridge-mautrix-bluesky.md) |
| [mautrix-twitter](https://github.com/mautrix/twitter) | ❌ | Bridge to [Twitter](https://twitter.com/) | [Link](docs/configuring-playbook-bridge-mautrix-twitter.md) |
| [mautrix-googlechat](https://github.com/mautrix/googlechat) | ❌ | Bridge to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat) | [Link](docs/configuring-playbook-bridge-mautrix-googlechat.md) |
| [mautrix-meta](https://github.com/mautrix/instagram) | ❌ | Bridge to [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) | Link for [Messenger](docs/configuring-playbook-bridge-mautrix-meta-messenger.md) / [Instagram](docs/configuring-playbook-bridge-mautrix-meta-instagram.md) |
@ -140,6 +135,7 @@ Bridges can be used to connect your Matrix installation with third-party communi
| [mx-puppet-discord](https://gitlab.com/mx-puppet/discord/mx-puppet-discord) | ❌ | Bridge to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-discord.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://github.com/icewind1991/mx-puppet-steam) | ❌ | Bridge to [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) |
| [Email2Matrix](https://github.com/devture/email2matrix) | ❌ | Bridge for relaying emails to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) |
| [Postmoogle](https://github.com/etkecc/postmoogle) | ❌ | Email to Matrix bridge | [Link](docs/configuring-playbook-bridge-postmoogle.md) |
### Bots
@ -148,13 +144,13 @@ Bots provide various additional functionality to your installation.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [baibot](https://github.com/etkecc/baibot) | ❌ | Bot that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you | [Link](docs/configuring-playbook-bot-baibot.md) |
| [baibot](https://github.com/etkecc/baibot) | ❌ | A bot that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you | [Link](docs/configuring-playbook-bot-baibot.md) |
| [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) | ❌ | Bot for scheduling one-off & recurring reminders and alarms | [Link](docs/configuring-playbook-bot-matrix-reminder-bot.md) |
| [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) | ❌ | Bot for invitations by creating and managing registration tokens | [Link](docs/configuring-playbook-bot-matrix-registration-bot.md) |
| [maubot](https://github.com/maubot/maubot) | ❌ | Plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) |
| [Honoroit](https://github.com/etkecc/honoroit) | ❌ | Helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) |
| [Mjolnir](https://github.com/matrix-org/mjolnir) | ❌ | Moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) |
| [Draupnir](https://github.com/the-draupnir-project/Draupnir) | ❌ | Moderation tool for Matrix (Fork of Mjolnir) | [Link](docs/configuring-playbook-bot-draupnir.md) (for [appservice mode](docs/configuring-playbook-appservice-draupnir-for-all.md))|
| [maubot](https://github.com/maubot/maubot) | ❌ | A plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) |
| [Honoroit](https://github.com/etkecc/honoroit) | ❌ | A helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) |
| [Mjolnir](https://github.com/matrix-org/mjolnir) | ❌ | A moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) |
| [Draupnir](https://github.com/the-draupnir-project/Draupnir) | ❌ | A moderation tool for Matrix (Fork of Mjolnir) | [Link](docs/configuring-playbook-bot-draupnir.md) (for [appservice mode](docs/configuring-playbook-appservice-draupnir-for-all.md))|
| [Buscarron](https://github.com/etkecc/buscarron) | ❌ | Web forms (HTTP POST) to Matrix | [Link](docs/configuring-playbook-bot-buscarron.md) |
### Administration
@ -165,8 +161,8 @@ Services that help you in administrating and monitoring your Matrix installation
| ---- | -------- | ----------- | ------------- |
| [matrix-alertmanager-receiver](https://github.com/metio/matrix-alertmanager-receiver) | ❌ | Prometheus' [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) client | [Link](docs/configuring-playbook-alertmanager-receiver.md) |
| [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) | ❌ | OAuth 2.0 and OpenID Provider server | [Link](docs/configuring-playbook-matrix-authentication-service.md) |
| [synapse-admin](https://github.com/etkecc/synapse-admin) | ❌ | Web UI tool for administrating users and rooms on your Matrix server | [Link](docs/configuring-playbook-synapse-admin.md) |
| Metrics and Graphs | ❌ | Consists of the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI, with [prometheus-nginxlog-exporter](https://github.com/martin-helmich/prometheus-nginxlog-exporter/) being available too | [Link](docs/configuring-playbook-prometheus-grafana.md) (for [prometheus-nginxlog-exporter](docs/configuring-playbook-prometheus-grafana.md#enable-metrics-and-graphs-for-nginx-logs-optional)) |
| [synapse-admin](https://github.com/etkecc/synapse-admin) | ❌ | A web UI tool for administrating users and rooms on your Matrix server | [Link](docs/configuring-playbook-synapse-admin.md) |
| Metrics and Graphs | ❌ | Consists of the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI, with [prometheus-nginxlog-exporter](https://github.com/martin-helmich/prometheus-nginxlog-exporter/) being available too | [Link](docs/configuring-playbook-prometheus-grafana.md) (for [prometheus-nginxlog-exporter](docs/configuring-playbook-prometheus-nginxlog.md)) |
| [Borg](https://borgbackup.org) | ❌ | Backups | [Link](docs/configuring-playbook-backup-borg.md) |
| [rageshake](https://github.com/matrix-org/rageshake) | ❌ | Bug report server | [Link](docs/configuring-playbook-rageshake.md) |
| [synapse-usage-exporter](https://github.com/loelkes/synapse-usage-exporter) | ❌ | Export the usage statistics of a Synapse homeserver to be scraped by Prometheus. | [Link](docs/configuring-playbook-synapse-usage-exporter.md) |
@ -178,16 +174,15 @@ Various services that don't fit any other categories.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [sliding-sync](https://github.com/matrix-org/sliding-sync)| ❌ | (Superseded by Simplified Sliding Sync integrated into Synapse > `1.114` and Conduit > `0.6.0`) Sliding Sync support for clients which require it (e.g. old Element X versions before Simplified Sliding Sync was developed) | [Link](docs/configuring-playbook-sliding-sync-proxy.md) |
| [synapse_auto_accept_invite](https://github.com/matrix-org/synapse-auto-accept-invite) | ❌ | Synapse module to automatically accept invites | [Link](docs/configuring-playbook-synapse-auto-accept-invite.md) |
| [synapse_auto_compressor](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) | ❌ | Cli tool that automatically compresses `state_groups` database table in background | [Link](docs/configuring-playbook-synapse-auto-compressor.md) |
| [synapse_auto_accept_invite](https://github.com/matrix-org/synapse-auto-accept-invite) | ❌ | A Synapse module to automatically accept invites. | [Link](docs/configuring-playbook-synapse-auto-accept-invite.md) |
| [synapse_auto_compressor](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) | ❌ | A cli tool that automatically compresses `state_groups` database table in background. | [Link](docs/configuring-playbook-synapse-auto-compressor.md) |
| [Matrix Corporal](https://github.com/devture/matrix-corporal) (advanced) | ❌ | Reconciliator and gateway for a managed Matrix server | [Link](docs/configuring-playbook-matrix-corporal.md) |
| [Etherpad](https://etherpad.org) | ❌ | Open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
| [Jitsi](https://jitsi.org/) | ❌ | Open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
| [Cactus Comments](https://cactus.chat) | ❌ | Federated comment system built on Matrix | [Link](docs/configuring-playbook-cactus-comments.md) |
| [Pantalaimon](https://github.com/matrix-org/pantalaimon) | ❌ | E2EE aware proxy daemon | [Link](docs/configuring-playbook-pantalaimon.md) |
| [Etherpad](https://etherpad.org) | ❌ | An open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
| [Jitsi](https://jitsi.org/) | ❌ | An open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
| [Cactus Comments](https://cactus.chat) | ❌ | A federated comment system built on Matrix | [Link](docs/configuring-playbook-cactus-comments.md) |
| [Pantalaimon](https://github.com/matrix-org/pantalaimon) | ❌ | An E2EE aware proxy daemon | [Link](docs/configuring-playbook-pantalaimon.md) |
| [Sygnal](https://github.com/matrix-org/sygnal) | ❌ | Push gateway | [Link](docs/configuring-playbook-sygnal.md) |
| [ntfy](https://ntfy.sh) | ❌ | Push notifications server | [Link](docs/configuring-playbook-ntfy.md) |
| [Element Call](https://github.com/element-hq/element-call) | ❌ | A native Matrix video conferencing application | [Link](docs/configuring-playbook-element-call.md) |
## 🆕 Changes

34
README.md.license
View File

@ -1,34 +0,0 @@
SPDX-FileCopyrightText: 2017 - 2025 MDAD project contributors
SPDX-FileCopyrightText: 2017 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2018 - 2021 Aaron Raimist
SPDX-FileCopyrightText: 2019 - 2020 Hugues Morisset
SPDX-FileCopyrightText: 2019 Edgars Voroboks
SPDX-FileCopyrightText: 2019 Eduardo Beltrame
SPDX-FileCopyrightText: 2020 Björn Marten
SPDX-FileCopyrightText: 2020 Lee Verberne
SPDX-FileCopyrightText: 2020 Marcel Partap
SPDX-FileCopyrightText: 2020 Matthew Croughan
SPDX-FileCopyrightText: 2020 Tulir Asokan
SPDX-FileCopyrightText: 2021 Alexandar Mechev
SPDX-FileCopyrightText: 2021 Béla Becker
SPDX-FileCopyrightText: 2021 Cody Neiman
SPDX-FileCopyrightText: 2021 Marcus Proest
SPDX-FileCopyrightText: 2021 Matthew Cengia
SPDX-FileCopyrightText: 2021 Prasiddh Pooskur
SPDX-FileCopyrightText: 2021 Toni Spets
SPDX-FileCopyrightText: 2021 Yannick Goossens
SPDX-FileCopyrightText: 2022 - 2023 Cody Wyatt Neiman
SPDX-FileCopyrightText: 2022 - 2025 Nikita Chernyi
SPDX-FileCopyrightText: 2022 Andrew Morgan
SPDX-FileCopyrightText: 2022 Christos Karamolegkos
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Julian Foad
SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
SPDX-FileCopyrightText: 2022 Kim Brose
SPDX-FileCopyrightText: 2023 - 2024 Michael Hollister
SPDX-FileCopyrightText: 2023 Joe Kappus
SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
SPDX-FileCopyrightText: 2023 Shreyas Ajjarapu
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later

11
YEAR-IN-REVIEW.md
View File

@ -1,10 +1,3 @@
<!--
SPDX-FileCopyrightText: 2023 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# 2023
2023 was a year filled with many changes for matrix-docker-ansible-deploy. In this post, we're looking backward at some of the major changes that happened this year, as well as taking a glimpse of what's ahead in 2024.
@ -59,7 +52,7 @@ Hopefully, Synapse defaults would also change the same way and we'd see the numb
With this configuration change in place, projects like [MatrixRooms.info](https://matrixrooms.info/) (made by [etke.cc](https://etke.cc/)) and potentially others in the future, can discover, index the metadata (room address, title, topic, number of users, etc.) and make public rooms browsable & searchable across the whole Matrix Federation. It'd be great if users joining Matrix could more easily find interesting communities that match their interests!
On the **media side of things**, besides Jitsi getting better Matrix integration (via the aforementioned Matrix User Verification Service), we've also had some [coturn security tightening](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues) as well as [performance optimizations](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#coturn-can-now-use-host-networking) for configurations exposing lots of network ports.
On the **media side of things**, besides Jitsi getting better Matrix integration (via the aforementioned Matrix User Verification Service), we've also had some [Coturn security tightening](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues) as well as [performance optimizations](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#coturn-can-now-use-host-networking) for configurations exposing lots of network ports.
[Element Call](https://github.com/element-hq/element-call) seems to have become a nice and polished product lately (as proclaimed in [The Matrix Holiday Update 2023](https://matrix.org/blog/2023/12/25/the-matrix-holiday-update-2023/)), so 2024 is likely the year we'll see support for it in the playbook. Element Call depends on the [LiveKit](https://livekit.io/) streaming server (which is also useful to developers even by itself), so the first step is likely to see LiveKit support in mash-playbook via a reusable Ansible role. Such a LiveKit Ansible role could later easily land in matrix-docker-ansible-deploy and an Element Call static website could be hooked to it.
@ -76,7 +69,7 @@ When it comes to the `matrix-docker-ansible-deploy` Ansible playbook, 2022 was t
Support for the following new **bridges** was added:
* [Postmoogle](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#postmoogle-email-bridge-support) for bi-directional email bridging, which supersedes my old and simplistic [Email2Matrix](https://github.com/devture/email2matrix) one-way bridge-bot
* [Postmoogle](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#postmoogle-email-bridge-support) for bi-directional email bridging, which supersedes my old and simplistic [email2matrix](https://github.com/devture/email2matrix) one-way bridge-bot
* [mautrix-discord](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#mautrix-discord-support)
* [go-skype-bridge](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#go-skype-bridge-bridging-support)
* [matrix-appservice-kakaotalk](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix-appservice-kakaotalk-support)

2
ansible.cfg
View File

@ -1,6 +1,6 @@
[defaults]
retry_files_enabled = False
result_format = yaml
stdout_callback = yaml
[connection]
pipelining = True

6
bin/ansible-all-hosts.sh
View File

@ -1,10 +1,4 @@
#!/usr/bin/env bash
# SPDX-FileCopyrightText: 2022 - 2024 MDAD project contributors
# SPDX-FileCopyrightText: 2024 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
#
# Run the playbook on multiple hosts with different credentials with this script
# It defaults to ansible tags "setup-all,start". You can pass alternative tags

17
bin/rebuild-mautrix-meta-instagram.sh
View File

@ -1,9 +1,4 @@
#!/bin/bash
# SPDX-FileCopyrightText: 2024 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
set -euxo pipefail
# This script rebuilds the mautrix-meta-instagram Ansible role, using the mautrix-meta-messenger role as a source.
@ -37,17 +32,7 @@ done
sed --in-place 's/matrix_mautrix_meta_instagram_meta_mode: \(.*\)/matrix_mautrix_meta_instagram_meta_mode: instagram/g' $instagram_role_path/defaults/main.yml
sed --in-place 's/matrix_mautrix_meta_instagram_identifier: \(.*\)/matrix_mautrix_meta_instagram_identifier: matrix-mautrix-meta-instagram/g' $instagram_role_path/defaults/main.yml
# Create the README.md file with the license header
cat > $instagram_role_path/README.md << 'EOF'
<!--
SPDX-FileCopyrightText: 2024 - 2025 MDAD Contributors
SPDX-License-Identifier: AGPL-3.0-or-later
-->
EOF
echo "" >> $instagram_role_path/README.md
echo "# matrix-mautrix-meta-instagram" >> $instagram_role_path/README.md
echo "# matrix-mautrix-meta-instagram" > $instagram_role_path/README.md
echo "" >> $instagram_role_path/README.md
echo "This bridge role is derived from the matrix-mautrix-meta-messenger Ansible role via automatic changes (see \`just rebuild-mautrix-meta-instagram\` or \`bin/rebuild-mautrix-meta-instagram.sh\`)." >> $instagram_role_path/README.md
echo "" >> $instagram_role_path/README.md

33
docs/README.md
View File

@ -1,12 +1,3 @@
<!--
SPDX-FileCopyrightText: 2018 - 2021 Slavi Pantaleev
SPDX-FileCopyrightText: 2018 Aaron Raimist
SPDX-FileCopyrightText: 2019 Lyubomir Popov
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Table of Contents
## ⬇️ Installaton guides <!-- NOTE: the 🚀 emoji is used by "Getting started" on README.md -->
@ -19,7 +10,7 @@ There are two installation guides available for beginners and advanced users.
- [Prerequisites](prerequisites.md)
- [Configuring DNS settings](configuring-dns.md)
- [Configuring your DNS settings](configuring-dns.md)
- [Getting the playbook](getting-the-playbook.md)
@ -36,23 +27,23 @@ NOTE:
You can check useful documentation for configuring components here: [Configuring the playbook](configuring-playbook.md)
- [Administration](configuring-playbook.md#administration) — services that help you in administrating and monitoring your Matrix installation
- [Administration](configuring-playbook.md#administration) - services that help you in administrating and monitoring your Matrix installation
- [Authentication and user-related](configuring-playbook.md#authentication-and-user-related) — extend and modify how users are authenticated on your homeserver
- [Authentication and user-related](configuring-playbook.md#authentication-and-user-related) - extend and modify how users are authenticated on your homeserver
- [Bots](configuring-playbook.md#bots) — bots provide various additional functionality to your installation
- [Bots](configuring-playbook.md#bots) - bots provide various additional functionality to your installation
- [Bridges](configuring-playbook.md#bridging-other-networks) — bridges can be used to connect your Matrix installation with third-party communication networks
- [Bridges](configuring-playbook.md#bridging-other-networks) - bridges can be used to connect your Matrix installation with third-party communication networks
- [Clients](configuring-playbook.md#clients) — web clients for Matrix that you can host on your own domains
- [Clients](configuring-playbook.md#clients) - web clients for Matrix that you can host on your own domains
- [Core service adjustments](configuring-playbook.md#core-service-adjustments) — backbone of your Matrix system
- [Core service adjustments](configuring-playbook.md#core-service-adjustments) - backbone of your Matrix system
- [File Storage](configuring-playbook.md#file-storage) — use alternative file storage to the default `media_store` folder
- [File Storage](configuring-playbook.md#file-storage) - use alternative file storage to the default `media_store` folder
<!-- NOTE: sort list items above alphabetically -->
- [Other specialized services](configuring-playbook.md#other-specialized-services) — various services that don't fit any other categories
- [Other specialized services](configuring-playbook.md#other-specialized-services) - various services that don't fit any other categories
## 👨‍🔧 Maintenance
@ -60,6 +51,8 @@ If your server and services experience issues, feel free to come to [our support
<!-- NOTE: sort list items alphabetically -->
- [Checking if services work](maintenance-checking-services.md)
- [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)
- [PostgreSQL maintenance](maintenance-postgres.md)
@ -70,7 +63,7 @@ If your server and services experience issues, feel free to come to [our support
## Other documentation pages <!-- NOTE: this header's title and the section below need optimization -->
- ℹ️ **[FAQ](faq.md)** — various Frequently Asked Questions about Matrix, with a focus on this Ansible playbook
- ℹ️ **[FAQ](faq.md)** - various Frequently Asked Questions about Matrix, with a focus on this Ansible playbook
<!-- NOTE: sort list items under faq.md alphabetically -->
@ -91,5 +84,3 @@ If your server and services experience issues, feel free to come to [our support
- [Uninstalling](uninstalling.md)
- [Updating users passwords](updating-users-passwords.md)
- [Using Ansible for the playbook](ansible.md)

8
docs/alternative-architectures.md
View File

@ -1,11 +1,3 @@
<!--
SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 Horvath Gergely
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Alternative architectures
As stated in the [Prerequisites](prerequisites.md), currently only `amd64` (`x86_64`) is fully supported.

50
docs/ansible.md
View File

@ -1,14 +1,5 @@
<!--
SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 Aaron Raimist
SPDX-FileCopyrightText: 2020 Hanno J. Gödecke
SPDX-FileCopyrightText: 2022 Kai Biebel
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Using Ansible for the playbook
# Running this playbook
This playbook is meant to be run using [Ansible](https://www.ansible.com/).
@ -38,12 +29,9 @@ If using the `pip` method, do note that the `ansible-playbook` binary may not be
## Using Ansible via Docker
Alternatively, you can run Ansible inside a Docker container (powered by the [ghcr.io/devture/ansible](https://github.com/devture/docker-ansible/pkgs/container/ansible) Docker image).
Alternatively, you can run Ansible inside a Docker container (powered by the [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
This ensures that:
- you're using a very recent Ansible version, which is less likely to be incompatible with the playbook
- you also get access to the [agru](https://github.com/etkecc/agru) tool for quicker Ansible role installation (when running `just roles`) compared to `ansible-galaxy`
This ensures that you're using a very recent Ansible version, which is less likely to be incompatible with the playbook.
You can either [run Ansible in a container on the Matrix server itself](#running-ansible-in-a-container-on-the-matrix-server-itself) or [run Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server).
@ -54,58 +42,54 @@ To run Ansible in a (Docker) container on the Matrix server itself, you need to
- you **either** need to install Docker manually first. Follow [the upstream instructions](https://docs.docker.com/engine/install/) for your distribution and consider setting `matrix_playbook_docker_installation_enabled: false` in your `vars.yml` file, to prevent the playbook from installing Docker
- **or** you need to run the playbook in another way (e.g. [Running Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server)) at least the first time around
Once you have a working Docker installation on the server, **clone the playbook** somewhere on the server and configure it as per usual (`inventory/hosts`, `inventory/host_vars/…`, etc.), as described in [configuring the playbook](configuring-playbook.md).
Once you have a working Docker installation on the server, **clone the playbook** somewhere on the server and configure it as per usual (`inventory/hosts`, `inventory/host_vars/..`, etc.), as described in [configuring the playbook](configuring-playbook.md).
You would then need to add `ansible_connection=community.docker.nsenter` to the host line in `inventory/hosts`. This tells Ansible to connect to the "remote" machine by switching Linux namespaces with [nsenter](https://man7.org/linux/man-pages/man1/nsenter.1.html), instead of using SSH.
Alternatively, you can leave your `inventory/hosts` as is and specify the connection type in **each** `ansible-playbook` call you do later, like this: `just install-all --connection=community.docker.nsenter` (or `ansible-playbook --connection=community.docker.nsenter …`).
Alternatively, you can leave your `inventory/hosts` as is and specify the connection type in **each** `ansible-playbook` call you do later, like this: `ansible-playbook --connection=community.docker.nsenter …`
Run this from the playbook's directory:
```sh
docker run \
-it \
--rm \
docker run -it --rm \
--privileged \
--pid=host \
-w /work \
--mount type=bind,src=`pwd`,dst=/work \
-v `pwd`:/work \
--entrypoint=/bin/sh \
ghcr.io/devture/ansible:11.1.0-r0-0
docker.io/devture/ansible:2.18.1-r0-0
```
Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container. The `/work` directory contains the playbook's code.
First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
Finally, you can execute `just` or `ansible-playbook …` (e.g. `ansible-playbook --connection=community.docker.nsenter …`) commands as per normal now.
Finally, you can execute `ansible-playbook …` (or `ansible-playbook --connection=community.docker.nsenter …`) commands as per normal now.
### Running Ansible in a container on another computer (not the Matrix server)
Run this from the playbook's directory:
```sh
docker run \
-it \
--rm \
docker run -it --rm \
-w /work \
--mount type=bind,src=`pwd`,dst=/work \
--mount type=bind,src$HOME/.ssh/id_ed25519,dst=/root/.ssh/id_ed25519,ro \
-v `pwd`:/work \
-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
--entrypoint=/bin/sh \
ghcr.io/devture/ansible:11.1.0-r0-0
docker.io/devture/ansible:2.18.1-r0-0
```
The above command tries to mount an SSH key (`$HOME/.ssh/id_ed25519`) into the container (at `/root/.ssh/id_ed25519`). If your SSH key is at a different path (not in `$HOME/.ssh/id_ed25519`), adjust that part.
The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`). If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that part.
Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container. The `/work` directory contains the playbook's code.
First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
Finally, you execute `just` or `ansible-playbook …` commands as per normal now.
Finally, you execute `ansible-playbook …` commands as per normal now.
#### If you don't use SSH keys for authentication
If you don't use SSH keys for authentication, simply remove that whole line (`--mount type=bind,src$HOME/.ssh/id_ed25519,dst=/root/.ssh/id_ed25519,ro`).
If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`).
To authenticate at your server using a password, you need to add a package. So, when you are in the shell of the ansible docker container (the previously used `docker run -it …` command), run:
@ -113,7 +97,7 @@ To authenticate at your server using a password, you need to add a package. So,
apk add sshpass
```
Then, to be asked for the password whenever running an `ansible-playbook` command add `--ask-pass` to the arguments of the command.
Then, to be asked for the password whenever running an `ansible-playbook` command add `--ask-pass` to the arguments of the command.
#### Resolve directory ownership issues

3
docs/assets/obtain_admin_access_token_element_web.png.license
View File

@ -1,3 +0,0 @@
SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
SPDX-License-Identifier: AGPL-3.0-or-later

9
docs/configuring-captcha.md
View File

@ -1,12 +1,3 @@
<!--
SPDX-FileCopyrightText: 2020 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 Justin Croonenberghs
SPDX-FileCopyrightText: 2022 MDAD project contributors
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
(Adapted from the [upstream project](https://github.com/element-hq/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
# Overview

93
docs/configuring-dns.md
View File

@ -1,46 +1,9 @@
<!--
SPDX-FileCopyrightText: 2018 - 2024 MDAD project contributors
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 Edgars Voroboks
SPDX-FileCopyrightText: 2020 - 2021 Aaron Raimist
SPDX-FileCopyrightText: 2020 Marcel Partap
SPDX-FileCopyrightText: 2020 Rónán Duddy
SPDX-FileCopyrightText: 2021 Yannick Goossens
SPDX-FileCopyrightText: 2022 Julian Foad
SPDX-FileCopyrightText: 2022 Nikita Chernyi
SPDX-FileCopyrightText: 2023 Johan Swetzén
SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
# Configuring your DNS settings
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Configuring DNS settings
<sup>[Prerequisites](prerequisites.md) > Configuring DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
<sup>[Prerequisites](prerequisites.md) > Configuring your DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
To set up Matrix on your domain, you'd need to do some DNS configuration.
## DNS settings for services enabled by default
To serve the base domain (`example.com`) and [Element Web](configuring-playbook-client-element-web.md) with the default subdomain, adjust DNS records as below.
| Type | Host | Priority | Weight | Port | Target |
| ----- | --------- | -------- | ------ | ---- | ---------------------|
| A | `matrix` | - | - | - | `matrix-server-IPv4` |
| AAAA | `matrix` | - | - | - | `matrix-server-IPv6` |
| CNAME | `element` | - | - | - | `matrix.example.com` |
As the table illustrates, you need to create 2 subdomains (`matrix.example.com` and `element.example.com`) and point both of them to your server's IPv4/IPv6 address.
If you don't have IPv6 connectivity yet, you can skip the `AAAA` record. For more details about IPv6, see the [Configuring IPv6](./configuring-ipv6.md) documentation page.
The `element.example.com` subdomain is necessary, because this playbook installs the [Element Web](https://github.com/element-hq/element-web) client for you by default. If you'd rather instruct the playbook not to install Element Web (`matrix_client_element_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `element.example.com` DNS record.
Be mindful as to how long it will take for the DNS records to propagate.
**Note**: if you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only". Otherwise, fetching certificates will fail.
## DNS setting for server delegation (optional)
In the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user ID like `@alice:example.com` instead of `@alice:matrix.example.com`.
@ -58,6 +21,58 @@ If you choose the recommended method (file-based delegation), you do not need to
On the other hand, if you choose this method (setting up a DNS SRV record), you need to configure the additional DNS record as well as adjust SSL certificate handling. Take a look at this documentation for more information: [Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced)
## DNS settings for services enabled by default
To serve the base domain (`example.com`) and [Element Web](configuring-playbook-client-element-web.md) with the default subdomain, adjust DNS records as below.
| Type | Host | Priority | Weight | Port | Target |
| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------|
| A | `matrix` | - | - | - | `matrix-server-IP` |
| CNAME | `element` | - | - | - | `matrix.example.com` |
As the table illustrates, you need to create 2 subdomains (`matrix.example.com` and `element.example.com`) and point both of them to your server's IP address (DNS `A` record or `CNAME` record is fine).
The `element.example.com` subdomain is necessary, because this playbook installs the [Element Web](https://github.com/element-hq/element-web) client for you by default. If you'd rather instruct the playbook not to install Element Web (`matrix_client_element_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `element.example.com` DNS record.
Be mindful as to how long it will take for the DNS records to propagate.
If you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only". Otherwise, fetching certificates will fail.
## DNS settings for optional services/features
For other services which may need subdomain settings, see the table below and configure the DNS (`CNAME`) records accordingly.
| Used by component | Type | Host | Priority | Weight | Port | Target |
| -------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | -------- | ------ | ---- | -----------------------------------|
| [Dimension](configuring-playbook-dimension.md) integration server | CNAME | `dimension` | - | - | - | `matrix.example.com` |
| [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform | CNAME | `jitsi` | - | - | - | `matrix.example.com` |
| [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system | CNAME | `stats` | - | - | - | `matrix.example.com` |
| [Go-NEB](configuring-playbook-bot-go-neb.md) bot | CNAME | `goneb` | - | - | - | `matrix.example.com` |
| [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.example.com` |
| [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.example.com` |
| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.example.com` |
| [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.example.com` |
| [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.example.com` |
| [SchildiChat Web](configuring-playbook-client-schildichat-web.md) client | CNAME | `schildichat` | - | - | - | `matrix.example.com` |
| [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge | CNAME | `wsproxy` | - | - | - | `matrix.example.com` |
| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.example.com` |
| [rageshake](configuring-playbook-rageshake.md) bug report server | CNAME | `rageshake` | - | - | - | `matrix.example.com` |
| [ma1sd](configuring-playbook-ma1sd.md) identity server | SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.example.com` |
| [Postmoogle](configuring-playbook-bridge-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX | `matrix` | 10 | 0 | - | `matrix.example.com` |
| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge | TXT | `matrix` | - | - | - | `v=spf1 ip4:matrix-server-IP -all` |
| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge | TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` |
| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge | TXT | `postmoogle._domainkey.matrix` | - | - | - | get it from `!pm dkim` |
### SRV record for ma1sd
To make ma1sd enable its federation features, you need to set up a `_matrix-identity._tcp` SRV record. Don't confuse this with the `_matrix._tcp` SRV record for server delegation. See the table above and [this section](configuring-playbook-ma1sd.md#adjusting-dns-records) for values which need to be specified.
When setting up a SRV record, if you are asked for a service and protocol instead of a hostname split the host value from the table where the period is. For example use service as `_matrix-identity` and protocol as `_tcp`.
### MX and TXT records for Postmoogle
To make Postmoogle enable its email sending features, you need to configure MX and TXT (SPF, DMARC, and DKIM) records. See the table above for values which need to be specified.
---------------------------------------------
[▶️](getting-the-playbook.md) When you're done with the DNS configuration and ready to proceed, continue with [Getting the playbook](getting-the-playbook.md).

191
docs/configuring-ipv6.md
View File

@ -1,191 +0,0 @@
<!--
SPDX-FileCopyrightText: 2025 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Configuring IPv6
Since 2025-03-08, the [default example configuration](../examples/vars.yml) for the playbook recommends enabling [IPv6](https://en.wikipedia.org/wiki/IPv6) support for Docker's container networks.
**If you have IPv6 support on your server/network** (see [How do I check if my server has IPv6 connectivity?](#how-do-i-check-if-my-server-has-ipv6-connectivity)), then [enabling IPv6 support for the playbook](#enabling-ipv6-support-for-the-playbook) would give you:
- 📥 incoming IPv6 connectivity to the server via the server's IPv6 address/addresses (containers won't have their own individual publicly accessible IPs)
- 📤 outgoing IPv6 connectivity from the server via the server's IPv6 address/addresses (containers won't exit via their own individual IPv6 address)
- 🔄 IPv6 connectivity for cross-container communication
**If you still don't have IPv6 support on your server/network**, then enabling IPv6 support for the playbook will only enable IPv6 connectivity for cross-container communication and shouldn't affect your server's incoming/outgoing communication. You may also be interested in reading if [there's a performance penalty to enabling IPv6 if the server/network doesn't support IPv6 connectivity?](#is-there-a-performance-penalty-to-enabling-ipv6-if-the-server-network-doesn-t-support-ipv6-connectivity)
As such, **we recommend that you follow the default example configuration and leave IPv6 support for Docker enabled in all cases**.
Enabling IPv6 consists of 2 steps:
- [Enabling IPv6 support for the playbook](#enabling-ipv6-support-for-the-playbook)
- [Configuring DNS records for IPv6](#configuring-dns-records-for-ipv6)
💡 If you've followed a recent version of our documentation, you would have already done these steps, so there's nothing else to do.
## Enabling IPv6 support for the playbook
You can enable IPv6 support for all components' Docker container networks by using the following `vars.yml` configuration:
```yml
# Controls whether container networks will be created with IPv6 support.
#
# If you also have IPv6 support on your server/network and AAAA DNS records pointing to the server,
# enabling this will effectively give you full public IPv6 connectivity (powered by NAT66).
#
# We recommend leaving this enabled even if you don't currently have IPv6 connectivity on your server/network.
# This way, once you eventually get IPv6 connectivity, you won't have to change anything (besides DNS records).
#
# Flipping this setting later on requires manual work (stopping services, deleting and recreating all container networks).
#
# In the future, this setting will likely default to `true`, so if you really want IPv6 disabled, explicitly set this to `false`.
#
# People managing Docker themselves and running an older Docker version will need additional configuration.
#
# Learn more in `docs/configuring-ipv6.md`.
devture_systemd_docker_base_ipv6_enabled: true
```
Doing this:
- all container networks will be IPv6-enabled
- NAT66 will be used, so that:
- containers will get [Unique Local Addresses (ULA)](https://en.wikipedia.org/wiki/Unique_local_address)
- the outgoing IPv6 address for containers will be the same as the one on the server
- traffic destined for the IPv6 address of the server will be forwarded to the containers that handle (and publish) that specific port
> [!WARNING]
> Without enabling this and assuming you have IPv6 `AAAA` DNS records pointing to the server (see [Configuring DNS records for IPv6](#configuring-dns-records-for-ipv6)), IPv6 traffic will still be handled, but NAT64 will be used instead of NAT66.
> As such, containers will only have an IPv4 address and all IPv6 traffic that reaches them will seem to originate from a local IP. Containers also won't be able to make outgoing (even cross-container) IPv6 requests.
To confirm connectivity, see the following other resources:
- [How do I check if my server has IPv6 connectivity?](#how-do-i-check-if-my-server-has-ipv6-connectivity)
- [How do I check outgoing IPv6 connectivity for containers?](#how-do-i-check-outgoing-ipv6-connectivity-for-containers)
- [How do I check incoming IPv6 connectivity for containers?](#how-do-i-check-incoming-ipv6-connectivity-for-containers)
- [How do I confirm if my container networks are IPv6-enabled?](#how-do-i-confirm-if-my-container-networks-are-ipv6-enabled)
- Ensure that the [Federation Tester](https://federationtester.matrix.org/) reports that your server is reachable over IPv6.
## Configuring DNS records for IPv6
[Enabling IPv6 support for the playbook](#enabling-ipv6-support-for-the-playbook) tells you how to prepare for IPv6 on the container (Docker) side.
For full public IPv6 connectivity (and not just IPv6 connectivity for containers inside the container networks) you also need to **ensure that your domain names** (e.g. `matrix.example.com` and others) have IPv6 (`AAAA`) DNS records pointing to the server's IPv6 address.
Also see the [Configuring DNS settings](configuring-dns.md) documentation page for more details.
### A note about old Docker
With our [default example configuration](../examples/vars.yml), the playbook manages Docker for you and installs a modern-enough version.
Docker versions newer than 27.0.1 enable IPv6 integration at the Docker daemon level out of the box. This still requires that networks are created with IPv6 support as described in the [Enabling IPv6 support for the playbook](#enabling-ipv6-support-for-the-playbook) section above.
**If you're on an old Docker version** (Docker 27.0.0 or older) for some reason, it's likely that your Docker installation is not enabled for IPv6 at all. In such a case:
- if Docker is managed by the playbook, you can tell it to force-enable IPv6 via `devture_systemd_docker_base_ipv6_daemon_options_changing_enabled: true`
- if Docker is managed by you manually, you can add `{"experimental": true, "ip6tables": true}` to the Docker daemon options and restart the Docker service (`docker.service`).
### Frequently Asked Questions
#### How do I check if my server has IPv6 connectivity?
##### With curl
You can run `curl https://icanhazip.com` and see if it returns an [IPv6 address](https://en.wikipedia.org/wiki/IPv6_address) (an address with `:` characters in it, like `2001:db8:1234:5678::1`). If it does, then your server has IPv6 connectivity and prefers it over using IPv4. This is common.
If you see an IPv4 address instead (e.g. `1.2.3.4`), it may be that your server prefers IPv4 over IPv6 or that your network does not support IPv6. You can try forcing `curl` to use IPv6 by running `curl -6 https://icanhazip.com` and see if it returns an IPv6 address.
##### With other network utilities
You can run `ip -6 addr` to see if you have any IPv6 addresses assigned to your server, besides the link-local (`fe80::*`) addresses that everyone has (unless they have force-disabled IPv6 support on their system).
If you do have an IPv6 address, it's still worth [using curl](#with-curl) to confirm that your server can successfully make outgoing requests over IPv6.
#### What does the `devture_systemd_docker_base_ipv6_enabled` setting actually do?
The `devture_systemd_docker_base_ipv6_enabled` setting controls whether container networks will be created with IPv6 support.
Changing this setting subsequently requires manual work (deleting all container networks).
See [I've changed the `devture_systemd_docker_base_ipv6_enabled` setting, but it doesn't seem to have any effect](#i-ve-changed-the-devture_systemd_docker_base_ipv6_enabled-setting-but-it-doesn-t-seem-to-have-any-effect).
#### I've changed the `devture_systemd_docker_base_ipv6_enabled` setting, but it doesn't seem to have any effect.
If you're using an older Docker version (Docker 27.0.0 or older), see [A note about old Docker](#a-note-about-old-docker).
If you've previously installed with one `devture_systemd_docker_base_ipv6_enabled` value and then changed it to another, you need to:
- stop all services (`just stop-all`)
- delete all container networks on the server: `docker network rm $(docker network ls -q)`
- re-run the playbook fully: `just install-all`
#### How do I confirm if my container networks are IPv6-enabled?
You can list container networks by running `docker network ls` on the server.
For each container network (e.g. `matrix-homeserver`), you can check if it has IPv6 connectivity by running a command like this: `docker network inspect matrix-homeserver`.
Ensure that there's an IPv6 subnet/gateway in the `IPAM.Config` section. If yes, you may wish to proceed with [How do I check outgoing IPv6 connectivity for containers?](#how-do-i-check-outgoing-ipv6-connectivity-for-containers)
If there's no IPv6 subnet/gateway in the `IPAM.Config` section, this container network was not created with IPv6 support.
See [I've changed the `devture_systemd_docker_base_ipv6_enabled` setting, but it doesn't seem to have any effect](#i-ve-changed-the-devture_systemd_docker_base_ipv6_enabled-setting-but-it-doesn-t-seem-to-have-any-effect).
#### How do I check outgoing IPv6 connectivity for containers?
```sh
docker run --rm --network=matrix-homeserver quay.io/curl/curl:latest curl -6 https://icanhazip.com
```
💡 This one-off container is connected to the `matrix-homeserver` container network, not to the default Docker bridge network. The default Docker `bridge` network does not have IPv6 connectivity by default (yet) and is not influenced by the `devture_systemd_docker_base_ipv6_enabled` setting, so using that network (by omitting `--network=..` from the command above) will not show an IPv6 address
✅ If this command returns an IPv6 address, you're all good.
❌ If this command doesn't return an IPv6 address, it may be that:
- your container network does not have IPv6 connectivity. See [How do I confirm if my container networks are IPv6-enabled?](#how-do-i-confirm-if-my-container-networks-are-ipv6-enabled) for more details.
- your server does not have IPv6 connectivity. See [How do I check if my server has IPv6 connectivity?](#how-do-i-check-if-my-server-has-ipv6-connectivity) for more details. If you do have IPv6 connectivity, then the issue is with Docker's IPv6 configuration. Otherwise, you need to check your server's network configuration/firewall/routing and get back to configuring the playbook later on.
#### How do I check incoming IPv6 connectivity for containers?
Only containers that publish ports will be exposed (reachable) publicly on the server's own IPv6 address. Containers will not get their own individual public IPv6 address.
For this playbook, a commonly exposed container is the Traefik reverse-proxy container (unless [you're using your own webserver](./configuring-playbook-own-webserver.md)).
You can either do something like `curl -6 https://matrix.example.com` from an IPv6-enabled host (including the server itself) and see if it works.
An alternative is to use the [IPv6 Port Checker](https://port.tools/port-checker-ipv6/) with a hostname of `matrix.example.com` and a port of `443`.
💡 Trying to connect to `matrix.example.com` via IPv6 requires that you have already [configured the DNS records for IPv6](#configuring-dns-records-for-ipv6) as described above. If you wish to eliminate DNS as a potential issue, you can also try connecting to the server's own IPv6 address directly: `curl -6 -H 'Host: matrix.example.com' https://[2001:db8:1234:5678::1]` (we pass a `Host` header to tell Traefik which host we'd like it to serve).
#### Why enable IPv6 if my network doesn't support it yet?
Because when your network does get support for IPv6 later on (even if that's 5 years away), you won't have to change anything besides [configuring the DNS records for IPv6](#configuring-dns-records-for-ipv6).
#### Can I use a custom subnet for IPv6?
Not easily.
The playbook and the various roles only support passing an `enable_ipv6` flag (`true` or `false` value depending on the `devture_systemd_docker_base_ipv6_enabled` Ansible variable) when creating the Docker container networks.
There's no support for passing a custom subnet for IPv4 and IPv6. We let Docker auto-generate the subnets for us.
You can either create a Pull Request that adds support for this to the various playbook roles, or you can manually recreate the networks from the command-line (e.g. `docker network rm matrix-homeserver && docker network create --ipv6 --subnet=2001:db8:1234:5678::/64 matrix-homeserver`).
#### Can I use Global Unicast Addresses (GUA) for IPv6?
No. You cannot have GUA addresses where each container is individually addressable over the public internet.
The playbook only supports NAT66, which should be good enough for most use cases.
Having containers get IPv6 addresses from your own GUA subnet requires complex configuration (ndp-proxy, etc.) and is not supported.
You may find [this Reddit post](https://www.reddit.com/r/ipv6/comments/1alpzmb/comment/kphpw11/) interesting.
#### Is there a performance penalty to enabling IPv6 if the server/network doesn't support IPv6 connectivity?
Probably a tiny one, as services may try to make (unsuccessful) outgoing requests over IPv6.
In practice, it's probably negligible.

51
docs/configuring-playbook-alertmanager-receiver.md
View File

@ -1,11 +1,3 @@
<!--
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2025 MDAD project contributors
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Prometheus Alertmanager integration via matrix-alertmanager-receiver (optional)
The playbook can install and configure the [matrix-alertmanager-receiver](https://github.com/metio/matrix-alertmanager-receiver) service for you. It's a [client](https://prometheus.io/docs/alerting/latest/clients/) for Prometheus' [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/), allowing you to deliver alerts to Matrix rooms.
@ -34,8 +26,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.alertma
The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
> [!WARNING]
> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
### Join to rooms as the bot manually
@ -45,12 +36,6 @@ For each new room you would like the bot to deliver alerts to, invite the bot to
Then, log in as the bot using any Matrix client of your choosing, accept the room invitation from the bot's account, and log out.
## Adjusting DNS records (optional)
By default, this playbook installs matrix-alertmanager-receiver on the `matrix.` subdomain, at the `/matrix-alertmanager-receiver` path (https://matrix.example.com/matrix-alertmanager-receiver). 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-matrix-alertmanager-receiver-url-optional) for details about DNS configuration.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
@ -74,11 +59,15 @@ matrix_alertmanager_receiver_config_matrix_room_mapping:
some-room-name: "!qporfwt:{{ matrix_domain }}"
```
### Adjusting the matrix-alertmanager-receiver URL (optional)
See `roles/custom/matrix-alertmanager-receiver/defaults/main.yml` for additional configuration variables.
### Adjusting the matrix-alertmanager-receiver URL
By default, this playbook installs matrix-alertmanager-receiver on the `matrix.` subdomain, at the `/matrix-alertmanager-receiver` path (https://matrix.example.com/matrix-alertmanager-receiver). 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.
By tweaking the `matrix_alertmanager_receiver_hostname` and `matrix_alertmanager_receiver_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
@ -86,18 +75,13 @@ matrix_alertmanager_receiver_hostname: alertmanager.example.com
matrix_alertmanager_receiver_path_prefix: /
```
If you've changed the default hostname, you may need to create a CNAME record for the matrix-alertmanager-receiver domain (`alertmanager.example.com`), which targets `matrix.example.com`.
## Adjusting DNS records
When setting, replace `example.com` with your own.
If you've changed the default hostname, **you may need to adjust your DNS** records to point the matrix-alertmanager-receiver domain to the Matrix server.
### Extending the configuration
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
There are some additional things you may wish to configure about the component.
Take a look at:
- `roles/custom/matrix-alertmanager-receiver/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-alertmanager-receiver/templates/config.yaml.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_alertmanager_receiver_configuration_extension_yaml` variable
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
@ -138,16 +122,3 @@ route:
```
where `URL_HERE` looks like `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name` or `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!qporfwt:example.com`.
## 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-alertmanager-receiver`.
### Increase logging verbosity
The default logging level for this component is `info`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Valid values: error, warn, info, debug
matrix_alertmanager_receiver_container_process_argument_log_level: debug
```

23
docs/configuring-playbook-appservice-double-puppet.md
View File

@ -1,17 +1,10 @@
<!--
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Appservice Double Puppet (optional)
The playbook can install and configure the Appservice Double Puppet service for you. It is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
Appservice Double Puppet is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
This is useful for performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) via the appservice method. The service is an implementation of this approach.
This is useful for performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) via the [appservice method](https://docs.mau.fi/bridges/general/double-puppeting.html#appservice-method-new). The Appservice Double Puppet service is an implementation of this approach.
Previously, bridges supported performing double-puppeting with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method.
Previously, bridges supported performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method.
## Adjusting the playbook configuration
@ -21,14 +14,6 @@ To enable the Appservice Double Puppet service, add the following configuration
matrix_appservice_double_puppet_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the service.
Take a look at:
- `roles/custom/matrix-appservice-double-puppet/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_double_puppet_registration_configuration_extension_yaml` variable
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -48,4 +33,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
Installing the service will automatically enable double puppeting for all bridges that support double puppeting via the appservice method.
When enabled, double puppeting will automatically be enabled for all bridges that support double puppeting via the appservice method.

42
docs/configuring-playbook-appservice-draupnir-for-all.md
View File

@ -1,10 +1,3 @@
<!--
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 MDAD project contributors
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Draupnir for All/D4A (optional)
The playbook can install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation tool for you in appservice mode.
@ -31,12 +24,19 @@ The playbook does not create a management room for your Main Draupnir. You **nee
Note that the room must be unencrypted.
The management room has to be given an alias, and your bot has to be invited to the room.
<!-- TODO: enable Pantalaimon as configuring-playbook-bot-draupnir.md -->
The management room has to be given an alias and be public when you are setting up the bot for the first time as the bot does not differentiate between invites and invites to the management room.
This management room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element clients call this powerlevel.
> [!WARNING]
> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
As noted in the Draupnir install instructions the control room is sensitive. **Anyone in this room can control the bot so it is important that you only invite trusted users to this room.**
### Set an alias to the management room
Next, set an alias to the management room.
This alias can be anything you want. However, for increased security during the setup phase, it is recommended to make this alias be a random string. When it has been locked down after setup phase, you can give your room a secondary human readable alias.
## Adjusting the playbook configuration
@ -45,28 +45,24 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
```yaml
matrix_appservice_draupnir_for_all_enabled: true
matrix_appservice_draupnir_for_all_config_adminRoom: "MANAGEMENT_ROOM_ALIAS_HERE"
matrix_appservice_draupnir_for_all_master_control_room_alias: "MANAGEMENT_ROOM_ALIAS_HERE"
```
### Extending the configuration
There are some additional things you may wish to configure about the component.
You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable.
Take a look at:
- `roles/custom/matrix-appservice-draupnir-for-all/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_draupnir_for_all_configuration_extension_yaml` variable
For example, to change Draupnir's `protectAllJoinedRooms` option to `true`, add the following configuration to your `vars.yml` file:
For example, to change Draupnir's `protectAllJoinedRooms` option to `true`, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_appservice_draupnir_for_all_configuration_extension_yaml: |
matrix_appservice_draupnir_for_all_extension_yaml: |
# Your custom YAML configuration goes here.
# This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_configuration_yaml`).
# This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_yaml`).
#
# You can override individual variables from the default configuration, or introduce new ones.
#
# If you need something more special, you can take full control by
# completely redefining `matrix_appservice_draupnir_for_all_configuration_yaml`.
# completely redefining `matrix_appservice_draupnir_for_all_yaml`.
protectAllJoinedRooms: true
```
@ -84,11 +80,13 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
<!-- 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
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
**Notes**:
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
- 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.
@ -105,7 +103,7 @@ Draupnir for all includes several security measures like that it only allows use
The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297))
To allow users or whole homeservers you type /plain !admin allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
To allow users or whole homeservers you type /plain @draupnir-main:example.com allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
### How to provision a D4A once you are allowed to

94
docs/configuring-playbook-backup-borg.md
View File

@ -1,19 +1,87 @@
<!--
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 - 2025 Nikita Chernyi
SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
SPDX-FileCopyrightText: 2022 MDAD project contributors
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up BorgBackup (optional)
The playbook can install and configure [BorgBackup](https://www.borgbackup.org/) (short: Borg) with [borgmatic](https://torsion.org/borgmatic/) for you.
BorgBackup is a deduplicating backup program with optional compression and encryption. That means your daily incremental backups can be stored in a fraction of the space and is safe whether you store it at home or on a cloud service.
The [Ansible role for BorgBackup](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg) is developed and maintained by [the MASH (mother-of-all-self-hosting) project](https://github.com/mother-of-all-self-hosting). For details about configuring BorgBackup, you can check them via:
- 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg/blob/main/docs/configuring-backup-borg.md) online
- 📁 `roles/galaxy/backup_borg/docs/configuring-backup-borg.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
You will need a remote server where BorgBackup will store the backups. There are hosted, BorgBackup compatible solutions available, such as [BorgBase](https://www.borgbase.com).
The backup will run based on `backup_borg_schedule` var (systemd timer calendar), default: 4am every day.
By default, if you're using the integrated Postgres database server (as opposed to [an external Postgres server](configuring-playbook-external-postgres.md)), backups with BorgBackup will also include dumps of your Postgres database. An alternative solution for backing up the Postgres database is [postgres backup](configuring-playbook-postgres-backup.md). If you decide to go with another solution, you can disable Postgres-backup support for BorgBackup using the `backup_borg_postgresql_enabled` variable.
**Note**: the component is not managed by this repository but its [own repository](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg).
## Prerequisites
1. If you do not disable Postgres-backup support, make sure that the Postgres version of your homeserver's database is compatible with borgmatic.
2. Create a new SSH key:
```sh
ssh-keygen -t ed25519 -N '' -f matrix-borg-backup -C matrix
```
This can be done on any machine and you don't need to place the key in the `.ssh` folder. It will be added to the Ansible config later.
3. Add the **public** part of this SSH key (the `matrix-borg-backup.pub` file) to your BorgBackup provider/server:
If you plan to use a hosted solution, follow their instructions. If you have your own server, copy the key over:
```sh
# example to append the new PUBKEY contents, where:
# PUBKEY is path to the public key,
# USER is a ssh user on a provider / server
# HOST is a ssh host of a provider / server
cat PUBKEY | ssh USER@HOST 'dd of=.ssh/authorized_keys oflag=append conv=notrunc'
```
## Adjusting the playbook configuration
Minimal working configuration (`inventory/host_vars/matrix.example.com/vars.yml`) to enable BorgBackup:
```yaml
backup_borg_enabled: true
backup_borg_location_repositories:
- ssh://USER@HOST/./REPO
backup_borg_storage_encryption_passphrase: "PASSPHRASE"
backup_borg_ssh_key_private: |
-----BEGIN OPENSSH PRIVATE KEY-----
TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZW
xpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRv
bG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3
RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXgg
ZWEgY29tbW9kbyBjb25zZXF1YXQuIA==
-----END OPENSSH PRIVATE KEY-----
```
where:
* USER - SSH user of a provider/server
* HOST - SSH host of a provider/server
* REPO - BorgBackup repository name, it will be initialized on backup start, eg: `matrix`, regarding Syntax see [Remote repositories](https://borgbackup.readthedocs.io/en/stable/usage/general.html#repository-urls)
* PASSPHRASE - passphrase used for encrypting backups. You can create one with a command like `pwgen -s 64 1`.
* PRIVATE KEY - the content of the **private** part of the SSH key you created before. The whole key (all of its belonging lines) under `backup_borg_ssh_key_private` needs to be indented with 2 spaces
To backup without encryption, add `backup_borg_encryption: 'none'` to your vars. This will also enable the `backup_borg_unknown_unencrypted_repo_access_is_ok` variable.
`backup_borg_location_source_directories` defines the list of directories to back up: it's set to `{{ matrix_base_data_path }}` by default, which is the base directory for every service's data, such as Synapse, Postgres and the bridges. You might want to exclude certain directories or file patterns from the backup using the `backup_borg_location_exclude_patterns` variable.
Check the [backup_borg role](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg)'s [defaults/main.yml](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg/blob/main/defaults/main.yml) file for the full list of available options.
## Installing
After configuring the playbook, run it 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.
## Manually start a backup
For testing your setup it can be helpful to not wait until 4am. If you want to run the backup immediately, log onto the server and run `systemctl start matrix-backup-borg`. This will not return until the backup is done, so possibly a long time. Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.

7
docs/configuring-playbook-base-domain-serving.md
View File

@ -1,10 +1,3 @@
<!--
SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Serving the base domain (optional)
By default, this playbook sets up services on your Matrix server (`matrix.example.com`), but has it configured so that it presents itself as the base domain (`example.com`). To have this server officially be responsible for Matrix services for the base domain (`example.com`), you need to set up server delegation / redirection.

46
docs/configuring-playbook-bot-baibot.md
View File

@ -1,10 +1,3 @@
<!--
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up baibot (optional)
<p align="center">
@ -85,7 +78,7 @@ To specify who is considered a bot [👮‍♂️ Administrator](https://github.
If `matrix_admin` is already configured in your `vars.yml` configuration, you can skip this section.
**If necessary**, add the following configuration to your `vars.yml` file:
**If necessary**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Uncomment to add one or more admins to this bridge:
@ -94,7 +87,7 @@ If `matrix_admin` is already configured in your `vars.yml` configuration, you ca
# - "@*:example.com"
# - "@admin:example.net"
#
# … unless you've made yourself an admin of all bots/bridges like this:
# .. unless you've made yourself an admin of all bots/bridges like this:
#
# matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
```
@ -114,7 +107,7 @@ Configuring `matrix_bot_baibot_config_initial_global_config_user_patterns` is op
**Note**: Once initially configured, the allowed users list **cannot be managed via Ansible anymore**. It can only be managed subsequently via bot commands.
**If necessary**, add the following configuration to your `vars.yml` file:
**If necessary**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Uncomment and adjust the bot users if necessary:
@ -130,7 +123,7 @@ Configuring `matrix_bot_baibot_config_initial_global_config_user_patterns` is op
You are **not required** to define agents [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration) via Ansible. **To get started quickly**, you can **skip this section and define agents at runtime via chat commands** (following the bot's guidance).
Privileged users (like the [👮‍♂️ Administrator](#️-administrator-configuration), but potentially others too — see the upstream [🔒 access](https://github.com/etkecc/baibot/blob/main/docs/access.md) documentation) can **define agents dynamically at any time** via chat commands.
Privileged users (like the [👮‍♂️ Administrator](#️-administrator-configuration), but potentially others too - see the upstream [🔒 access](https://github.com/etkecc/baibot/blob/main/docs/access.md) documentation) can **define agents dynamically at any time** via chat commands.
The Ansible role includes preset variables for easily enabling some [🤖 agents](https://github.com/etkecc/baibot/blob/main/docs/agents.md) on various [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md) (e.g. OpenAI, etc).
@ -153,13 +146,15 @@ matrix_bot_baibot_config_agents_static_definitions_anthropic_enabled: true
matrix_bot_baibot_config_agents_static_definitions_anthropic_config_api_key: "YOUR_API_KEY_HERE"
# Uncomment and adjust this part if you'd like to use another text-generation agent
# If you'd like to use another text-generation agent, uncomment and adjust:
# matrix_bot_baibot_config_agents_static_definitions_anthropic_config_text_generation_model_id: claude-3-5-sonnet-20240620
# The playbook defines a default prompt for all statically-defined agents.
# You can adjust it in the `matrix_bot_baibot_config_agents_static_definitions_prompt` variable,
# or you can adjust it below only for the Anthropic agent.
# matrix_bot_baibot_config_agents_static_definitions_anthropic_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
# See `defaults/main.yml` in the baibot role for more configuration options.
```
If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
@ -189,6 +184,8 @@ matrix_bot_baibot_config_agents_static_definitions_groq_config_text_generation_m
#
# matrix_bot_baibot_config_agents_static_definitions_groq_config_speech_to_text_enabled: true
# matrix_bot_baibot_config_agents_static_definitions_groq_config_speech_to_text_model_id: whisper-large-v3
# See `defaults/main.yml` in the baibot role for more configuration options.
```
Because this is a [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration)-defined agent, it will be given a `static/` ID prefix and will be named `static/groq`.
@ -215,6 +212,8 @@ matrix_bot_baibot_config_agents_static_definitions_mistral_config_api_key: "YOUR
# Uncomment and adjust this part if you're not happy with these defaults:
# matrix_bot_baibot_config_agents_static_definitions_mistral_config_text_generation_model_id: mistral-large-latest
# See `defaults/main.yml` in the baibot role for more configuration options.
```
Because this is a [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration)-defined agent, it will be given a `static/` ID prefix and will be named `static/mistral`.
@ -243,6 +242,8 @@ matrix_bot_baibot_config_agents_static_definitions_openai_config_api_key: "YOUR_
# If you'd like to use another text-generation agent, uncomment and adjust:
# matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_model_id: gpt-4o
# See `defaults/main.yml` in the baibot role for more configuration options.
```
Because this is a [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration)-defined agent, it will be given a `static/` ID prefix and will be named `static/openai`.
@ -257,7 +258,7 @@ You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot
This provider allows you to use OpenAI-compatible API services like [OpenRouter](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openrouter), [Together AI](https://github.com/etkecc/baibot/blob/main/docs/providers.md#together-ai), etc.
Some of these popular services already have **shortcut** providers (see [supported providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md#supported-providers) leading to this one behind the scenes — this make it easier to get started.
Some of these popular services already have **shortcut** providers (see [supported providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md#supported-providers) leading to this one behind the scenes - this make it easier to get started.
As of this moment, the playbook does not include presets for any of these services, so you'll need to [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset).
@ -312,7 +313,7 @@ Because these are [statically](https://github.com/etkecc/baibot/blob/main/docs/c
💡 To figure out what to put in the `config` section, refer to the [☁️ provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md) page, which contains **sample configuration YAML for each provider**.
As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md), defining them means they exist. To actually make use of them, they need to be configured as handlers globally or in a specific room — see [Mixing & matching models](https://github.com/etkecc/baibot/blob/main/docs/features.md#mixing--matching-models).
As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md), defining them means they exist. To actually make use of them, they need to be configured as handlers globally or in a specific room - see [Mixing & matching models](https://github.com/etkecc/baibot/blob/main/docs/features.md#mixing--matching-models).
💡 You may also wish to use these new agents for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
@ -361,15 +362,6 @@ matrix_bot_baibot_config_initial_global_config_handler_image_generation: null
**Note**: these are initial defaults for the bot's global configuration. As such, changing any of these values subsequently has no effect on the bot's behavior. **Once initially configured the global configuration cannot be managed Ansible**, but only via bot commands.
### Extending the configuration
There are some additional things you may wish to configure about the bot.
Take a look at:
- `roles/custom/matrix-bot-baibot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bot-baibot/templates/config.yaml.j2` for the bot's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bot_baibot_configuration_extension_yaml` variable
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -403,13 +395,11 @@ Send `!bai help` to the bot in the room to see the available commands.
You can also refer to the upstream [baibot](https://github.com/etkecc/baibot) project's documentation.
## Troubleshooting
## Debugging
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-bot-baibot`.
As with all other services, you can find service logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by running something like `journalctl -fu matrix-bot-baibot`
### Increase logging verbosity
The default logging level for this service is `info`. If you want to increase the verbosity to `debug` (or even `trace`), add the following configuration to your `vars.yml` file and re-run the playbook:
The default logging level for this service is `info`, but you can increase it to `debug` (or even `trace`) with the following additional configuration:
```yaml
# Adjust the bot's own logging level.

48
docs/configuring-playbook-bot-buscarron.md
View File

@ -1,25 +1,9 @@
<!--
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 Nikita Chernyi
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Buscarron (optional)
The playbook can install and configure [Buscarron](https://github.com/etkecc/buscarron) for you.
Buscarron is bot that receives HTTP POST submissions of web forms and forwards them to a Matrix room.
See the project's [documentation](https://github.com/etkecc/buscarron/blob/main/README.md) to learn what it does and why it might be useful to you.
## Adjusting DNS records
By default, this playbook installs Buscarron on the `buscarron.` subdomain (`buscarron.example.com`) and requires you to create a CNAME record for `buscarron`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
## Adjusting the playbook configuration
To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -45,11 +29,13 @@ matrix_bot_buscarron_forms:
matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (with wildcards support) that should be rejected automatically
```
### Adjusting the Buscarron URL (optional)
### Adjusting the Buscarron URL
By default, this playbook installs Buscarron on the `buscarron.` subdomain (`buscarron.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_bot_buscarron_hostname` and `matrix_bot_buscarron_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
@ -60,18 +46,14 @@ matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
matrix_bot_buscarron_path_prefix: /buscarron
```
After changing the domain, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
By default, you will need to create a CNAME record for `buscarron`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
### Extending the configuration
There are some additional things you may wish to configure about the bot.
Take a look at:
- `roles/custom/matrix-bot-buscarron/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:
@ -113,14 +95,4 @@ Here is an example for the `contact` form:
If you get banned, you'd need to restart the process by running the playbook with `--tags=start` or running `systemctl restart matrix-bot-buscarron` on the server.
## 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-bot-buscarron`.
### Increase logging verbosity
The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
matrix_bot_buscarron_loglevel: DEBUG
```
You can also refer to the upstream [documentation](https://github.com/etkecc/buscarron).

27
docs/configuring-playbook-bot-chatgpt.md
View File

@ -1,21 +1,11 @@
<!--
SPDX-FileCopyrightText: 2023 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2023 MDAD project contributors
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up matrix-bot-chatgpt (optional, unmaintained)
**Note**: [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) is now an archived (**unmaintained**) project. Talking to ChatGPT (and many other LLM providers) can happen via the much more featureful [baibot](https://github.com/etkecc/baibot), which can be [installed using this playbook](configuring-playbook-bot-baibot.md). Consider using that bot instead of this one.
**Note**: [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) is now an archived (**unmaintained**) project. Talking to ChatGPT (and many other LLM providers) can happen via the much more featureful [baibot](https://github.com/etkecc/baibot), which can be installed using [this playbook](configuring-playbook-bot-baibot.md). Consider using that bot instead of this one.
The playbook can install and configure [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) for you.
Talk to [ChatGPT](https://openai.com/blog/chatgpt/) via your favourite Matrix client!
See the project's [documentation](https://github.com/matrixgpt/matrix-chatgpt-bot/blob/main/README.md) to learn what it does and why it might be useful to you.
## Prerequisites
### Obtain an OpenAI API key
@ -38,8 +28,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.chatgpt
The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
> [!WARNING]
> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
To make sure the bot can read encrypted messages, it will need an encryption key, just like any other new user. While obtaining the access token, follow the prompts to setup a backup key. More information can be found in the [Element documentation](https://element.io/help#encryption6).
@ -62,14 +51,6 @@ matrix_bot_chatgpt_matrix_access_token: 'ACCESS_TOKEN_HERE'
matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a large language model trained by OpenAI.'
```
### Extending the configuration
There are some additional things you may wish to configure about the bot.
Take a look at:
- `roles/custom/matrix-bot-chatgpt/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -93,6 +74,4 @@ To use the bot, invite it to the room you specified on your `vars.yml` file (`/i
After the bot joins the room, you can send a message to it. When you do so, use the prefix if you configured it or mention the bot.
## 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-bot-chatgpt`.
You can also refer to the upstream [documentation](https://github.com/matrixgpt/matrix-chatgpt-bot).

224
docs/configuring-playbook-bot-draupnir.md
View File

@ -1,165 +1,143 @@
<!--
SPDX-FileCopyrightText: 2023 - 2025 MDAD project contributors
SPDX-FileCopyrightText: 2023 Kim Brose
SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Draupnir (optional)
The playbook can install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation bot for you.
See the project's [documentation](https://the-draupnir-project.github.io/draupnir-documentation/) to learn what it does and why it might be useful to you.
See the project's [documentation](https://github.com/the-draupnir-project/Draupnir/blob/main/README.md) to learn what it does and why it might be useful to you.
This documentation page is about installing Draupnir in bot mode. As an alternative, you can run a multi-instance Draupnir deployment by installing [Draupnir in appservice mode](./configuring-playbook-appservice-draupnir-for-all.md) (called Draupnir-for-all) instead.
If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
If your migrating from Mjolnir skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
## Prerequisites
### Create a management room
### Register the bot account
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.
The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
> [!WARNING]
> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
It is possible to make the management room encrypted (E2EE). If doing so, then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`.
## End-to-End Encryption support
Decide whether you want to support having an encrypted management room or not. Draupnir can still protect encrypted rooms without encryption support enabled.
Refer to Draupnir's [documentation](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#protecting-encrypted-rooms) for more details about why you might want to care about encryption support for protected rooms.
### Disable Pantalaimon for Draupnir (since v2.0.0; optional)
It is known that running Draupnir along with Pantalaimon breaks all workflows that involve answering prompts with reactions.
If you are updating Draupnir from v1.x.x and have enabled Pantalaimon for it, you can disable Pantalaimon in favor of the native E2EE support. To disable Pantalaimon, remove the configuration `matrix_bot_draupnir_pantalaimon_use: true` from your `vars.yml` file.
**Note**: because the management room is still encrypted, disabling it without enabling the native E2EE support will break the management room.
### Native E2EE support
To enable the native E2EE support, you need to obtain an access token for Draupnir and set it on your `vars.yml` file.
Note that native E2EE requires a clean access token that has not touched E2EE so curl is recommended as a method to obtain it. **The access token obtained via Element Web does not work with it**. Refer to the documentation on [how to obtain an access token via curl](obtaining-access-tokens.md#obtain-an-access-token-via-curl).
To enable the native E2EE support, add the following configuration to your `vars.yml` file. Make sure to replace `CLEAN_ACCESS_TOKEN_HERE` with the access token you obtained just now.
```yaml
# Enables the native E2EE support
matrix_bot_draupnir_config_experimentalRustCrypto: true
# Access token which the bot will use for logging in.
# Comment out `matrix_bot_draupnir_login_native` when using this option.
matrix_bot_draupnir_config_accessToken: "CLEAN_ACCESS_TOKEN_HERE"
```
## Adjusting the playbook configuration
To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created earlier.
```yaml
# Enable Draupnir
matrix_bot_draupnir_enabled: true
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_draupnir_login: bot.draupnir
# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
# If creating the user on your own and using `matrix_bot_draupnir_config_accessToken` to login you can comment out this line.
matrix_bot_draupnir_password: PASSWORD_FOR_THE_BOT
# Comment out if using `matrix_bot_draupnir_config_experimentalRustCrypto: true` or `matrix_bot_draupnir_config_accessToken` to login.
matrix_bot_draupnir_login_native: true
matrix_bot_draupnir_config_managementRoom: "MANAGEMENT_ROOM_ID_HERE"
```
### Create and invite the bot to the management room
Before proceeding to the next step, run the playbook with the following command to create the bot user.
You can use the playbook to [register a new user](registering-users.md):
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
**Note**: the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
If you would like Draupnir to be able to deactivate users, move aliases, shutdown rooms, show abuse reports (see [below](#abuse-reports)), etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
Then, invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier.
### Obtain an access token
### Make sure the account is free from rate limiting (optional, recommended)
The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a highly recommended step. If you do not configure it, Draupnir performance will be degraded.**
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
### Make sure the account is free from rate limiting
If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a required step. If you do not configure it, Draupnir will crash.**
This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). They can be accessed both externally and internally.
**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints).
The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
#### Add the configuration
To expose the APIs publicly, add the following configuration to your `vars.yml` file:
To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file.
```yaml
matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
```
#### Obtain an access token for admin account
The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
Manual access to Synapse's Admin APIs requires an access token for a homeserver admin account. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints).
> [!WARNING]
> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
#### Run the `curl` command
To disable rate limiting, run the following command on systems that ship curl. Before running it, make sure to replace:
- `ADMIN_ACCESS_TOKEN_HERE` with the access token of the admin account
- `example.com` with your base domain
- `@bot.draupnir:example.com` with the MXID of your Draupnir bot user
To discharge rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.draupnir:example.com` with the MXID of your Draupnir:
```sh
curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit
curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit
```
**Notes**:
- This does not work on outdated Windows 10 as curl is not available there.
- Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally.
You can obtain an access token for a homeserver admin account in the same way as you can do so for Draupnir itself. If you have made Draupnir an admin, you can just use the Draupnir token.
### 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.
If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)).
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 Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`.
Finally invite the `@bot.draupnir:example.com` account you created earlier into the room.
## Adjusting the playbook configuration
To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`.
```yaml
# Enable Draupnir
matrix_bot_draupnir_enabled: true
matrix_bot_draupnir_management_room: "MANAGEMENT_ROOM_ID_HERE"
```
### End-to-End Encryption support
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).
#### 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.example.com/vars.yml` file (adapt to your needs):
```yaml
# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
matrix_pantalaimon_enabled: true
# Tell Draupnir to use Pantalaimon
matrix_bot_draupnir_pantalaimon_use: true
# User name and password for the bot you have created above. Required when using Pantalaimon.
matrix_bot_draupnir_pantalaimon_username: "bot.draupnir"
matrix_bot_draupnir_pantalaimon_password: "PASSWORD_FOR_THE_BOT"
```
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 }}"
```
#### 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.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
```yaml
matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE"
```
### Abuse Reports
Draupnir can receive reports in the management room.
Draupnir supports two methods to receive reports in the management room.
The bot can intercept the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver. If you are using Traefik, this playbook can set this up for you:
The first method intercepts the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver. If you are using traefik, this playbook can set this up for you:
```yaml
matrix_bot_draupnir_config_web_abuseReporting: true
matrix_bot_draupnir_abuse_reporting_enabled: true
```
<!--
NOTE: this is unsupported by the playbook due to the admin API being inaccessible from containers currently.
The other method polls an Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin (see [above](#register-the-bot-account)). To enable it, set `pollReports: true` on `vars.yml` file as below.
-->
### Extending the configuration
There are some additional things you may wish to configure about the bot.
You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable.
Take a look at:
- `roles/custom/matrix-bot-draupnir/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bot_draupnir_configuration_extension_yaml` variable
For example, to change Draupnir's `acceptInvitesFromSpace` option to `!qporfwt:example.com`, add the following configuration to your `vars.yml` file:
For example, to change Draupnir's `pollReports` option to `true`, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_bot_draupnir_configuration_extension_yaml: |
@ -170,15 +148,13 @@ matrix_bot_draupnir_configuration_extension_yaml: |
#
# If you need something more special, you can take full control by
# completely redefining `matrix_bot_draupnir_configuration_yaml`.
acceptInvitesFromSpace: "!qporfwt:example.com"
pollReports: true
```
### 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.
Note that Draupnir supports E2EE natively, so you can enable it instead of Pantalaimon. It is recommended to consult the instruction [here](#native-e2ee-support).
That is all you need to do due to that Draupnir can complete migration on its own.
## Installing
@ -190,9 +166,15 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
**Notes**:
`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.
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
- 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.
- If you change the Pantalaimon's password (`matrix_bot_draupnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_draupnir_pantalaimon_password` to let Pantalaimon know its new password.
## Usage
@ -254,7 +236,7 @@ You can also **turn on various built-in [protections](https://the-draupnir-proje
To **see which protections are available and which are enabled**, send a `!draupnir protections` command to the Management Room.
To **see the configuration options for a given protection**, send a `!draupnir protections show PROTECTION_NAME` (e.g. `!draupnir protections show JoinWaveShortCircuit`).
To **see the configuration options for a given protection**, send a `!draupnir config get PROTECTION_NAME` (e.g. `!draupnir config get JoinWaveShortCircuit`).
To **set a specific option for a given protection**, send a command like this: `!draupnir config set PROTECTION_NAME.OPTION VALUE` (e.g. `!draupnir config set JoinWaveShortCircuit.timescaleMinutes 30`).

48
docs/configuring-playbook-bot-go-neb.md
View File

@ -1,16 +1,6 @@
<!--
SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2021 Yannick Goossens
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2025 MDAD project contributors
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Go-NEB (optional, unmaintained)
**Note**: [Go-NEB](https://github.com/matrix-org/go-neb) is now an archived (**unmaintained**) project. We recommend not bothering with installing it. While not a 1:1 replacement, the bridge's author suggests taking a look at [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) as a replacement, which can also be [installed using this playbook](configuring-playbook-bridge-hookshot.md). Consider using that bot instead of this one.
**Note**: [Go-NEB](https://github.com/matrix-org/go-neb) is now an archived (**unmaintained**) project. We recommend not bothering with installing it. While not a 1:1 replacement, the bridge's author suggests taking a look at [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) as a replacement, which can also be installed using [this playbook](configuring-playbook-bridge-hookshot.md). Consider using that bot instead of this one.
The playbook can install and configure [Go-NEB](https://github.com/matrix-org/go-neb) for you.
@ -36,14 +26,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb
The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
> [!WARNING]
> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
## Adjusting DNS records
By default, this playbook installs Go-NEB on the `goneb.` subdomain (`goneb.example.com`) and requires you to create a CNAME record for `goneb`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
## Adjusting the playbook configuration
@ -211,34 +194,31 @@ matrix_bot_go_neb_services:
msg_type: "m.text" # Must be either `m.text` or `m.notice`
```
### Adjusting the Go-NEB URL (optional)
### Adjusting the Go-NEB URL
By default, this playbook installs Go-NEB on the `goneb.` subdomain (`goneb.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_bot_go_neb_hostname` and `matrix_bot_go_neb_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Go-NEB.
matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /go-neb subpath
# Expose under the /buscarron subpath
matrix_bot_go_neb_path_prefix: /go-neb
```
After changing the domain, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
By default, you will need to create a CNAME record for `goneb`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
### Extending the configuration
There are some additional things you may wish to configure about the bot.
Take a look at:
- `roles/custom/matrix-bot-go-neb/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bot-go-neb/templates/config.yaml.j2` for the bot's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bot_go_neb_configuration_extension_yaml` variable
## 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:
@ -265,7 +245,3 @@ Basic usage is like this: `!echo hi` or `!imgur puppies` or `!giphy matrix`
If you enabled the github_cmd service, send `!github help` to the bot in the room to see the available commands.
You can also refer to the upstream [Documentation](https://github.com/matrix-org/go-neb).
## 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-bot-go-neb`.

44
docs/configuring-playbook-bot-honoroit.md
View File

@ -1,11 +1,3 @@
<!--
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 MDAD project contributors
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Honoroit (optional)
The playbook can install and configure [Honoroit](https://github.com/etkecc/honoroit) for you.
@ -14,12 +6,6 @@ It's a bot you can use to setup **your own helpdesk on matrix**
See the project's [documentation](https://github.com/etkecc/honoroit/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 Honoroit on the `matrix.` subdomain, at the `/honoroit` path (https://matrix.example.com/honoroit). 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-honoroit-url-optional) for details about DNS configuration.
## Adjusting the playbook configuration
To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -37,11 +23,13 @@ matrix_bot_honoroit_password: PASSWORD_FOR_THE_BOT
matrix_bot_honoroit_roomid: "!qporfwt:{{ matrix_domain }}"
```
### Adjusting the Honoroit URL (optional)
### Adjusting the Honoroit URL
By default, this playbook installs Honoroit on the `matrix.` subdomain, at the `/honoroit` path (https://matrix.example.com/honoroit). 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.
By tweaking the `matrix_bot_honoroit_hostname` and `matrix_bot_honoroit_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
@ -49,17 +37,13 @@ matrix_bot_honoroit_hostname: honoroit.example.com
matrix_bot_honoroit_path_prefix: /
```
If you've changed the default hostname, you may need to create a CNAME record for the Honoroit domain (`honoroit.example.com`), which targets `matrix.example.com`.
## Adjusting DNS records
When setting, replace `example.com` with your own.
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Honoroit domain to the Matrix server.
### Extending the configuration
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
There are some additional things you may wish to configure about the bot.
Take a look at:
- `roles/custom/matrix-bot-honoroit/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
@ -89,15 +73,3 @@ After the bot joins the room, any Matrix user can send a message to it to start
Send `!ho help` to the bot in the room to see the available commands.
You can also refer to the upstream [documentation](https://github.com/etkecc/honoroit#features).
## 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-bot-honoroit`.
### Increase logging verbosity
If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
matrix_bot_honoroit_loglevel: 'DEBUG'
```

34
docs/configuring-playbook-bot-matrix-registration-bot.md
View File

@ -1,15 +1,3 @@
<!--
SPDX-FileCopyrightText: 2022 - 2023 Julian-Samuel Gebühr
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Erick Wibben
SPDX-FileCopyrightText: 2022 Kolja Lampe
SPDX-FileCopyrightText: 2023 - 2024 MDAD project contributors
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up matrix-registration-bot (optional)
The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
@ -41,15 +29,6 @@ matrix_synapse_registration_requires_token: true
The bot account will be created automatically.
### Extending the configuration
There are some additional things you may wish to configure about the bot.
Take a look at:
- `roles/custom/matrix-bot-matrix-registration-bot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bot-matrix-registration-bot/templates/config.yaml.j2` for the bridge's default configuration
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -84,16 +63,3 @@ To clean the cache (session & encryption data) after you changed the bot's usern
```sh
just run-tags bot-matrix-registration-bot-clean-cache
```
## 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-bot-matrix-registration-bot`.
### Increase logging verbosity
The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Valid values: ERROR, INFO, DEBUG
matrix_bot_matrix_registration_bot_logging_level: DEBUG
```

32
docs/configuring-playbook-bot-matrix-reminder-bot.md
View File

@ -1,11 +1,3 @@
<!--
SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 MDAD project contributors
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up matrix-reminder-bot (optional)
The playbook can install and configure [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for you.
@ -31,15 +23,6 @@ matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT
matrix_bot_matrix_reminder_bot_reminders_timezone: Europe/London
```
### Extending the configuration
There are some additional things you may wish to configure about the bot.
Take a look at:
- `roles/custom/matrix-bot-matrix-reminder-bot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bot-matrix-reminder-bot/templates/config.yaml.j2` for the bot's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bot_matrix_reminder_bot_configuration_extension_yaml` variable
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -70,18 +53,3 @@ Basic usage is like this: `!remindme in 2 minutes; This is a test`
Send `!help reminders` to the room to see the bot's help menu for additional commands.
You can also refer to the upstream [Usage documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage).
## 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-bot-matrix-reminder-bot`.
### Increase logging verbosity
The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
matrix_bot_matrix_reminder_bot_configuration_extension_yaml: |
logging:
# Valid values: ERROR, WARNING, INFO, DEBUG
level: DEBUG
```

71
docs/configuring-playbook-bot-maubot.md
View File

@ -1,14 +1,3 @@
<!--
SPDX-FileCopyrightText: 2022 - 2024 MDAD project contributors
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Fabio Bonelli
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up maubot (optional)
The playbook can install and configure [maubot](https://github.com/maubot/maubot) for you.
@ -17,12 +6,6 @@ After setting up maubot, you can use the web management interface to make it do
See the project's [documentation](https://docs.mau.fi/maubot/usage/basic.html) to learn what it does and why it might be useful to you.
## Adjusting DNS records (optional)
By default, this playbook installs maubot on the `matrix.` subdomain, at the `/_matrix/maubot/` path (https://matrix.example.com/_matrix/maubot/). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**.
If you wish to adjust it, see the section [below](#adjusting-the-maubot-url-optional) for details about DNS configuration.
## Adjusting the playbook configuration
To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -42,11 +25,13 @@ matrix_bot_maubot_admins:
You can add multiple admins. The admin accounts are only used to access the maubot administration interface.
### Adjusting the maubot URL (optional)
### Adjusting the maubot URL
By default, this playbook installs maubot on the `matrix.` subdomain, at the `/_matrix/maubot/` path (https://matrix.example.com/_matrix/maubot/). 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.
By tweaking the `matrix_bot_maubot_hostname` and `matrix_bot_maubot_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
@ -54,37 +39,13 @@ matrix_bot_maubot_hostname: maubot.example.com
matrix_bot_maubot_path_prefix: /
```
If you've changed the default hostname, you may need to create a CNAME record for the maubot domain (`maubot.example.com`), which targets `matrix.example.com`.
## Adjusting DNS records
When setting, replace `example.com` with your own.
If you've changed the default hostname, **you may need to adjust your DNS** records to point the maubot domain to the Matrix server.
### Extending the configuration
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
There are some additional things you may wish to configure about the bot.
Take a look at:
- `roles/custom/matrix-bot-maubot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bot-maubot/templates/config.yaml.j2` for the bot's default configuration
## Customizing the maubot container image
Certain [maubot plugins](https://plugins.mau.bot/) require additional dependencies to be installed.
You can customize the default maubot container image and install your own dependencies.
Example additional configuration for your `vars.yml` file:
```yaml
matrix_bot_maubot_container_image_customizations_enabled: true
# Adjust the Dockerfile and install ffmpeg.
#
matrix_bot_maubot_container_image_customizations_dockerfile_body_custom: |
RUN apk add --no-cache ffmpeg
```
Consult the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/) for more information about the syntax.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
@ -120,18 +81,4 @@ This can be done via `mbc login` then `mbc auth` (see the [maubot documentation]
Alternatively, you can refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). Be aware that you'd better use the **Obtain an access token via curl** method (not **Obtain an access token via Element Web**) as the latter will causes issues to your bot in encrypted rooms. Read [more](https://docs.mau.fi/maubot/usage/basic.html#creating-clients).
> [!WARNING]
> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
## 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-bot-maubot`.
### Increase logging verbosity
The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Valid values: CRITICAL, ERROR, WARNING, INFO, DEBUG
matrix_bot_maubot_logging_level: DEBUG
```
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.

82
docs/configuring-playbook-bot-mjolnir.md
View File

@ -1,14 +1,3 @@
<!--
SPDX-FileCopyrightText: 2021 - 2024 MDAD project contributors
SPDX-FileCopyrightText: 2021 Aaron Raimist
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Marko Weltzer
SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mjolnir (optional)
The playbook can install and configure the [Mjolnir](https://github.com/matrix-org/mjolnir) moderation bot for you.
@ -35,8 +24,7 @@ If you would like Mjolnir to be able to deactivate users, move aliases, shutdown
The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
> [!WARNING]
> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
### Make sure the account is free from rate limiting
@ -44,57 +32,37 @@ If your homeserver's implementation is Synapse, you will need to prevent it from
This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). They can be accessed both externally and internally.
**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints).
The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
#### Add the configuration
To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file.
```yaml
matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
```
#### Obtain an access token for admin account
The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
Manual access to Synapse's Admin APIs requires an access token for a homeserver admin account. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). If you have made Mjolnir an admin, you can just use the Mjolnir token.
**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints).
> [!WARNING]
> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
#### Run the `curl` command
To disable rate limiting, run the following command on systems that ship curl. Before running it, make sure to replace:
- `ADMIN_ACCESS_TOKEN_HERE` with the access token of the admin account
- `example.com` with your base domain
- `@bot.mjolnir:example.com` with the MXID of your Mjolnir bot user
To discharge rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.mjolnir:example.com` with the MXID of your Mjolnir:
```sh
curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit
curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit
```
**Notes**:
- This does not work on outdated Windows 10 as curl is not available there.
- Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally.
You can obtain an access token for a homeserver admin account in the same way as you can do so for Mjolnir itself. If you have made Mjolnir an admin, you can just use the Mjolnir token.
### 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.
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.
> [!WARNING]
> 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](#configuration-with-e2ee-support)).
It is possible to make the management room encrypted (E2EE). If doing so, then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)).
Once you have created the room you need to copy the room ID so you can specify it on your `vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`.
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 Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`.
Finally invite the `@bot.mjolnir:example.com` account you created earlier into the room.
## Adjusting the playbook configuration
To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created just now.
To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`.
```yaml
# Enable Mjolnir
@ -113,7 +81,7 @@ To support E2EE, Mjolnir needs to [use Pantalaimon](configuring-playbook-pantala
When using Pantalaimon, Mjolnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
Add the following configuration to your `vars.yml` file (adapt to your needs):
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
```yaml
# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
@ -143,7 +111,7 @@ matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_u
When NOT using Pantalaimon, Mjolnir does not log in by itself and you must give it an access token for its bot account.
Add the following configuration to your `vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
```yaml
matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_HERE"
@ -151,7 +119,7 @@ matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_HERE"
### Adding Mjolnir synapse antispam module (optional)
To enable Mjolnir synapse antispam module, add the following configuration to your `vars.yml` file (adapt to your needs):
To enable Mjolnir synapse antispam module, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
```yaml
matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled: true
@ -163,13 +131,9 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
### Extending the configuration
There are some additional things you may wish to configure about the bot.
You can configure additional options by adding the `matrix_bot_mjolnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.
Take a look at:
- `roles/custom/matrix-bot-mjolnir/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bot_mjolnir_configuration_extension_yaml` variable
For example, to change Mjolnir's `recordIgnoredInvites` option to `true`, add the following configuration to your `vars.yml` file:
For example, to change Mjolnir's `recordIgnoredInvites` option to `true`, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_bot_mjolnir_configuration_extension_yaml: |
@ -205,17 +169,3 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
You can refer to the upstream [documentation](https://github.com/matrix-org/mjolnir) for additional ways to use and configure Mjolnir. Check out their [quickstart guide](https://github.com/matrix-org/mjolnir#quickstart-guide) for some basic commands you can give to the bot.
## 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-bot-mjolnir`.
### Increase logging verbosity
The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Valid values: ERROR, WARN, INFO, DEBUG
matrix_bot_mjolnir_configuration_extension_yaml: |
logLevel: "DEBUG"
```

37
docs/configuring-playbook-bridge-appservice-discord.md
View File

@ -1,12 +1,3 @@
<!--
SPDX-FileCopyrightText: 2019 - 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 - 2023 MDAD project contributors
SPDX-FileCopyrightText: 2022 Jim Myhrberg
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Appservice Discord bridging (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.
@ -37,15 +28,6 @@ matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
# use_appservice_legacy_authorization: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-appservice-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-appservice-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_discord_configuration_extension_yaml` variable
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -65,7 +47,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Self-Service Bridging (Manual)
Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. To enable it, add the following configuration to your `vars.yml` file:
Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. To enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_appservice_discord_bridge_enableSelfServiceBridging: true
@ -91,7 +73,7 @@ Through portal bridging, Matrix rooms will automatically be created by the bot a
All Matrix rooms created this way are **listed publicly** by default, and you will not have admin permissions to change this. To get more control, [make yourself a room Administrator](#getting-administrator-access-in-a-portal-bridged-room). You can then unlist the room from the directory and change the join rules.
To disable portal bridging, add the following configuration to your `vars.yml` file:
To disable portal bridging, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_appservice_discord_bridge_disablePortalBridging: true
@ -117,18 +99,3 @@ There's the Discord bridge's guide for [setting privileges on bridge managed roo
docker exec -it matrix-appservice-discord \
/bin/sh -c 'cp /cfg/registration.yaml /tmp/discord-registration.yaml && cd /tmp && node /build/tools/adminme.js -c /cfg/config.yaml -m "!qporfwt:example.com" -u "@alice:example.com" -p 100'
```
## 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-appservice-discord`.
### Increase logging verbosity
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file (adapt to your needs) and re-run the playbook:
```yaml
matrix_appservice_discord_configuration_extension_yaml: |
logging:
# What level should the logger output to the console at.
console: "info" # Valid values: silent, error, warn, http, info, verbose, silly
```

38
docs/configuring-playbook-bridge-appservice-irc.md
View File

@ -1,12 +1,3 @@
<!--
SPDX-FileCopyrightText: 2019 - 2021 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 MDAD project contributors
SPDX-FileCopyrightText: 2020 Lee Verberne
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Appservice IRC bridging (optional)
**Note**: bridging to [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) can also happen via the [Heisenbridge](configuring-playbook-bridge-heisenbridge.md) bridge supported by the playbook.
@ -69,15 +60,6 @@ matrix_appservice_irc_ircService_servers:
lineLimit: 3
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-appservice-irc/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-appservice-irc/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_irc_configuration_extension_yaml` variable
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -98,23 +80,3 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
To use the bridge, you need to start a chat with `@irc_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
## 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-appservice-irc`.
### Configuring for logging
The default logging level for this component is `debug`, and the log is output to the console only. If you want to change the verbosity or enable logging to a file, add the following configuration to your `vars.yml` file (adapt to your needs) and re-run the playbook:
```yaml
matrix_appservice_irc_configuration_extension_yaml: |
logging:
# Level to log on console/logfile.
# Valid values: error, warn, info, debug
level: "debug"
# The file location to log to. This is relative to the project directory.
logfile: "debug.log"
# The file location to log errors to. This is relative to the project directory.
errfile: "errors.log"
```

52
docs/configuring-playbook-bridge-appservice-kakaotalk.md
View File

@ -1,30 +1,16 @@
<!--
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 MDAD project contributors
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Appservice Kakaotalk bridging (optional)
The playbook can install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) for you, for bridging to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG). This bridge is based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code.
The playbook can install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) for you. `matrix-appservice-kakaotalk` is a bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code.
⚠️ **Warning**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
See the project's [documentation](https://src.miscworks.net/fair/matrix-appservice-kakaotalk/src/branch/master/README.md) to learn what it does and why it might be useful to you.
> [!WARNING]
> There have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
## Prerequisite (optional)
### Enable Shared Secret Auth
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -34,7 +20,9 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_appservice_kakaotalk_enabled: true
```
### Extending the configuration
You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
### Additional configuration
There are some additional things you may wish to configure about the bridge.
@ -64,16 +52,26 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
To use the bridge, you need to start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You then need to send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
## Troubleshooting
### 💡 Set up Double Puppeting
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-appservice-kakaotalk`.
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
### Increase logging verbosity
To set it up, you have 2 ways of going about it.
The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
#### Method 1: automatically, by enabling Shared Secret Auth
```yaml
matrix_appservice_kakaotalk_logging_level: DEBUG
```
The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature

35
docs/configuring-playbook-bridge-appservice-slack.md
View File

@ -1,14 +1,3 @@
<!--
SPDX-FileCopyrightText: 2019 - 2022 MDAD project contributors
SPDX-FileCopyrightText: 2020 Udo Rader
SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2021 Joel Bennett
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Fabio Bonelli
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Appservice Slack bridging (optional)
**Notes**:
@ -72,21 +61,7 @@ matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
# matrix_appservice_slack_team_sync_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-appservice-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-appservice-slack/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_slack_configuration_extension_yaml` variable
For example, to change the bot's username from `slackbot`, add the following configuration to your `vars.yml` file. Replace `examplebot` with your own.
```yaml
matrix_appservice_slack_configuration_extension_yaml: |
bot_username: "examplebot"
```
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
## Installing
@ -111,7 +86,7 @@ To use the bridge, you need to send `/invite @slackbot:example.com` to invite th
If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
- Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID — it will look something like `!qporfwt:example.com`.
- Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like `!qporfwt:example.com`.
- Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:example.com` for Matrix.
- Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel ID>/details/`.
- Issue a link command in the administration control room with these collected values as arguments:
@ -146,7 +121,7 @@ Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave
## 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-appservice-slack`.
As always, check the logs: `journalctl -fu matrix-appservice-slack`
### Linking: "Room is now pending-name"
@ -154,8 +129,8 @@ This typically means that you haven't used the correct Slack channel ID. Unlink
### Messages work from Matrix to Slack, but not the other way around
Check the logs, and if you find the message like below, unlink your room, reinvite the bot and re-link it again.
Check you logs, if they say something like
`WARN SlackEventHandler Ignoring message from unrecognised Slack channel ID : %s (%s) <the channel ID> <some other ID>`
This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.
then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.

40
docs/configuring-playbook-bridge-appservice-webhooks.md
View File

@ -1,17 +1,6 @@
<!--
SPDX-FileCopyrightText: 2020 - 2023 MDAD project contributors
SPDX-FileCopyrightText: 2020 Björn Marten
SPDX-FileCopyrightText: 2020 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 iLyas Bakouch
SPDX-FileCopyrightText: 2022 Kim Brose
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Appservice Webhooks bridging (optional, deprecated)
**Note**: This bridge has been deprecated. We recommend not bothering with installing it. While not a 1:1 replacement, the bridge's author suggests taking a look at [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) as a replacement, which can also be [installed using this playbook](configuring-playbook-bridge-hookshot.md). Consider using that bridge instead of this one.
**Note**: This bridge has been deprecated. We recommend not bothering with installing it. While not a 1:1 replacement, the bridge's author suggests taking a look at [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) as a replacement, which can also be installed using [this playbook](configuring-playbook-bridge-hookshot.md). Consider using that bridge instead of this one.
The playbook can install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) for you. This bridge provides support for Slack-compatible webhooks.
@ -25,6 +14,9 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_appservice_webhooks_enabled: true
matrix_appservice_webhooks_api_secret: '<your_secret>'
# Uncomment to increase the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
# matrix_appservice_webhooks_log_level: 'verbose'
# As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
# Note: This deprecated method is considered insecure.
#
@ -32,15 +24,6 @@ matrix_appservice_webhooks_api_secret: '<your_secret>'
# use_appservice_legacy_authorization: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-appservice-webhooks/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-appservice-webhooks/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_webhooks_configuration_extension_yaml` variable
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -65,7 +48,7 @@ To use the bridge, you need to invite the bridge bot user to your room in either
- Send `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
- Add the bridge bot to a private channel (personal channels imply you being an administrator)
You then need to send a message to the bridge bot to receive a private message including the webhook link:
You then need to send a message to the bridge bot in order to receive a private message including the webhook link:
```
!webhook
@ -102,16 +85,3 @@ If you're using the [Dimension integration manager](configuring-playbook-dimensi
To configure it, open the Dimension integration manager, and go to "Settings" and "Bridges", then select edit action for "Webhook Bridge".
On the UI, press "Add self-hosted Bridge" button and populate "Provisioning URL" and "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.
## 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-appservice-webhooks`.
### Increase logging verbosity
The default logging level for this component is `info`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Valid values: info, verbose
matrix_appservice_webhooks_log_level: 'verbose'
```

66
docs/configuring-playbook-bridge-beeper-linkedin.md
View File

@ -1,29 +1,9 @@
<!--
SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2021 Alexandar Mechev
SPDX-FileCopyrightText: 2022 Cody Wyatt Neiman
SPDX-FileCopyrightText: 2023 Kuba Orlik
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Beeper Linkedin bridging (optional)
The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the mautrix bridges.
The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the other mautrix bridges
See the project's [documentation](https://github.com/beeper/linkedin/blob/master/README.md) to learn what it does and why it might be useful to you.
## Prerequisite
### Enable Appservice Double Puppet or Shared Secret Auth (optional)
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -32,13 +12,25 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_beeper_linkedin_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge before you continue.
There are some additional things you may wish to configure about the bridge.
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
```yaml
matrix_beeper_linkedin_bridge_encryption_allow: true
matrix_beeper_linkedin_bridge_encryption_default: true
```
**Note**: when following the guide to configure the bridge, make sure to replace `_mautrix_SERVICENAME_` in the variable names with `_beeper_linkedin_`.
If you would like to be able to administrate the bridge from your account it can be configured like this:
```yaml
matrix_beeper_linkedin_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
```
You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
## Installing
@ -57,24 +49,26 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
`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.
## Set up Double Puppeting by enabling Appservice Double Puppet or Shared Secret Auth
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
## Usage
To use the bridge, you need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You then need to send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account.
Send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account.
If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting-by-enabling-appservice-double-puppet-or-shared-secret-auth), if you haven't already done so.
## 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-beeper-linkedin`.
### Increase logging verbosity
The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
matrix_beeper_linkedin_logging_level: DEBUG
```
### Bridge asking for 2FA even if you don't have 2FA enabled
If you don't have 2FA enabled and are logging in from a strange IP for the first time, LinkedIn will send an email with a one-time code. You can use this code to authorize the bridge session. In my experience, once the IP is authorized, you will not be asked again.

44
docs/configuring-playbook-bridge-go-skype-bridge.md
View File

@ -1,42 +1,17 @@
<!--
SPDX-FileCopyrightText: 2022 Vladimir Panteleev
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Go Skype Bridge bridging (optional)
The playbook can install and configure [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you, for bridging to [Skype](https://www.skype.com/). This bridge was created based on [mautrix-whatsapp](https://github.com/mautrix/whatsapp) and can be configured in a similar way to it.
The playbook can install and configure [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you.
See the project's [documentation](https://github.com/kelaresg/go-skype-bridge/blob/master/README.md) to learn what it does and why it might be useful to you.
## Prerequisite (optional)
### Enable Shared Secret Auth
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable the [Skype](https://www.skype.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_go_skype_bridge_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
**Note**: when following the guide to configure the bridge, make sure to replace `_mautrix_SERVICENAME_` in the variable names with `_go_skype_bridge_`.
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -56,17 +31,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
To use the bridge, you need to start a chat with `@skypebridgebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
To use the bridge, you need to start a chat with `Skype bridge bot` with the handle `@skypebridgebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
## 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-go-skype-bridge`.
### Increase logging verbosity
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Valid values: fatal, error, warn, info, debug
matrix_go_skype_bridge_log_level: 'info'
```
Send `help` to the bot to see the available commands.

44
docs/configuring-playbook-bridge-heisenbridge.md
View File

@ -1,26 +1,12 @@
<!--
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 Heisenbridge bouncer-style IRC bridging (optional)
**Note**: bridging to [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) can also happen via the [matrix-appservice-irc](configuring-playbook-bridge-appservice-irc.md) bridge supported by the playbook.
The playbook can install and configure [Heisenbridge](https://github.com/hifi/heisenbridge) — the bouncer-style [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) bridge for you.
The playbook can install and configure [Heisenbridge](https://github.com/hifi/heisenbridge) - the bouncer-style [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) bridge for you.
See the project's [documentation](https://github.com/hifi/heisenbridge/blob/master/README.md) to learn what it does and why it might be useful to you. You can also take a look at [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I).
## Adjusting DNS records (optional)
By default, this playbook installs Heisenbridge on the `matrix.` subdomain, at the `/heisenbridge` path (https://matrix.example.com/heisenbridge). It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)). 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-heisenbridge-url-optional) for details about DNS configuration.
## Adjusting the playbook configuration
## Configuration
To enable Heisenbridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -35,11 +21,17 @@ matrix_heisenbridge_owner: "@alice:{{ matrix_domain }}"
# matrix_heisenbridge_identd_enabled: true
```
### Adjusting the Heisenbridge URL (optional)
For a more complete list of variables that you could override, see the [`defaults/main.yml` file](../roles/custom/matrix-bridge-heisenbridge/defaults/main.yml) of the Heisenbridge Ansible role.
### Adjusting the Heisenbridge URL
By default, this playbook installs Heisenbridge on the `matrix.` subdomain, at the `/heisenbridge` path (https://matrix.example.com/heisenbridge). It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)).
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.
By tweaking the `matrix_heisenbridge_hostname` and `matrix_heisenbridge_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
@ -47,17 +39,13 @@ matrix_heisenbridge_hostname: heisenbridge.example.com
matrix_heisenbridge_path_prefix: /
```
If you've changed the default hostname, you may need to create a CNAME record for the Heisenbridge domain (`heisenbridge.example.com`), which targets `matrix.example.com`.
## Adjusting DNS records
When setting, replace `example.com` with your own.
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Heisenbridge domain to the Matrix server.
### Extending the configuration
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-heisenbridge/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
@ -85,7 +73,3 @@ Help is available for all commands with the `-h` switch.
You can also learn the basics by watching [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I).
If you encounter issues or feel lost you can join the project room at [#heisenbridge:vi.fi](https://matrix.to/#/#heisenbridge:vi.fi) 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-heisenbridge`.

86
docs/configuring-playbook-bridge-hookshot.md
View File

@ -1,13 +1,3 @@
<!--
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 Kim Brose
SPDX-FileCopyrightText: 2022 MDAD project contributors
SPDX-FileCopyrightText: 2022 Paul Tötterman
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up matrix-hookshot (optional)
The playbook can install and configure [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) for you.
@ -48,12 +38,7 @@ Take special note of the `matrix_hookshot_*_enabled` variables. Services that ne
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-hookshot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-hookshot/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables
You can configure additional options by adding the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables.
Refer the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) and the comments in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) to learn what the individual options do.
@ -106,8 +91,9 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
| provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) |
| appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
| metrics | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and exposure enabled via `matrix_hookshot_metrics_proxying_enabled` or `matrix_metrics_exposure_enabled`. Read more in the [Metrics section](#metrics) below. | Prometheus |
Also see the various `matrix_hookshot_container_labels_*` variables in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml), which expose URLs publicly.
Also see the various `matrix_hookshot_container_labels_*` variables in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml), which expose URLs publicly
The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
@ -119,7 +105,7 @@ The GitHub bridge requires you to install a private key file. This can be done i
- somehow copy the file to the path `{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
- use the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) to copy the file from an arbitrary path on your ansible client to the correct path on the server.
To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following configuration to your `vars.yml` file:
To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
aux_file_definitions:
@ -134,57 +120,21 @@ For more information, see the documentation in the [default configuration of the
### Provisioning API
The provisioning API will be enabled automatically if you set `matrix_dimension_enabled: true` and provided a `matrix_hookshot_provisioning_secret`, unless you override it either way. To use hookshot with Dimension, you will need to enter as "Provisioning URL": `http://matrix-hookshot:9002`, which is made up of the variables `matrix_hookshot_container_url` and `matrix_hookshot_provisioning_port`.
The provisioning API will be enabled automatically if you set `matrix_dimension_enabled: true` and provided a `matrix_hookshot_provisioning_secret`, unless you override it either way. To use hookshot with dimension, you will need to enter as "Provisioning URL": `http://matrix-hookshot:9002`, which is made up of the variables `matrix_hookshot_container_url` and `matrix_hookshot_provisioning_port`.
### Metrics
Metrics are **only enabled by default** if the builtin [Prometheus](configuring-playbook-prometheus-grafana.md) is enabled (by default, Prometheus isn't enabled). If so, metrics will automatically be collected by Prometheus and made available in Grafana. You will, however, need to set up your own Dashboard for displaying them.
To explicitly enable metrics, use `matrix_hookshot_metrics_enabled: true`. This only exposes metrics over the container network, however.
**To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to enable metrics exposure on `https://matrix.example.com/metrics/hookshot` by:
- either enabling metrics exposure for Hookshot via `matrix_hookshot_metrics_proxying_enabled: true`
- or enabling metrics exposure for all services via `matrix_metrics_exposure_enabled: true`
Whichever one you go with, by default metrics are exposed publicly **without** password-protection. See [the Prometheus and Grafana docs](configuring-playbook-prometheus-grafana.md) for details about password-protection for metrics.
### Collision with matrix-appservice-webhooks
If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_userIdPrefix: '_webhooks_'`).
### Enable metrics
The playbook can enable and configure the metrics of the service for you.
Metrics are **only enabled by default** if the builtin [Prometheus](configuring-playbook-prometheus-grafana.md) is enabled (by default, Prometheus isn't enabled). If so, metrics will automatically be collected by Prometheus and made available in Grafana. You will, however, need to set up your own Dashboard for displaying them.
To enable the metrics, add the following configuration to your `vars.yml` file:
```yaml
# Expose metrics (locally, on the container network).
matrix_hookshot_metrics_enabled: true
```
**To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to enable metrics exposure on `https://matrix.example.com/metrics/hookshot` by adding the following configuration to your `vars.yml` file:
```yaml
matrix_hookshot_metrics_proxying_enabled: true
```
By default metrics are exposed publicly **without** password-protection. To password-protect the metrics with dedicated credentials, add the following configuration to your `vars.yml` file:
```yaml
matrix_hookshot_container_labels_metrics_middleware_basic_auth_enabled: true
matrix_hookshot_container_labels_metrics_middleware_basic_auth_users: ''
```
To `matrix_hookshot_container_labels_metrics_middleware_basic_auth_users`, set the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint. See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users for details about it.
**Note**: alternatively, you can use `matrix_metrics_exposure_enabled` to expose all services on this `/metrics/*` feature, and you can use `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` to password-protect the metrics of them. See [this section](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) for more information.
#### Enable Grafana (optional)
Probably you wish to enable Grafana along with Prometheus for generating graphs of the metics.
To enable Grafana, see [this section](configuring-playbook-prometheus-grafana.md#adjusting-the-playbook-configuration-grafana) for instructions.
## 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-hookshot`.
### Increase logging verbosity
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Valid values: error, warn, info, debug
matrix_hookshot_logging_level: debug
```

25
docs/configuring-playbook-bridge-matrix-bridge-sms.md
View File

@ -1,20 +1,10 @@
<!--
SPDX-FileCopyrightText: 2020 MDAD project contributors
SPDX-FileCopyrightText: 2020 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Matrix SMS bridging (optional)
The playbook can install and configure [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for you.
See the project's [documentation](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md) to learn what it does and why it might be useful to you.
## Prerequisite
The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.
**The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.**
## Adjusting the playbook configuration
@ -38,16 +28,9 @@ matrix_sms_bridge_provider_android_password: supeSecretPassword
# (optional) if your android-sms-gateway-server uses a self signed vertificate, the bridge needs a "truststore". This can be the certificate itself.
matrix_sms_bridge_provider_android_truststore_local_path: android-sms-gateway-server.p12
matrix_sms_bridge_provider_android_truststore_password: 123
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-sms/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_sms_bridge_configuration_extension_yaml` variable
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -68,7 +51,3 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
Read the [user guide](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md#user-guide) to see how this bridge works.
## 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-sms-bridge`.

73
docs/configuring-playbook-bridge-mautrix-bluesky.md
View File

@ -1,73 +0,0 @@
<!--
SPDX-FileCopyrightText: 2025 MDAD project contributors
SPDX-FileCopyrightText: 2025 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Bluesky bridging (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
The playbook can install and configure [mautrix-bluesky](https://github.com/mautrix/bluesky) for you, which provides a bridge to [Bluesky](https://bsky.social/about).
See the project's [documentation](https://github.com/mautrix/bluesky/blob/master/README.md) to learn what it does and why it might be useful to you.
## Prerequisite (optional)
### Enable Appservice Double Puppet
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_mautrix_bluesky_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
<!-- NOTE: relay mode is not supported for this bridge -->
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
## Installing
After configuring the playbook, run it 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
```
**Notes**:
- 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.
## Usage
To use the bridge, you need to start a chat with `@blueskybot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/bluesky/authentication.html).
After logging in, the bridge will create portal rooms for some recent chats. Portal rooms for other chats will be created as you receive messages.
## 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-mautrix-bluesky`.
### Increase logging verbosity
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Valid values: fatal, error, warn, info, debug, trace
matrix_mautrix_bluesky_logging_level: 'debug'
```

222
docs/configuring-playbook-bridge-mautrix-bridges.md
View File

@ -1,222 +0,0 @@
<!--
SPDX-FileCopyrightText: 2022 - 2024 MDAD project contributors
SPDX-FileCopyrightText: 2022 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2023 Nikita Chernyi
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up a Generic Mautrix Bridge (optional)
The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, discord, signal, googlechat, etc.), as well as many other (non-mautrix) bridges. This is a common guide for configuring mautrix bridges.
The author of the bridges maintains [the official docs](https://docs.mau.fi/bridges/index.html), whose source code is available at [mautrix/docs](https://github.com/mautrix/docs) repository on GitHub. You may as well to refer it while configuring them.
You can see each bridge's features on the `ROADMAP.md` file in its corresponding mautrix repository.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Replace SERVICENAME with one of: twitter, discord, signal, googlechat, etc.
matrix_mautrix_SERVICENAME_enabled: true
```
**Note**: for bridging to Meta's Messenger or Instagram, you would need to add `meta` with an underscore symbol (`_`) or hyphen (`-`) based on the context as prefix to each `SERVICENAME`; add `_` to variables (as in `matrix_mautrix_meta_messenger_configuration_extension_yaml` for example) and `-` to paths of the configuration files (as in `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2`), respectively. **`matrix_mautrix_facebook_*` and `matrix_mautrix_instagram_*` variables belong to the deprecated components and do not control the new bridge** ([mautrix-meta](https://github.com/mautrix/meta)), which can be [installed using this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md).
There are some additional things you may wish to configure about the bridge before you continue. Each bridge may have additional requirements besides `_enabled: true`. For example, the mautrix-telegram bridge (our documentation page about it is [here](configuring-playbook-bridge-mautrix-telegram.md)) requires the `matrix_mautrix_telegram_api_id` and `matrix_mautrix_telegram_api_hash` variables to be defined. Refer to each bridge's individual documentation page for details about enabling bridges.
### Configure bridge permissions (optional)
By default any user on your homeserver will be able to use the mautrix bridges. To limit who can use them you would need to configure their permissions settings.
Different levels of permission can be granted to users. For example, to **configure a user as an administrator for all bridges**, add the following configuration to your `vars.yml` file:
```yaml
matrix_admin: "@alice:{{ matrix_domain }}"
```
If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default.
**Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
```
This will add the admin permission to the specific user, while keeping the default permissions.
You could also redefine the default permissions settings completely, rather than adding extra permissions. You may wish to look at `roles/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` to find information on the permission settings and other options you would like to configure.
### Enable encryption (optional)
[Encryption (End-to-Bridge Encryption, E2BE) support](https://docs.mau.fi/bridges/general/end-to-bridge-encryption.html) is off by default. If you would like to enable encryption, add the following configuration to your `vars.yml` file:
**for all bridges with encryption support**:
```yaml
matrix_bridges_encryption_enabled: true
matrix_bridges_encryption_default: true
```
**Alternatively**, for a specific bridge:
```yaml
matrix_mautrix_SERVICENAME_bridge_encryption_enabled: true
matrix_mautrix_SERVICENAME_bridge_encryption_default: true
```
### Enable relay mode (optional)
[Relay mode](https://docs.mau.fi/bridges/general/relay-mode.html) is off by default. Check [the table on the official documentation](https://docs.mau.fi/bridges/general/relay-mode.html#support-table) for bridges which support relay mode.
If you would like to enable it, add the following configuration to your `vars.yml` file:
**for all bridges with relay mode support**:
```yaml
matrix_bridges_relay_enabled: true
```
**Alternatively**, for a specific bridge:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
relay:
enabled: true
```
You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
relay:
enabled: true
permissions:
'@alice:{{ matrix_domain }}': admin
encryption:
allow: true
default: true
```
If you want to activate the relaybot in a room, send `!prefix set-relay` in the rooms where you want to use the bot (replace `!prefix` with the appropriate command prefix for the bridge, like `!signal` or `!wa`). To deactivate, send `!prefix unset-relay`.
Use `!prefix set-pl 100` to be able for the bot to modify room settings and invite others.
#### Allow anyone on the homeserver to become a relay user (optional)
By default, only admins are allowed to set themselves as relay users. To allow anyone on your homeserver to set themselves as relay users, add the following configuration to your `vars.yml` file:
```yaml
matrix_mautrix_SERVICENAME_bridge_relay_admin_only: false
```
### Set the bot's username (optional)
To set the bot's username, add the following configuration to your `vars.yml` file:
```yaml
matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
```
### Configure the logging level (optional)
To specify the logging level, add the following configuration to your `vars.yml` file:
```yaml
matrix_mautrix_SERVICENAME_logging_level: warn
```
Replace `warn` with one of the following to control the verbosity of the logs generated: `trace`, `debug`, `info`, `warn`, `error` or `fatal`.
If you have issues with a service, and are requesting support, the higher levels of logging (those that appear earlier in the list, like `trace`) will generally be more helpful.
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_SERVICENAME_configuration_extension_yaml` variable
## Installing
After configuring the playbook, run it 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,ensure-matrix-users-created,start
```
**Notes**:
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
- 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.
## Usage
To use the bridge, you need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
For details about the next steps, refer to each bridge's individual documentation page.
Send `help` to the bot to see the available commands.
If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
### Set up Double Puppeting (optional)
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
To set it up, you have 2 ways of going about it.
#### Method 1: automatically, by enabling Appservice Double Puppet (recommended)
To set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html), you could enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
Appservice Double Puppet is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
To enable the Appservice Double Puppet service, add the following configuration to your `vars.yml` file:
```yaml
matrix_appservice_double_puppet_enabled: true
```
When enabled, double puppeting will automatically be enabled for all bridges that support double puppeting via the appservice method.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
**Notes**:
- Previously there were multiple different automatic double puppeting methods like one with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but they have been superseded by this Appservice Double Puppet method. Double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future as the older methods were completely removed in the megabridge rewrites on [the upstream project](https://docs.mau.fi/bridges/general/double-puppeting.html#automatically).
<!-- TODO: remove this note if the Shared Secret Auth service has stopped working or the bridges have been removed -->
- Some bridges like [the deprecated Facebook mautrix bridge](configuring-playbook-bridge-mautrix-facebook.md) and [matrix-appservice-kakaotalk](configuring-playbook-bridge-appservice-kakaotalk.md), which is partially based on the Facebook bridge, are compatible with the Shared Secret Auth service only. These bridges automatically perform Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
## Troubleshooting
For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge.
If the bridge's bot doesn't accept the invite to a chat, refer [the official troubleshooting page](https://docs.mau.fi/bridges/general/troubleshooting.html) as well.
If you found bugs in mautrix bridges, they should be reported to the upstream project, in the corresponding mautrix repository, not to us.

80
docs/configuring-playbook-bridge-mautrix-discord.md
View File

@ -1,19 +1,5 @@
<!--
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2018 Hugues Morisset
SPDX-FileCopyrightText: 2021 - 2022 MDAD project contributors
SPDX-FileCopyrightText: 2022 Abílio Costa
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Marko Weltzer
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Discord bridging (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridges supported by the playbook.
- For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing.
- For personal use with a discord account we recommend the `mautrix-discord` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
@ -32,9 +18,7 @@ If this is a dealbreaker for you, consider using one of the other Discord bridge
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -44,12 +28,16 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_mautrix_discord_enabled: true
```
### Extending the configuration
You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
### Additional configuration
There are some additional things you may wish to configure about the bridge.
<!-- NOTE: common relay mode is not supported for this bridge -->
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
Take a look at:
- `roles/custom/matrix-bridge-mautrix-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-mautrix-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_discord_configuration_extension_yaml` variable
## Installing
@ -70,29 +58,51 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
To use the bridge, you need to start a chat with `@discordbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
### Logging in
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/discord/authentication.html).
#### Method 1: Login using QR code (recommended)
After logging in, the bridge will create portal rooms for some recent direct messages.
For using this bridge, you would need to authenticate by **scanning a QR code** with the Discord app on your phone.
### Bridge guilds
You can delete the Discord app after the authentication process.
If you'd like to bridge guilds, send `guilds status` to see the list of guilds, then send `guilds bridge GUILD_ID_HERE` for each guild that you'd like bridged. Make sure to replace `GUILD_ID_HERE` with the guild's ID.
#### Method 2: Login using Discord token (not recommended)
After bridging, spaces will be created automatically, and rooms will be created if necessary when messages are received. You can also pass `--entire` to the bridge command to immediately create all rooms.
To acquire the token, open Discord in a private browser window. Then open the developer settings (keyboard shortcut might be "ctrl+shift+i" or by pressing "F12"). Navigate to the "Network" tab then reload the page. In the URL filter or search bar type "/api" and find the response with the file name of "library". Under the request headers you should find a variable called "Authorization", this is the token to your Discord account. After copying the token, you can close the browser window.
If you want to manually bridge channels, invite the bot to the room you want to bridge, and run `!discord bridge CHANNEL_ID_HERE` to bridge the room. Make sure to replace `CHANNEL_ID_HERE` with the channel's ID.
### Bridging
## Troubleshooting
1. Start a chat with `@discordbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
2. If you would like to login to Discord using a token, send `login-token` command, otherwise, send `login-qr` command.
3. You'll see a QR code which you need to scan with the Discord app on your phone. You can scan it with the camera app too, which will open Discord, which will then instruct you to scan it a 2nd time in the Discord app.
4. After confirming (in the Discord app) that you'd like to allow this login, the bot should respond with "Succcessfully authenticated as …"
5. Now that you're logged in, you can send `help` to the bot to see the available commands.
6. Some Direct Messages from Discord should start syncing automatically
7. If you'd like to bridge guilds:
- send `guilds status` to see the list of guilds
- for each guild that you'd like bridged, send `guilds bridge GUILD_ID --entire`
8. You may wish to uninstall the Discord app from your phone now. It's not needed for the bridge to function.
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-mautrix-discord`.
### 💡 Set up Double Puppeting
### Increase logging verbosity
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
To set it up, you have 2 ways of going about it.
```yaml
# Valid values: fatal, error, warn, info, debug, trace
matrix_mautrix_discord_logging_level: 'debug'
```
#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature

93
docs/configuring-playbook-bridge-mautrix-facebook.md
View File

@ -1,34 +1,16 @@
<!--
SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 Hugues Morisset
SPDX-FileCopyrightText: 2021 - 2022 MDAD project contributors
SPDX-FileCopyrightText: 2021 Aaron Raimist
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 László Várady
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Facebook bridging (optional, deprecated)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
**Note**: This bridge has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge, which can be [installed using this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md). Consider using that bridge instead of this one.
**Note**: This bridge has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge, which can be installed using [this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md). Consider using that bridge instead of this one.
The playbook can install and configure [mautrix-facebook](https://github.com/mautrix/facebook) for you.
See the project's [documentation](https://github.com/mautrix/facebook/blob/master/README.md) to learn what it does and why it might be useful to you.
See the project's [documentation](https://github.com/mautrix/facebook/blob/master/ROADMAP.md) to learn what it does and why it might be useful to you.
## Prerequisite (optional)
### Enable Shared Secret Auth
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -38,11 +20,40 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_mautrix_facebook_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge before you continue.
There are some additional things you may wish to configure about the bridge.
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
```yaml
matrix_mautrix_facebook_configuration_extension_yaml: |
bridge:
encryption:
allow: true
default: true
```
If you would like to be able to administrate the bridge from your account it can be configured like this:
```yaml
matrix_mautrix_facebook_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
```
Using both would look like
```yaml
matrix_mautrix_facebook_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
encryption:
allow: true
default: true
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-facebook/defaults/main.yml` to find other things you would like to configure.
## Installing
@ -65,22 +76,34 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
To use the bridge, you need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You then need to send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account.
Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/facebook/authentication.html).
If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
### 💡 Set up Double Puppeting
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
To set it up, you have 2 ways of going about it.
#### Method 1: automatically, by enabling Shared Secret Auth
The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Facebook` device some time in the future, as that would break the Double Puppeting feature
## 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-mautrix-facebook`.
### Increase logging verbosity
The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
matrix_mautrix_facebook_logging_level: DEBUG
```
### Facebook rejecting login attempts and forcing you to change password
If your Matrix server is in a wildly different location than where you usually use your Facebook account from, the bridge's login attempts may be outright rejected by Facebook. Along with that, Facebook may even force you to change the account's password.

46
docs/configuring-playbook-bridge-mautrix-gmessages.md
View File

@ -1,26 +1,14 @@
<!--
SPDX-FileCopyrightText: 2023 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2023 Shreyas Ajjarapu
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Google Messages bridging (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
The playbook can install and configure [mautrix-gmessages](https://github.com/mautrix/gmessages) for you, for bridging to [Google Messages](https://messages.google.com/).
See the project's [documentation](https://docs.mau.fi/bridges/go/gmessages/index.html) to learn what it does and why it might be useful to you.
## Prerequisite (optional)
### Enable Appservice Double Puppet
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -30,13 +18,6 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_mautrix_gmessages_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
<!-- NOTE: relay mode is not supported for this bridge -->
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -58,19 +39,24 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
To use the bridge, you need to start a chat with `@gmessagesbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/gmessages/authentication.html).
### 💡 Set up Double Puppeting
After logging in, the bridge will create portal rooms for recent chats.
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
## Troubleshooting
To set it up, you have 2 ways of going about it.
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-mautrix-gmessages`.
#### Method 1: automatically, by enabling Appservice Double Puppet
### Increase logging verbosity
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
```yaml
# Valid values: fatal, error, warn, info, debug, trace
matrix_mautrix_gmessages_logging_level: 'debug'
```
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-gmessages` device some time in the future, as that would break the Double Puppeting feature

60
docs/configuring-playbook-bridge-mautrix-googlechat.md
View File

@ -1,29 +1,14 @@
<!--
SPDX-FileCopyrightText: 2021 MDAD project contributors
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Google Chat bridging (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
The playbook can install and configure [mautrix-googlechat](https://github.com/mautrix/googlechat) for you.
See the project's [documentation](https://docs.mau.fi/bridges/python/googlechat/index.html) to learn what it does and why it might be useful to you.
## Prerequisite (optional)
### Enable Appservice Double Puppet or Shared Secret Auth
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -33,13 +18,6 @@ To enable the [Google Chat](https://chat.google.com/) bridge, add the following
matrix_mautrix_googlechat_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
<!-- NOTE: relay mode is not supported for this bridge -->
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -59,20 +37,36 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
To use the bridge, you need to start a chat with `@googlechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
To use the bridge, you need to start a chat with `googlechat bridge bot` with handle `@googlechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html).
Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions.
After logging in, the bridge will create portal rooms for some recent chats. Portal rooms for other chats will be created as you receive messages.
Automatic login may not work. If it does not, reload the page and select the "Manual login" checkbox before starting. Manual login involves logging into your Google account normally and then manually getting the OAuth token from browser cookies with developer tools.
## Troubleshooting
Once logged in, recent chats should show up as new conversations automatically. Other chats will get portals as you receive messages.
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-mautrix-googlechat`.
You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html).
### Increase logging verbosity
### 💡 Set up Double Puppeting
The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
```yaml
matrix_mautrix_googlechat_logging_level: DEBUG
```
To set it up, you have 2 ways of going about it.
#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-googlechat` device some time in the future, as that would break the Double Puppeting feature

79
docs/configuring-playbook-bridge-mautrix-hangouts.md
View File

@ -1,27 +1,72 @@
<!--
SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 Eduardo Beltrame
SPDX-FileCopyrightText: 2021 MDAD project contributors
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
# Setting up Mautrix Hangouts bridging (optional, deprecated)
SPDX-License-Identifier: AGPL-3.0-or-later
-->
💡 **Note**: This bridge has been deprecated in favor of [Google Chat bridge](https://github.com/mautrix/googlechat), which can be installed using [this playbook](configuring-playbook-bridge-mautrix-googlechat.md). Installing the mautrix-hangouts bridge is **no longer possible**. For now, this documentation page remains here for historical purposes.
# Setting up Mautrix Hangouts bridging (optional, removed)
The playbook can install and configure [mautrix-hangouts](https://github.com/mautrix/hangouts) for you.
🪦 The playbook used to be able to install and configure [mautrix-hangouts](https://github.com/mautrix/hangouts), but no longer includes this component, because Google Hangouts has been discontinued since the 1st of November 2022.
See the project's [documentation](https://docs.mau.fi/bridges/python/hangouts/index.html) to learn what it does and why it might be useful to you.
You may wish to use the [Google Chat bridge](https://github.com/mautrix/googlechat) instead.
## Prerequisite (optional)
## Uninstalling the bridge manually
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
If you still have the Hangouts bridge installed on your Matrix server, the playbook can no longer help you uninstall it and you will need to do it manually. To uninstall manually, run these commands on the server:
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
```sh
systemctl disable --now matrix-mautrix-hangouts.service
## Adjusting the playbook configuration
rm -rf /matrix/mautrix-hangouts
To enable the [Google Hangouts](https://hangouts.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
/matrix/postgres/bin/cli-non-interactive 'DROP DATABASE matrix_mautrix_hangouts;'
```yaml
matrix_mautrix_hangouts_enabled: true
```
## Installing
After configuring the playbook, run it 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,ensure-matrix-users-created,start
```
**Notes**:
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
- 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.
## Usage
To use the bridge, you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions.
Automatic login may not work. If it does not, reload the page and select the "Manual login" checkbox before starting. Manual login involves logging into your Google account normally and then manually getting the OAuth token from browser cookies with developer tools.
Once logged in, recent chats should show up as new conversations automatically. Other chats will get portals as you receive messages.
You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/hangouts/authentication.html).
### 💡 Set up Double Puppeting
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
To set it up, you have 2 ways of going about it.
#### Method 1: automatically, by enabling Shared Secret Auth
The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Hangouts` device some time in the future, as that would break the Double Puppeting feature

57
docs/configuring-playbook-bridge-mautrix-instagram.md
View File

@ -1,21 +1,10 @@
<!--
SPDX-FileCopyrightText: 2021 - 2022 MDAD project contributors
SPDX-FileCopyrightText: 2021 Marcus Proest
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Instagram bridging (optional, deprecated)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
**Note**: This bridge has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge, which can be [installed using this playbook](configuring-playbook-bridge-mautrix-meta-instagram.md). Consider using that bridge instead of this one.
**Note**: This bridge has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge, which can be installed using [this playbook](configuring-playbook-bridge-mautrix-meta-instagram.md). Consider using that bridge instead of this one.
The playbook can install and configure [mautrix-instagram](https://github.com/mautrix/instagram) for you.
See the project's [documentation](https://github.com/mautrix/instagram/blob/master/README.md) to learn what it does and why it might be useful to you.
See the project's [documentation](https://docs.mau.fi/bridges/python/instagram/index.html) to learn what it does and why it might be useful to you.
## Adjusting the playbook configuration
@ -25,11 +14,33 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_mautrix_instagram_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge before you continue.
There are some additional things you may wish to configure about the bridge.
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
```yaml
matrix_mautrix_instagram_configuration_extension_yaml: |
bridge:
encryption:
allow: true
default: true
```
If you would like to be able to administrate the bridge from your account it can be configured like this:
```yaml
# The easy way. The specified Matrix user ID will be made an admin of all bridges
matrix_admin: "@alice:{{ matrix_domain }}"
# OR:
# The more verbose way. Applies to this bridge only. You may define multiple Matrix users as admins.
matrix_mautrix_instagram_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure.
## Installing
@ -52,16 +63,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
To use the bridge, you need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You then need to send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account.
Send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account.
## 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-mautrix-instagram`.
### Increase logging verbosity
The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
matrix_mautrix_instagram_logging_level: DEBUG
```
You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/instagram/authentication.html).

70
docs/configuring-playbook-bridge-mautrix-meta-instagram.md
View File

@ -1,18 +1,7 @@
<!--
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Instagram bridging via Mautrix Meta (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you.
See the project's [documentation](https://docs.mau.fi/bridges/go/meta/index.html) to learn what it does and why it might be useful to you.
Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
This documentation page only deals with the bridge's ability to bridge to Instagram. For bridging to Facebook/Messenger, see [Setting up Messenger bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-messenger.md).
@ -34,7 +23,7 @@ Then, consider disabling the old bridge in your configuration, so it won't recre
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -46,11 +35,37 @@ matrix_mautrix_meta_instagram_enabled: true
Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
### Extending the configuration
### Bridge permissions
There are some additional things you may wish to configure about the bridge.
By default, any user on your homeserver will be able to use the bridge.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
Different levels of permission can be granted to users:
- `relay` - Allowed to be relayed through the bridge, no access to commands
- `user` - Use the bridge with puppeting
- `admin` - Use and administer the bridge
The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
The default permissions are set via `matrix_mautrix_meta_instagram_bridge_permissions_default` and are somewhat like this:
```yaml
matrix_mautrix_meta_instagram_bridge_permissions_default:
'*': relay
example.com: user
'{{ matrix_admin }}': admin
```
If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default.
You may redefine `matrix_mautrix_meta_instagram_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_instagram_bridge_permissions_custom` like this:
```yaml
matrix_mautrix_meta_instagram_bridge_permissions_custom:
'@alice:{{ matrix_domain }}': admin
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
## Installing
@ -73,19 +88,24 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
To use the bridge, you need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html).
### 💡 Set up Double Puppeting
After logging in, the bridge will sync recent chats.
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
## Troubleshooting
To set it up, you have 2 ways of going about it.
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-mautrix-meta-instagram`.
#### Method 1: automatically, by enabling Appservice Double Puppet
### Increase logging verbosity
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
```yaml
# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
matrix_mautrix_meta_instagram_logging_min_level: debug
```
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature

79
docs/configuring-playbook-bridge-mautrix-meta-messenger.md
View File

@ -1,19 +1,7 @@
<!--
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Johan Swetzén
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Messenger bridging via Mautrix Meta (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you.
See the project's [documentation](https://docs.mau.fi/bridges/go/meta/index.html) to learn what it does and why it might be useful to you.
Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
This documentation page only deals with the bridge's ability to bridge to Facebook Messenger. For bridging to Instagram, see [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md).
@ -34,7 +22,7 @@ Then, consider disabling the old bridge in your configuration, so it won't recre
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -53,18 +41,44 @@ As mentioned above, the [mautrix-meta](https://github.com/mautrix/meta) bridge s
The bridge can pull your Messenger messages via 3 different methods:
- (`facebook`) Facebook via `facebook.com`
- (`facebook-tor`) Facebook via `facebookwkhpilnemxj7asaniu7vnjjbiltxjqhye3mhbshg7kx5tfyd.onion` ([Tor](https://www.torproject.org/)) — does not currently proxy media downloads
- (default) (`messenger`) Messenger via `messenger.com` — usable even without a Facebook account
- (`facebook-tor`) Facebook via `facebookwkhpilnemxj7asaniu7vnjjbiltxjqhye3mhbshg7kx5tfyd.onion` ([Tor](https://www.torproject.org/)) - does not currently proxy media downloads
- (default) (`messenger`) Messenger via `messenger.com` - usable even without a Facebook account
You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variable. The playbook defaults to the `messenger` mode, because it's most universal (every Facebook user has a Messenger account, but the opposite is not true).
Note that switching the mode (especially between `facebook*` and `messenger`) will intentionally make the bridge use another database (`matrix_mautrix_meta_facebook` or `matrix_mautrix_meta_messenger`) to isolate the 2 instances. Switching between Tor and non-Tor may be possible without dataloss, but your mileage may vary. Before switching to a new mode, you may wish to de-configure the old one (send `help` to the bridge bot and unbridge your portals, etc.).
### Extending the configuration
### Bridge permissions
There are some additional things you may wish to configure about the bridge.
By default, any user on your homeserver will be able to use the bridge.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
Different levels of permission can be granted to users:
- `relay` - Allowed to be relayed through the bridge, no access to commands
- `user` - Use the bridge with puppeting
- `admin` - Use and administer the bridge
The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permissions_default` and are somewhat like this:
```yaml
matrix_mautrix_meta_messenger_bridge_permissions_default:
'*': relay
example.com: user
'{{ matrix_admin }}': admin
```
If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default.
You may redefine `matrix_mautrix_meta_messenger_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_messenger_bridge_permissions_custom` like this:
```yaml
matrix_mautrix_meta_messenger_bridge_permissions_custom:
'@alice:{{ matrix_domain }}': admin
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
## Installing
@ -87,21 +101,28 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
To use the bridge, you need to start a chat with `@messengerbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). Note that the user ID of the bridge's bot is not `@facebookbot:example.com`.
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html).
You then need to send a `login` command and follow the bridge bot's instructions.
After logging in, the bridge will sync recent chats.
Given that the bot is configured in `messenger` [bridge mode](#bridge-mode) by default, you will need to log in to [messenger.com](https://messenger.com/) (not `facebook.com`!) and obtain the cookies from there as per [the bridge's authentication instructions](https://docs.mau.fi/bridges/go/meta/authentication.html).
**Note**: given that the bot is configured in `messenger` [bridge mode](#bridge-mode) by default, you will need to log in to [messenger.com](https://messenger.com/) (not `facebook.com`!) and obtain the cookies from there.
### 💡 Set up Double Puppeting
## Troubleshooting
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
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-mautrix-meta-messenger`.
To set it up, you have 2 ways of going about it.
### Increase logging verbosity
#### Method 1: automatically, by enabling Appservice Double Puppet
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
```yaml
# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
matrix_mautrix_meta_messenger_logging_min_level: debug
```
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature

90
docs/configuring-playbook-bridge-mautrix-signal.md
View File

@ -1,26 +1,10 @@
<!--
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2018 Hugues Morisset
SPDX-FileCopyrightText: 2020 - 2021 MDAD project contributors
SPDX-FileCopyrightText: 2020 Sabine Laszakovits
SPDX-FileCopyrightText: 2021 Julian Foad
SPDX-FileCopyrightText: 2021 Wolfgang Winter
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Marko Weltzer
SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Benjamin Kampmann
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Signal bridging (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
The playbook can install and configure [mautrix-signal](https://github.com/mautrix/signal) for you.
See the project's [documentation](https://docs.mau.fi/bridges/go/signal/index.html) to learn what it does and why it might be useful to you.
See the project's [documentation](https://docs.mau.fi/bridges/python/signal/index.html) to learn what it does and why it might be useful to you.
**Note**: This revamped version of the [mautrix-signal (legacy)](configuring-playbook-bridge-mautrix-signal.md) may increase the CPU usage of your homeserver.
## Prerequisites (optional)
@ -34,7 +18,7 @@ However, if you're [using an external Postgres server](configuring-playbook-exte
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -44,11 +28,46 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_mautrix_signal_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge before you continue.
There are some additional things you may wish to configure about the bridge.
By default, any user on your homeserver will be able to use the bridge.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
Different levels of permission can be granted to users:
* relay - Allowed to be relayed through the bridge, no access to commands;
* user - Use the bridge with puppeting;
* admin - Use and administer the bridge.
The permissions are following the sequence: nothing < relay < user < admin.
The default permissions are set as follows:
```yaml
permissions:
'*': relay
example.com: user
```
If you want to augment the preset permissions, you might want to set the additional permissions with the following settings in your `vars.yml` file:
```yaml
matrix_mautrix_signal_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
```
This will add the admin permission to the specific user, while keeping the default permissions.
In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file:
```yaml
matrix_mautrix_signal_bridge_permissions:
'@alice:{{ matrix_domain }}': admin
'@bob:{{ matrix_domain }}' : user
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
## Installing
@ -71,21 +90,24 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
To use the bridge, you need to start a chat with `@signalbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/signal/authentication.html).
### 💡 Set up Double Puppeting
After logging in, the bridge will bridge chats as you receive messages.
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
**Note**: Signal does not support any kind of message history (even on official apps), so the bridge won't backfill any messages.
To set it up, you have 2 ways of going about it.
## Troubleshooting
#### Method 1: automatically, by enabling Appservice Double Puppet
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-mautrix-signal`.
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
### Increase logging verbosity
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
#### Method 2: manually, by asking each user to provide a working access token
```yaml
# Valid values: fatal, error, warn, info, debug, trace
matrix_mautrix_signal_logging_level: 'debug'
```
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Signal` device some time in the future, as that would break the Double Puppeting feature

56
docs/configuring-playbook-bridge-mautrix-slack.md
View File

@ -1,16 +1,5 @@
<!--
SPDX-FileCopyrightText: 2023 Cody Wyatt Neiman
SPDX-FileCopyrightText: 2023 Stuart Mumford
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Slack bridging (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
**Note**: bridging to [Slack](https://slack.com/) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) bridges supported by the playbook.
- For using as a Bot we recommend the [Appservice Slack](configuring-playbook-bridge-appservice-slack.md), because it supports plumbing. Note that it is not available for new installation unless you have already created a classic Slack application, because the creation of classic Slack applications, which this bridge makes use of, has been discontinued.
- For personal use with a slack account we recommend the `mautrix-slack` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Slack bridges supported by the playbook.
@ -31,7 +20,7 @@ Note that neither of these methods are officially supported by Slack. [matrix-ap
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -41,12 +30,16 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_mautrix_slack_enabled: true
```
### Extending the configuration
You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
There are some additional things you may wish to configure about the bridge.
### Additional configuration
<!-- NOTE: relay mode is not supported for this bridge -->
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
There are some additional options you may wish to configure with the bridge.
Take a look at:
- `roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-mautrix-slack/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_slack_configuration_extension_yaml` variable
## Installing
@ -67,21 +60,30 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
To use the bridge, you need to start a chat with `@slackbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
1. Start a chat with `@slackbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
2. If you would like to login to Slack using a token, send the `login-token` command, otherwise, send the `login-password` command. Read [here](https://docs.mau.fi/bridges/go/slack/authentication.html) on how to retrieve your token and cookie token.
3. The bot should respond with "Successfully logged into <email> for team <workspace>"
4. Now that you're logged in, you can send `help` to the bot to see the available commands.
5. Slack channels should automatically begin bridging if you authenticated using a token. Otherwise, you must wait to receive a message in the channel if you used password authentication.
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/slack/authentication.html).
### 💡 Set up Double Puppeting
If you authenticated using a token, the recent chats will be bridged automatically (depending on the `conversation_count` setting). Otherwise (i.e. logging with the Discord application), the chats the bot is in will be bridged automatically.
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
## Troubleshooting
To set it up, you have 2 ways of going about it.
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-mautrix-slack`.
#### Method 1: automatically, by enabling Appservice Double Puppet
### Increase logging verbosity
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
```yaml
# Valid values: fatal, error, warn, info, debug, trace
matrix_mautrix_slack_logging_level: 'debug'
```
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature

129
docs/configuring-playbook-bridge-mautrix-telegram.md
View File

@ -1,45 +1,18 @@
<!--
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2018 Hugues Morisset
SPDX-FileCopyrightText: 2019 - 2022 MDAD project contributors
SPDX-FileCopyrightText: 2021 Panagiotis Georgiadis
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Iikka Järvenpää
SPDX-FileCopyrightText: 2022 Marko Weltzer
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Telegram bridging (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
The playbook can install and configure [mautrix-telegram](https://github.com/mautrix/telegram) for you.
See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/index.html) to learn what it does and why it might be useful to you.
## Prerequisites
### Obtain a Telegram API key
To use the bridge, you'd need to obtain an API key from [https://my.telegram.org/apps](https://my.telegram.org/apps).
### Enable Appservice Double Puppet or Shared Secret Auth (optional)
## Prerequisite (optional)
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
**Notes**:
- Double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
- If you decided to enable Double Puppeting manually, send `login-matrix` to the bot in order to receive an instruction about how to send an access token to it.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `YOUR_TELEGRAM_APP_ID` and `YOUR_TELEGRAM_API_HASH`.
You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_mautrix_telegram_enabled: true
@ -47,41 +20,6 @@ matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
```
### Relaying
### Enable relay-bot (optional)
If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `vars.yml` file:
```yaml
matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN
matrix_mautrix_telegram_configuration_extension_yaml: |
bridge:
permissions:
'*': relaybot
```
### Configure a user as an administrator of the bridge (optional)
You might also want to give permissions to a user to administrate the bot. See [this section](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional) on the common guide for details about it.
More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
### Use the bridge for direct chats only (optional)
If you want to exclude all groups from syncing and use the Telegram-Bridge only for direct chats, add the following configuration to your `vars.yml` file:
```yaml
matrix_mautrix_telegram_filter_mode: whitelist
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
<!-- NOTE: common relay mode is not supported for this bridge -->
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -103,18 +41,55 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
To use the bridge, you need to start a chat with `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/telegram/authentication.html).
After logging in, the bridge will create portal rooms for all of your Telegram groups and invite you to them. Note that the bridge won't automatically create rooms for private chats.
## 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-mautrix-telegram`.
### Increase logging verbosity
The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_mautrix_telegram_logging_level: DEBUG
matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN
matrix_mautrix_telegram_configuration_extension_yaml: |
bridge:
permissions:
'*': relaybot
```
You might also want to give permissions to administrate the bot:
```yaml
matrix_mautrix_telegram_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
```
More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
If you like to exclude all groups from syncing and use the Telgeram-Bridge only for direct chats, you can add the following additional playbook configuration:
```yaml
matrix_mautrix_telegram_filter_mode: whitelist
```
### 💡 Set up Double Puppeting
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
To set it up, you have 2 ways of going about it.
#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
#### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging.
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send `login-matrix` to the bot and follow instructions about how to send the access token to it
- make sure you don't log out the `Mautrix-Telegram` device some time in the future, as that would break the Double Puppeting feature

52
docs/configuring-playbook-bridge-mautrix-twitter.md
View File

@ -1,16 +1,5 @@
<!--
SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2021 Matthew Cengia
SPDX-FileCopyrightText: 2022 Aaron Raimist
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Twitter bridging (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
**Note**: bridging to [Twitter](https://twitter.com/) can also happen via the [mx-puppet-twitter](configuring-playbook-bridge-mx-puppet-twitter.md) bridge supported by the playbook.
The playbook can install and configure [mautrix-twitter](https://github.com/mautrix/twitter) for you.
@ -19,11 +8,11 @@ See the project's [documentation](https://github.com/mautrix/twitter/blob/master
## Prerequisite (optional)
### Enable Appservice Double Puppet
### Enable Appservice Double Puppet (optional)
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -33,13 +22,6 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_mautrix_twitter_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
<!-- NOTE: relay mode is not supported for this bridge -->
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -59,21 +41,29 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
To use the bridge, you need to start a chat with `@twitterbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
1. You then need to start a chat with `@twitterbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
2. Send login-cookie to start the login. The bot should respond with instructions on how to proceed.
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/twitter/authentication.html).
You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/twitter/authentication.html).
After logging in, the bridge will create portal rooms for some recent chats. Portal rooms for other chats will be created as you receive messages.
### 💡 Set up Double Puppeting
## Troubleshooting
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
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-mautrix-twitter`.
To set it up, you have 2 ways of going about it.
### Increase logging verbosity
#### Method 1: automatically, by enabling Appservice Double Puppet
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
```yaml
# Valid values: fatal, error, warn, info, debug, trace
matrix_mautrix_twitter_logging_level: 'debug'
```
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature

64
docs/configuring-playbook-bridge-mautrix-whatsapp.md
View File

@ -1,33 +1,14 @@
<!--
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2018 Hugues Morisset
SPDX-FileCopyrightText: 2021 - 2025 MDAD project contributors
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Marko Weltzer
SPDX-FileCopyrightText: 2023 James Collier
SPDX-FileCopyrightText: 2023 Kuba Orlik
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix Whatsapp bridging (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
The playbook can install and configure [mautrix-whatsapp](https://github.com/mautrix/whatsapp) for you.
See the project's [documentation](https://docs.mau.fi/bridges/go/whatsapp/index.html) to learn what it does and why it might be useful to you.
## Prerequisite (optional)
### Enable Appservice Double Puppet or Shared Secret Auth
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
## Adjusting the playbook configuration
@ -37,11 +18,21 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_mautrix_whatsapp_enabled: true
```
### Extending the configuration
Whatsapp multidevice beta is required, now it is enough if Whatsapp is connected to the Internet every 2 weeks.
There are some additional things you may wish to configure about the bridge.
The relay bot functionality is off by default. If you would like to enable the relay bot, add the following to your `vars.yml` file:
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
```yaml
matrix_mautrix_whatsapp_bridge_relay_enabled: true
```
By default, only admins are allowed to set themselves as relay users. To allow anyone on your homeserver to set themselves as relay users add this to your `vars.yml` file:
```yaml
matrix_mautrix_whatsapp_bridge_relay_admin_only: false
```
If you want to activate the relay bot in a room, send `!wa set-relay`. To deactivate, send `!wa unset-relay`.
## Installing
@ -64,21 +55,26 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
To use the bridge, you need to start a chat with `@whatsappbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/whatsapp/authentication.html).
### 💡 Set up Double Puppeting
Approximately in a minute after logging in, the bridge will create portal rooms for recent chats.
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
**Note**: your linked devices will be logged out if you don’t use your phone for over 14 days (see the official FAQ entry [here](https://faq.whatsapp.com/general/download-and-installation/about-linked-devices)). The bridge will warn you if it doesn't receive any data from the phone over 12 days.
To set it up, you have 2 ways of going about it.
## Troubleshooting
#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
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-mautrix-whatsapp`.
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
### Increase logging verbosity
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
```yaml
# Valid values: fatal, error, warn, info, debug, trace
matrix_mautrix_whatsapp_logging_level: 'debug'
```
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Whatsapp` device some time in the future, as that would break the Double Puppeting feature

36
docs/configuring-playbook-bridge-mautrix-wsproxy.md
View File

@ -1,25 +1,9 @@
<!--
SPDX-FileCopyrightText: 2023 Johan Swetzén
SPDX-FileCopyrightText: 2023 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Mautrix wsproxy for bridging Android SMS or Apple iMessage (optional)
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
The playbook can install and configure [mautrix-wsproxy](https://github.com/mautrix/wsproxy) for you.
See the project's [documentation](https://github.com/mautrix/wsproxy/blob/master/README.md) to learn what it does and why it might be useful to you.
## Adjusting DNS records
By default, this playbook installs wsproxy on the `wsproxy.` subdomain (`wsproxy.example.com`) and requires you to create a CNAME record for `wsproxy`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -36,24 +20,24 @@ matrix_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge'
Note that the tokens must match what is compiled into the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android device.
### Adjusting the wsproxy URL (optional)
### Adjusting the wsproxy URL
By default, this playbook installs wsproxy on the `wsproxy.` subdomain (`wsproxy.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_mautrix_wsproxy_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
Example additional configuration for your `vars.yml` file:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname
matrix_mautrix_wsproxy_hostname: ws.example.com
```
After changing the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server.
## Adjusting DNS records
### Extending the configuration
Once you've decided on the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server.
There are some additional things you may wish to configure about the bridge.
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
By default, you will need to create a CNAME record for `wsproxy`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
## Installing
@ -74,8 +58,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
Follow the [mautrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).
## 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-mautrix-wsproxy`.
Follow the [matrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).

11
docs/configuring-playbook-bridge-mx-puppet-discord.md
View File

@ -1,15 +1,6 @@
<!--
SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 Hugues Morisset
SPDX-FileCopyrightText: 2022 MDAD project contributors
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up MX Puppet Discord bridging (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md)and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md)and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.
- For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing.
- For personal use with a discord account we recommend the [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridge, because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.

9
docs/configuring-playbook-bridge-mx-puppet-groupme.md
View File

@ -1,12 +1,3 @@
<!--
SPDX-FileCopyrightText: 2021 Cody Neiman
SPDX-FileCopyrightText: 2021 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 Cody Wyatt Neiman
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up MX Puppet GroupMe bridging (optional)
The playbook can install and configure [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) for you.

7
docs/configuring-playbook-bridge-mx-puppet-instagram.md
View File

@ -1,10 +1,3 @@
<!--
SPDX-FileCopyrightText: 2021 MDAD project contributors
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up MX Puppet Instagram bridging (optional)
The playbook can install and configure [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) for you.

10
docs/configuring-playbook-bridge-mx-puppet-skype.md
View File

@ -1,13 +1,5 @@
<!--
SPDX-FileCopyrightText: 2020 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 Rodrigo Belem
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up MX Puppet Skype bridging (optional, removed)
🪦 The playbook used to be able to install and configure [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype), but no longer includes this component, because it has been broken and unmaintained for a long time.
The playbook used to be able to install and configure [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype), but no longer includes this component, because it has been broken and unmaintained for a long time.
Bridging to [Skype](https://www.skype.com/) can also happen via the [go-skype-bridge](configuring-playbook-bridge-go-skype-bridge.md) bridge supported by the playbook.

11
docs/configuring-playbook-bridge-mx-puppet-slack.md
View File

@ -1,14 +1,3 @@
<!--
SPDX-FileCopyrightText: 2020 - 2023 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 Rodrigo Belem
SPDX-FileCopyrightText: 2021 Marcel Ackermann
SPDX-FileCopyrightText: 2022 Jim Myhrberg
SPDX-FileCopyrightText: 2022 Nikita Chernyi
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up MX Puppet Slack bridging (optional)
**Note**: bridging to [Slack](https://slack.com) can also happen via the [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges supported by the playbook. Note that `matrix-appservice-slack` is not available for new installation unless you have already created a classic Slack application, because the creation of classic Slack applications, which this bridge makes use of, has been discontinued.

9
docs/configuring-playbook-bridge-mx-puppet-steam.md
View File

@ -1,12 +1,3 @@
<!--
SPDX-FileCopyrightText: 2020 - 2021 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 Hugues Morisset
SPDX-FileCopyrightText: 2020 Panagiotis Vasilopoulos
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up MX Puppet Steam bridging (optional)
The playbook can install and configure [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) for you.

8
docs/configuring-playbook-bridge-mx-puppet-twitter.md
View File

@ -1,11 +1,3 @@
<!--
SPDX-FileCopyrightText: 2020 Tulir Asokan
SPDX-FileCopyrightText: 2021 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up MX Puppet Twitter bridging (optional)
**Note**: bridging to [Twitter](https://twitter.com/) can also happen via the [mautrix-twitter](configuring-playbook-bridge-mautrix-twitter.md) bridge supported by the playbook.

42
docs/configuring-playbook-bridge-postmoogle.md
View File

@ -1,14 +1,7 @@
<!--
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 Nikita Chernyi
SPDX-FileCopyrightText: 2023 Luke D Iremadze
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Postmoogle email bridging (optional)
**Note**: email bridging can also happen via the [email2matrix](configuring-playbook-email2matrix.md) bridge supported by the playbook.
The playbook can install and configure [Postmoogle](https://github.com/etkecc/postmoogle) for you.
Postmoogle is a bridge you can use to have its bot user forward emails to Matrix rooms. It runs an SMTP email server and allows you to assign mailbox addresses to the rooms.
@ -26,19 +19,6 @@ If you don't open these ports, you will still be able to send emails, but not re
These port numbers are configurable via the `matrix_postmoogle_smtp_host_bind_port` and `matrix_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use.
## Adjusting DNS records
To make Postmoogle enable its email sending features, you need to configure MX and TXT (SPF, DMARC, and DKIM) records. See the table below for values which need to be specified.
| Type | Host | Priority | Weight | Port | Target |
|------|--------------------------------|----------|--------|------|------------------------------------|
| MX | `matrix` | 10 | 0 | - | `matrix.example.com` |
| TXT | `matrix` | - | - | - | `v=spf1 ip4:matrix-server-IP -all` |
| TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` |
| TXT | `postmoogle._domainkey.matrix` | - | - | - | get it from `!pm dkim` |
**Note**: the DKIM record can be retrieved after configuring and installing the bridge's bot.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -57,18 +37,14 @@ matrix_postmoogle_password: PASSWORD_FOR_THE_BOT
# matrix_postmoogle_admins:
# - '@yourAdminAccount:{{ matrix_domain }}'
#
# … unless you've made yourself an admin of all bots/bridges like this:
# .. unless you've made yourself an admin of all bots/bridges like this:
#
# matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
```
### Extending the configuration
## Adjusting DNS records
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-postmoogle/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
You will also need to add several DNS records so that Postmoogle can send emails. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
## Installing
@ -99,13 +75,11 @@ Send `!pm help` to the bot in the room to see the available commands.
You can also refer to the upstream [documentation](https://github.com/etkecc/postmoogle).
## Troubleshooting
### Debug/Logs
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-postmoogle`.
As with all other services, you can find their logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by running something like `journalctl -fu matrix-postmoogle`
### Increase logging verbosity
The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
The default logging level for this bridge is `INFO`, but you can increase it to `DEBUG` with the following additional configuration:
```yaml
matrix_postmoogle_loglevel: 'DEBUG'

40
docs/configuring-playbook-bridge-wechat.md
View File

@ -1,19 +1,9 @@
<!--
SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up WeChat bridging (optional)
The playbook can install and configure [matrix-wechat](https://github.com/duo/matrix-wechat) for you, for bridging to [WeChat](https://www.wechat.com/).
The playbook can install and configure the [matrix-wechat](https://github.com/duo/matrix-wechat) bridge for you (for bridging to the [WeChat](https://www.wechat.com/) network).
See the project's [documentation](https://github.com/duo/matrix-wechat/blob/master/README.md) to learn what it does and why it might be useful to you.
> [!WARNING]
> This bridge does not work against newer versions of Synapse anymore. See [this issue](https://github.com/duo/matrix-wechat/issues/33). Don't even bother installing it. Unless bridge maintenance is resumed and fixes this issue, we have no choice but to remove it from the playbook.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -22,45 +12,25 @@ To enable the bridge, add the following configuration to your `inventory/host_va
matrix_wechat_enabled: true
```
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-wechat/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-wechat/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_wechat_configuration_extension_yaml` variable
## Installing
After configuring the playbook, run it 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
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
**Notes**:
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
- 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.
## Usage
To use the bridge, you need to start a chat with `@wechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Once the bridge is installed, start a chat with `@wechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `help` to the bot to see the available commands.
## 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-wechat`.
### Increase logging verbosity
The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Valid values: fatal, error, warn, info, debug
matrix_wechat_log_level: 'debug'
```

84
docs/configuring-playbook-cactus-comments.md
View File

@ -1,12 +1,3 @@
<!--
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
SPDX-FileCopyrightText: 2023 MDAD project contributors
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Cactus Comments (optional)
The playbook can install and configure the [Cactus Comments](https://cactus.chat) system for you.
@ -17,45 +8,43 @@ See the project's [documentation](https://cactus.chat/docs/getting-started/intro
The playbook contains 2 roles for configuring different pieces of the Cactus Comments system:
- `matrix-cactus-comments` — the backend appservice integrating with the Matrix homeserver
- `matrix-cactus-comments` - the backend appservice integrating with the Matrix homeserver
- `matrix-cactus-comments-client` — a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`)
- `matrix-cactus-comments-client` - a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`)
You can enable whichever component you need (typically both).
## Adjusting DNS records (optional)
By default, this playbook installs Cactus Comments' client on the `matrix.` subdomain, at the `/cactus-comments` path (https://matrix.example.com/cactus-comments). 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-cactus-comments-client-url-optional) for details about DNS configuration.
## Adjusting the playbook configuration
## Configuration
To enable Cactus Comments, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
#################
## Cactus Comments ##
#################
# This enables the backend (appservice)
matrix_cactus_comments_enabled: true
# This enables client assets static files serving on `https://matrix.example.com/cactus-comments`.
# When the backend (appservice) is enabled, this is also enabled automatically, but we explicitly enable it here.
matrix_cactus_comments_client_enabled: true
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_cactus_comments_user_id: "bot.cactusbot"
# To allow guest comments without users needing to log in, you need to have guest registration enabled.
# To do this you need to uncomment one of the following lines (depending if you are using Synapse or Dendrite as a homeserver)
# If you don't know which one you use: The default is Synapse ;)
# matrix_synapse_allow_guest_access: true
# matrix_dendrite_allow_guest_access: true
# This enables client assets static files serving on `https://matrix.example.com/cactus-comments`.
# When the backend (appservice) is enabled, this is also enabled automatically,
# but we explicitly enable it here.
matrix_cactus_comments_client_enabled: true
```
### Adjusting the Cactus Comments' client URL (optional)
### Adjusting the Cactus Comments' client URL
By default, this playbook installs Cactus Comments' client on the `matrix.` subdomain, at the `/cactus-comments` path (https://matrix.example.com/cactus-comments). 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.
By tweaking the `matrix_cactus_comments_client_hostname` and `matrix_cactus_comments_client_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix to host the client assets at a different location
@ -64,21 +53,13 @@ matrix_cactus_comments_client_hostname: cactus.example.com
matrix_cactus_comments_client_path_prefix: /
```
If you've changed the default hostname, you may need to create a CNAME record for the Cactus Comments' client domain (`cactus.example.com`), which targets `matrix.example.com`.
## Adjusting DNS records
When setting, replace `example.com` with your own.
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Cactus Comments' client domain to the Matrix server.
### Extending the configuration
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
There are some additional things you may wish to configure about the components.
For `matrix-cactus-comments`, take a look at:
- `roles/custom/matrix-cactus-comments/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
For `matrix-cactus-comments-client`, take a look at:
- `roles/custom/matrix-cactus-comments-client/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
@ -99,9 +80,11 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
To use the component, you need to start a chat with `@bot.cactusbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Upon starting Cactus Comments, a `bot.cactusbot` user account is created automatically.
Then, register a site by sending `register YOUR_SITE_NAME_HERE` (where `YOUR_SITE_NAME_HERE` is a unique identifier you choose. It does not have to match your domain). You will then be invited into a moderation room.
To get started, send `help` to the `@bot.cactusbot:example.com` bot to confirm it's working.
Then, register a site by sending `register <YourSiteName>` (where `<YourSiteName>` is a unique identifier you choose. It does not have to match your domain). You will then be invited into a moderation room.
Now you are good to go and can embed the comment section on your website!
@ -115,7 +98,7 @@ After including the JavaScript and CSS asset files, insert a `<div>` where you'd
<div id="comment-section"></div>
````
Then, you need to initialize the comment section. Make sure to replace `example.com` with your base domain and `YOUR_SITE_NAME_HERE` with the one that has been registered above:
Then, you need to initialize the comment section. Make sure to replace `example.com` with your base domain and `<YourSiteName>` with the one that has been registered above:
```html
<script>
@ -123,7 +106,7 @@ initComments({
node: document.getElementById("comment-section"),
defaultHomeserverUrl: "https://matrix.example.com:8448",
serverName: "example.com",
siteName: "YOUR_SITE_NAME_HERE",
siteName: "<YourSiteName>",
commentSectionId: "1"
})
</script>
@ -141,18 +124,3 @@ Make sure to replace `example.com` with your base domain before you include the
```
**Note**: if the `matrix_cactus_comments_client_hostname` and `matrix_cactus_comments_client_path_prefix` variables are tweaked, you would need to adjust the URLs of the assets accordingly.
## 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-cactus-comments` for the backend appservice or `journalctl -fu matrix-cactus-comments-client` for the server serving the client assets, respectively.
### Increase logging verbosity
It is possible to increase logging verbosity for `matrix-cactus-comments-client`. The default logging level for this component is `error`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
# Controls the SERVER_LOG_LEVEL environment variable.
# See: https://static-web-server.net/configuration/environment-variables/
# Valid values: error, warn, info, debug, trace
matrix_cactus_comments_client_environment_variable_server_log_level: debug
```

44
docs/configuring-playbook-client-cinny.md
View File

@ -1,14 +1,6 @@
<!--
SPDX-FileCopyrightText: 2022 MDAD project contributors
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Cinny (optional)
The playbook can install and configure the [Cinny](https://github.com/ajbura/cinny) Matrix web client for you.
This playbook can install the [Cinny](https://github.com/ajbura/cinny) Matrix web client for you.
Cinny is a web client focusing primarily on simple, elegant and secure interface. It can be installed alongside or instead of [Element Web](./configuring-playbook-client-element-web.md).
@ -16,12 +8,6 @@ Cinny is a web client focusing primarily on simple, elegant and secure interface
- [app.cinny.in](https://app.cinny.in), hosted by the [Cinny](https://cinny.in/) developers
## Adjusting DNS records
By default, this playbook installs Cinny on the `cinny.` subdomain (`cinny.example.com`) and requires you to create a CNAME record for `cinny`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
## Adjusting the playbook configuration
To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -30,32 +16,28 @@ To enable Cinny, add the following configuration to your `inventory/host_vars/ma
matrix_client_cinny_enabled: true
```
### Adjusting the Cinny URL (optional)
### Adjusting the Cinny URL
By default, this playbook installs Cinny on the `cinny.` subdomain (`cinny.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_client_cinny_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
Example additional configuration for your `vars.yml` file:
While a `matrix_client_cinny_path_prefix` variable exists for tweaking the path-prefix, it's [not supported anymore](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3701), because Cinny requires an application rebuild (with a tweaked build config) to be functional under a custom path.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to a different domain (`app.example.com`) than the default one (`cinny.example.com`)
matrix_client_cinny_hostname: "app.{{ matrix_domain }}"
# Expose under the /cinny subpath
# matrix_client_cinny_path_prefix: /cinny
```
After changing the domain, **you may need to adjust your DNS** records to point the Cinny domain to the Matrix server.
## Adjusting DNS records
**Note**: while there is a `matrix_client_cinny_path_prefix` variable for changing the path where Cinny is served, overriding it is [not possible](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3701), because Cinny requires an application rebuild (with a tweaked build config) to be functional under a custom path. You'd need to serve Cinny at a dedicated subdomain.
Once you've decided on the domain, **you may need to adjust your DNS** records to point the Cinny domain to the Matrix server.
### Extending the configuration
By default, you will need to create a CNAME record for `cinny`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
There are some additional things you may wish to configure about the component.
Take a look at:
- `roles/custom/matrix-client-cinny/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-client-cinny/templates/config.json.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_client_cinny_configuration_extension_json` variable
If you've adjusted `matrix_client_cinny_hostname`, you will need to adjust your DNS configuration accordingly.
## Installing
@ -69,7 +51,3 @@ 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.
## 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-client-cinny`.

123
docs/configuring-playbook-client-element-web.md
View File

@ -1,83 +1,53 @@
<!--
SPDX-FileCopyrightText: 2020 - 2022 MDAD project contributors
SPDX-FileCopyrightText: 2020 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 Aaron Raimist
SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Configuring Element Web (optional)
By default, this playbook installs the [Element Web](https://github.com/element-hq/element-web) Matrix client for you. If that's okay, you can skip this document.
If you'd like to stop the playbook installing the client, see the section [below](#disabling-element-web) to check the configuration for disabling it.
💡 **Note**: the latest version of Element Web is also available on the web, hosted by 3rd parties. If you trust giving your credentials to the following 3rd party Single Page Applications, you can consider using it from there and avoiding the (small) overhead of self-hosting (by [disabling Element Web](#disabling-element-web)):
- [app.element.io](https://app.element.io/), hosted by [Element](https://element.io/)
- [app.etke.cc](https://app.etke.cc/), hosted by [etke.cc](https://etke.cc/)
## Adjusting DNS records
## Disabling Element Web
By default, this playbook installs Element Web on the `element.` subdomain (`element.example.com`) and requires you to create a CNAME record for `element`, which targets `matrix.example.com`.
If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
When setting, replace `example.com` with your own.
```yaml
matrix_client_element_enabled: false
```
## Adjusting the playbook configuration
### Set the country code for phone number inputs
The playbook provides some customization variables you could use to change Element Web's settings.
You can change the country code (default: `GB`) to use when showing phone number inputs. To change it to `FR` for example, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
Their defaults are defined in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-element/templates/config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2) template.
```yaml
matrix_client_element_default_country_code: "FR"
```
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for an Element Web setting you wish to change:
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Element Web's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2)) by making use of the `matrix_client_element_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
### Themes
#### Change the default theme
To change the look of Element Web, you can define your own themes manually by using the `matrix_client_element_setting_defaults_custom_themes` setting.
You can change the default theme from `light` to `dark`. To do so, add the following configuration to your `vars.yml` file:
```yaml
# Controls the default theme
matrix_client_element_default_theme: 'dark'
```
#### Use themes by `element-themes`
You can change the look of Element Web by pulling themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project or defining your own themes manually.
To pull the themes and use them for your Element Web instance, add the following configuration to your `vars.yml` file:
```yaml
matrix_client_element_themes_enabled: true
```
If the variable is set to `true`, all themes found in the repository specified with `matrix_client_element_themes_repository_url` will be installed and enabled automatically.
Note that for a custom theme to work well, all Element Web instances that you use must have the same theme installed.
#### Define themes manually
You can also define your own themes manually by adding and adjusting the following configuration to your `vars.yml` file:
```yaml
# Controls the `setting_defaults.custom_themes` setting of the Element Web configuration.
matrix_client_element_setting_defaults_custom_themes: []
```
If you define your own themes with it and set `matrix_client_element_themes_enabled` to `true` for the themes by `element-themes`, your themes will be preserved as well.
Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_element_themes_enabled: true`).
If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
### Adjusting the Element Web URL (optional)
Note that for a custom theme to work well, all Element Web instances that you use must have the same theme installed.
### Adjusting the Element Web URL
By default, this playbook installs Element Web on the `element.` subdomain (`element.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_client_element_hostname` and `matrix_client_element_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
@ -88,45 +58,14 @@ matrix_client_element_hostname: "{{ matrix_server_fqn_matrix }}"
matrix_client_element_path_prefix: /element
```
After changing the domain, **you may need to adjust your DNS** records to point the Element domain to the Matrix server.
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Element Web domain to the Matrix server.
By default, you will need to create a CNAME record for `element`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
### Extending the configuration
There are some additional things you may wish to configure about the component.
Take a look at:
- `roles/custom/matrix-client-element/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-client-element/templates/config.json.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_client_element_configuration_extension_json` variable
For example, to override some Element Web settings, add the following configuration to your `vars.yml` file:
```yaml
# Your custom JSON configuration for Element Web should go to `matrix_client_element_configuration_extension_json`.
# This configuration extends the default starting configuration (`matrix_client_element_configuration_default`).
#
# You can override individual variables from the default configuration, or introduce new ones.
#
# If you need something more special, you can take full control by
# completely redefining `matrix_client_element_configuration_default`.
#
matrix_client_element_configuration_extension_json: |
{
"disable_3pid_login": true,
"disable_login_language_selector": true
}
```
## Disabling Element Web
If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `vars.yml` file:
```yaml
matrix_client_element_enabled: false
```
## 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:
@ -139,7 +78,3 @@ 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.
## 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-client-element`.

66
docs/configuring-playbook-client-fluffychat-web.md
View File

@ -1,66 +0,0 @@
<!--
SPDX-FileCopyrightText: 2025 Nikita Chernyi
SPDX-FileCopyrightText: 2025 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up FluffyChat Web (optional)
The playbook can install and configure the [FluffyChat Web](https://github.com/krille-chan/fluffychat) Matrix client for you.
FluffyChat Web is a cute cross-platform (web, iOS, Android) messenger for Matrix written in [Flutter](https://flutter.dev/).
💡 **Note**: the latest version of FluffyChat Web is also available on the web, hosted by 3rd parties. If you trust giving your credentials to the following 3rd party Single Page Application, you can consider using it from there:
- [fluffychat.im](https://fluffychat.im/web), hosted by the [FluffyChat](https://fluffychat.im/) developers
## Adjusting DNS records
By default, this playbook installs FluffyChat Web on the `fluffychat.` subdomain (`fluffychat.example.com`) and requires you to create a CNAME record for `fluffychat`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
## Adjusting the playbook configuration
To enable FluffyChat Web, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_client_fluffychat_enabled: true
```
### Adjusting the FluffyChat Web URL (optional)
By tweaking the `matrix_client_fluffychat_hostname` and `matrix_client_fluffychat_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
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for FluffyChat Web.
matrix_client_fluffychat_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /fluffychat subpath
matrix_client_fluffychat_path_prefix: /fluffychat
```
After changing the domain, **you may need to adjust your DNS** records to point the FluffyChat Web domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## 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.
## 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-client-fluffychat`.

42
docs/configuring-playbook-client-hydrogen.md
View File

@ -1,24 +1,9 @@
<!--
SPDX-FileCopyrightText: 2021 Aaron Raimist
SPDX-FileCopyrightText: 2021 MDAD project contributors
SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
SPDX-FileCopyrightText: 2024 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Hydrogen (optional)
The playbook can install and configure the [Hydrogen](https://github.com/element-hq/hydrogen-web) Matrix web client for you.
This playbook can install the [Hydrogen](https://github.com/element-hq/hydrogen-web) Matrix web client for you.
Hydrogen is a lightweight web client that supports mobile and legacy web browsers. It can be installed alongside or instead of Element Web.
## Adjusting DNS records
By default, this playbook installs Hydrogen on the `hydrogen.` subdomain (`hydrogen.example.com`) and requires you to create a CNAME record for `hydrogen`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
## Adjusting the playbook configuration
To enable Hydrogen, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -27,11 +12,13 @@ To enable Hydrogen, add the following configuration to your `inventory/host_vars
matrix_client_hydrogen_enabled: true
```
### Adjusting the Hydrogen URL (optional)
### Adjusting the Hydrogen URL
By default, this playbook installs Hydrogen on the `hydrogen.` subdomain (`hydrogen.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_client_hydrogen_hostname` and `matrix_client_hydrogen_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
@ -42,19 +29,14 @@ matrix_client_hydrogen_hostname: "{{ matrix_server_fqn_matrix }}"
matrix_client_hydrogen_path_prefix: /hydrogen
```
After changing the domain, **you may need to adjust your DNS** records to point the Hydrogen domain to the Matrix server.
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Hydrogen domain to the Matrix server.
By default, you will need to create a CNAME record for `hydrogen`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
### Extending the configuration
There are some additional things you may wish to configure about the client.
Take a look at:
- `roles/custom/matrix-client-hydrogen/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-client-hydrogen/templates/config.json.j2` for the client's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_client_hydrogen_configuration_extension_json` variable
## 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:
@ -67,7 +49,3 @@ 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.
## 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-client-hydrogen`.

111
docs/configuring-playbook-client-schildichat-web.md
View File

@ -1,14 +1,6 @@
<!--
SPDX-FileCopyrightText: 2023 Nikita Chernyi
SPDX-FileCopyrightText: 2023 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up SchildiChat Web (optional)
The playbook can install and configure the [SchildiChat Web](https://github.com/SchildiChat/schildichat-desktop) Matrix client for you.
This playbook can install the [SchildiChat Web](https://github.com/SchildiChat/schildichat-desktop) Matrix client for you.
SchildiChat Web is a feature-rich messenger for Matrix based on Element Web with some extras and tweaks. It can be installed alongside or instead of Element Web.
@ -16,12 +8,6 @@ SchildiChat Web is a feature-rich messenger for Matrix based on Element Web with
- [app.schildi.chat](https://app.schildi.chat/), hosted by the [SchildiChat](https://schildi.chat/) developers
## Adjusting DNS records
By default, this playbook installs SchildiChat Web on the `schildichat.` subdomain (`schildichat.example.com`) and requires you to create a CNAME record for `schildichat`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
## Adjusting the playbook configuration
To enable SchildiChat Web, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -30,57 +16,37 @@ To enable SchildiChat Web, add the following configuration to your `inventory/ho
matrix_client_schildichat_enabled: true
```
### Set the country code for phone number inputs
The playbook provides some customization variables you could use to change SchildiChat Web's settings.
You can change the country code (default: `GB`) to use when showing phone number inputs. To change it to `FR` for example, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
Their defaults are defined in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml) and they ultimately end up in the generated `/matrix/schildichat/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-schildichat/templates/config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2) template.
```yaml
matrix_client_schildichat_default_country_code: "FR"
```
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for a SchildiChat Web setting you wish to change:
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of SchildiChat Web's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2)) by making use of the `matrix_client_schildichat_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_schildichat_configuration_default` (or `matrix_client_schildichat_configuration`). You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
### Themes
#### Change the default theme
To change the look of SchildiChat Web, you can define your own themes manually by using the `matrix_client_schildichat_setting_defaults_custom_themes` setting.
You can change the default theme from `light` to `dark`. To do so, add the following configuration to your `vars.yml` file:
```yaml
# Controls the default theme
matrix_client_schildichat_default_theme: 'dark'
```
#### Use themes by `element-themes`
You can change the look of SchildiChat Web by pulling themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project or defining your own themes manually.
To pull the themes and use them for your SchildiChat Web instance, add the following configuration to your `vars.yml` file:
```yaml
matrix_client_schildichat_themes_enabled: true
```
If the variable is set to `true`, all themes found in the repository specified with `matrix_client_schildichat_themes_repository_url` will be installed and enabled automatically.
Note that for a custom theme to work well, all SchildiChat Web instances that you use must have the same theme installed.
#### Define themes manually
You can also define your own themes manually by adding and adjusting the following configuration to your `vars.yml` file:
```yaml
# Controls the `setting_defaults.custom_themes` setting of the SchildiChat Web configuration.
matrix_client_schildichat_setting_defaults_custom_themes: []
```
If you define your own themes with it and set `matrix_client_schildichat_themes_enabled` to `true` for the themes by `element-themes`, your themes will be preserved as well.
Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_schildichat_themes_enabled: true`).
If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
### Adjusting the SchildiChat Web URL (optional)
Note that for a custom theme to work well, all SchildiChat Web instances that you use must have the same theme installed.
### Adjusting the SchildiChat Web URL
By default, this playbook installs SchildiChat Web on the `schildichat.` subdomain (`schildichat.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_client_schildichat_hostname` and `matrix_client_schildichat_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
@ -91,37 +57,14 @@ matrix_client_schildichat_hostname: "{{ matrix_server_fqn_matrix }}"
matrix_client_schildichat_path_prefix: /schildichat
```
After changing the domain, **you may need to adjust your DNS** records to point the SchildiChat Web domain to the Matrix server.
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the SchildiChat Web domain to the Matrix server.
By default, you will need to create a CNAME record for `schildichat`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
### Extending the configuration
There are some additional things you may wish to configure about the component.
Take a look at:
- `roles/custom/matrix-client-schildichat/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-client-schildichat/templates/config.json.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_client_schildichat_configuration_extension_json` variable
For example, to override some SchildiChat Web settings, add the following configuration to your `vars.yml` file:
```yaml
# Your custom JSON configuration for SchildiChat Web should go to `matrix_client_schildichat_configuration_extension_json`.
# This configuration extends the default starting configuration (`matrix_client_schildichat_configuration_default`).
#
# You can override individual variables from the default configuration, or introduce new ones.
#
# If you need something more special, you can take full control by
# completely redefining `matrix_client_schildichat_configuration_default`.
#
matrix_client_schildichat_configuration_extension_json: |
{
"disable_3pid_login": true,
"disable_login_language_selector": true
}
```
## 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:
@ -134,7 +77,3 @@ 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.
## 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-client-schildichat`.

46
docs/configuring-playbook-conduit.md
View File

@ -1,53 +1,27 @@
<!--
SPDX-FileCopyrightText: 2022 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Configuring Conduit (optional)
The playbook can install and configure the [Conduit](https://conduit.rs) Matrix server for you.
By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Conduit](https://conduit.rs).
See the project's [documentation](https://docs.conduit.rs/) to learn what it does and why it might be useful to you.
**Notes**:
By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Conduit). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
💡 **Note**: The playbook also supports installing a (currently) faster-moving Conduit fork called [conduwuit](./configuring-playbook-conduwuit.md).
> [!WARNING]
> - **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Conduit). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
> - **Homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
- **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
## Adjusting the playbook configuration
To use Conduit, you **generally** need to adjust the `matrix_homeserver_implementation: synapse` configuration on your `inventory/host_vars/matrix.example.com/vars.yml` file as below:
To use Conduit, you **generally** need to add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_homeserver_implementation: conduit
```
### Extending the configuration
There are some additional things you may wish to configure about the server.
Take a look at:
- `roles/custom/matrix-conduit/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-conduit/templates/conduit.toml.j2` for the server's default configuration
If you'd like to have your own different configuration, feel free to copy and paste the original files into your inventory (e.g. in `inventory/host_vars/matrix.example.com/`) and then change the specific host's `vars.yml` file like this:
```yaml
matrix_conduit_template_conduit_config: "{{ playbook_dir }}/inventory/host_vars/matrix.example.com/conduit.toml.j2"
```
## Creating the first user account
Since it is difficult to create the first user account on Conduit (see [famedly/conduit#276](https://gitlab.com/famedly/conduit/-/issues/276) and [famedly/conduit#354](https://gitlab.com/famedly/conduit/-/merge_requests/354)) and it does not support [registering users](registering-users.md) (via the command line or via the playbook) like Synapse and Dendrite do, we recommend the following procedure:
1. Add `matrix_conduit_allow_registration: true` to your `vars.yml` the first time around, temporarily
2. Run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` — see [Installing](installing.md))
2. Run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` - see [Installing](installing.md))
3. Create your first user via Element Web or any other client which supports creating users
4. Get rid of `matrix_conduit_allow_registration: true` from your `vars.yml`
5. Run the playbook again (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-conduit,start` would be enough this time)
@ -55,9 +29,9 @@ Since it is difficult to create the first user account on Conduit (see [famedly/
## Configuring bridges / appservices
For other homeserver implementations (like Synapse and Dendrite), the playbook automatically registers appservices (for bridges, bots, etc.) with the homeserver.
Automatic appservice setup is currently unsupported when using Conduit. After setting up the service as usual you may notice that it is unable to start.
For Conduit, you will have to manually register appservices using the the [register-appservice](https://gitlab.com/famedly/conduit/-/blob/next/APPSERVICES.md) command.
You will have to manually register appservices using the the [register-appservice](https://gitlab.com/famedly/conduit/-/blob/next/APPSERVICES.md) command.
Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`, then pass the content to Conduit:
@ -80,7 +54,3 @@ Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/ma
sender_localpart: _bot_signalbot
url: http://matrix-mautrix-signal:29328
```
## 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-conduit`.

104
docs/configuring-playbook-conduwuit.md
View File

@ -1,104 +0,0 @@
<!--
SPDX-FileCopyrightText: 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Configuring conduwuit (optional)
The playbook can install and configure the [conduwuit](https://conduwuit.puppyirl.gay/) Matrix server for you.
See the project's [documentation](https://conduwuit.puppyirl.gay/) to learn what it does and why it might be useful to you.
By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
💡 **Note**: conduwuit is a fork of [Conduit](./configuring-playbook-conduit.md), which the playbook also supports. See [Differences from upstream Conduit](https://conduwuit.puppyirl.gay/differences.html).
> [!WARNING]
> - **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> conduwuit). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
> - **Homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
## Adjusting the playbook configuration
To use conduwuit, you **generally** need to adjust the `matrix_homeserver_implementation: synapse` configuration on your `inventory/host_vars/matrix.example.com/vars.yml` file as below:
```yaml
matrix_homeserver_implementation: conduwuit
# Registering users can only happen via the API,
# so it makes sense to enable it, at least initially.
matrix_conduwuit_config_allow_registration: true
# Generate a strong registration token to protect the registration endpoint from abuse.
# You can create one with a command like `pwgen -s 64 1`.
matrix_conduwuit_config_registration_token: ''
```
### Extending the configuration
There are some additional things you may wish to configure about the server.
Take a look at:
- `roles/custom/matrix-conduwuit/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-conduwuit/templates/conduwuit.toml.j2` for the server's default configuration
There are various Ansible variables that control settings in the `conduwuit.toml` file.
If a specific setting you'd like to change does not have a dedicated Ansible variable, you can either submit a PR to us to add it, or you can [override the setting using an environment variable](https://conduwuit.puppyirl.gay/configuration.html#environment-variables) using `matrix_conduwuit_environment_variables_extension`. For example:
```yaml
matrix_conduwuit_environment_variables_extension: |
CONDUWUIT_MAX_REQUEST_SIZE=50000000
CONDUWUIT_REQUEST_TIMEOUT=60
```
## Creating the first user account
Unlike other homeserver implementations (like Synapse and Dendrite), conduwuit does not support creating users via the command line or via the playbook.
If you followed the instructions above (see [Adjusting the playbook configuration](#adjusting-the-playbook-configuration)), you should have registration enabled and protected by a registration token.
This should allow you to create the first user account via any client (like [Element Web](./configuring-playbook-client-element-web.md)) which supports creating users.
The **first user account that you create will be marked as an admin** and **will be automatically invited to an admin room**.
## Configuring bridges / appservices
For other homeserver implementations (like Synapse and Dendrite), the playbook automatically registers appservices (for bridges, bots, etc.) with the homeserver.
For conduwuit, you will have to manually register appservices using the [`!admin appservices register` command](https://conduwuit.puppyirl.gay/appservices.html#set-up-the-appservice---general-instructions) sent to the server bot account.
The server's bot account has a Matrix ID of `@conduit:example.com` (not `@conduwuit:example.com`!) due to conduwuit's historical legacy.
Your first user account would already have been invited to an admin room with this bot.
Find the appservice file you'd like to register. This can be any `registration.yaml` file found in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`.
Then, send its content to the existing admin room:
!admin appservices register
```
as_token: <token>
de.sorunome.msc2409.push_ephemeral: true
hs_token: <token>
id: signal
namespaces:
aliases:
- exclusive: true
regex: ^#signal_.+:example\.org$
users:
- exclusive: true
regex: ^@signal_.+:example\.org$
- exclusive: true
regex: ^@signalbot:example\.org$
rate_limited: false
sender_localpart: _bot_signalbot
url: http://matrix-mautrix-signal:29328
```
## 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-conduwuit`.

67
docs/configuring-playbook-dendrite.md
View File

@ -1,60 +1,34 @@
<!--
SPDX-FileCopyrightText: 2022 MDAD project contributors
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Configuring Dendrite (optional)
The playbook can install and configure the [Dendrite](https://github.com/element-hq/dendrite) Matrix server for you.
By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Dendrite](https://github.com/matrix-org/dendrite).
See the project's [documentation](https://element-hq.github.io/dendrite/) to learn what it does and why it might be useful to you.
**Notes**:
By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Dendrite). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
> [!WARNING]
> - **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Dendrite). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
> - **Homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
- **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
## Adjusting the playbook configuration
To use Dendrite, you **generally** need to adjust the `matrix_homeserver_implementation: synapse` configuration on your `inventory/host_vars/matrix.example.com/vars.yml` file as below:
To use Dendrite, you **generally** need to add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_homeserver_implementation: dendrite
```
### Extending the configuration
The playbook provides lots of customization variables you could use to change Dendrite's settings.
There are some additional things you may wish to configure about the server.
Their defaults are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2) template.
Take a look at:
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
- `roles/custom/matrix-dendrite/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-dendrite/templates/dendrite.yaml.j2` for the server's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_dendrite_configuration_extension_yaml` variable
Alternatively, **if there is no pre-defined variable** for a Dendrite setting you wish to change:
For example, to override some Dendrite settings, add the following configuration to your `vars.yml` file:
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Dendrite's various settings that rarely get used.
```yaml
matrix_dendrite_configuration_extension_yaml: |
# Your custom YAML configuration for Dendrite goes here.
# This configuration extends the default starting configuration (`matrix_dendrite_configuration_yaml`).
#
# You can override individual variables from the default configuration, or introduce new ones.
#
# If you need something more special, you can take full control by
# completely redefining `matrix_dendrite_configuration_yaml`.
#
# Example configuration extension follows:
#
server_notices:
system_mxid_localpart: notices
system_mxid_display_name: "Server Notices"
system_mxid_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ"
room_name: "Server Notices"
```
- or, you can **extend and override the default configuration** ([`dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2)) by making use of the `matrix_dendrite_configuration_extension_yaml` variable. You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_dendrite_configuration` (or `matrix_dendrite_configuration_yaml`). You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
## Installing
@ -68,18 +42,3 @@ 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.
## 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-dendrite`.
### Increase logging verbosity
The default logging level for this component is `warning`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
```yaml
matrix_dendrite_configuration_extension_yaml: |
logging:
- type: std
level: debug
```

119
docs/configuring-playbook-dimension.md
View File

@ -1,76 +1,22 @@
<!--
SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 - 2025 MDAD project contributors
SPDX-FileCopyrightText: 2019 Edgars Voroboks
SPDX-FileCopyrightText: 2020 Chris van Dijk
SPDX-FileCopyrightText: 2020 jens quade
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Kim Brose
SPDX-FileCopyrightText: 2022 Travis Ralston
SPDX-FileCopyrightText: 2022 Yan Minagawa
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Dimension integration manager (optional, unmaintained)
**Notes**:
- Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it.
- This playbook now supports running Dimension in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`.
**[Dimension](https://dimension.t2bot.io) can only be installed after Matrix services are installed and running.** If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) flow and come back here later.
The playbook can install and configure the [Dimension](https://dimension.t2bot.io) integration manager for you.
**Note**: Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it.
See the project's [documentation](https://github.com/turt2live/matrix-dimension/blob/master/README.md) to learn what it does and why it might be useful to you.
## Prerequisites
### Open Matrix Federation port
Enabling the Dimension service will automatically reconfigure your Synapse homeserver to expose the `openid` API endpoints on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. If you enable the component, make sure that the port is accessible.
### Install Matrix services
Dimension can only be installed after Matrix services are installed and running. If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) and come back here later.
### Register a dedicated Matrix user (optional, recommended)
We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username).
Generate a strong password for the user. You can create one with a command like `pwgen -s 64 1`.
You can use the playbook to [register a new user](registering-users.md):
```sh
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=dimension password=PASSWORD_FOR_THE_USER admin=no' --tags=register-user
```
### Obtain an access token
Dimension requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
> [!WARNING]
> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
## Adjusting DNS records
By default, this playbook installs Dimension on the `dimension.` subdomain (`dimension.example.com`) and requires you to create a CNAME record for `dimension`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
**Note**: This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`. Enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
## Adjusting the playbook configuration
To enable Dimension, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_dimension_enabled: true
matrix_dimension_access_token: "ACCESS_TOKEN_HERE"
```
### Define admin users
To define admin users who can modify the integrations this Dimension supports, add the following configuration to your `vars.yml` file:
These users can modify the integrations this Dimension supports. Add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_dimension_admins:
@ -80,11 +26,29 @@ matrix_dimension_admins:
The admin interface is accessible within Element Web by accessing it in any room and clicking the cog wheel/settings icon in the top right. Currently, Dimension can be opened in Element Web by the "Add widgets, bridges, & bots" link in the room information.
### Adjusting the Dimension URL (optional)
### Obtain an access token
We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username). Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
You are required to specify an access token (belonging to this new user) for Dimension to work. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
Add access token to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_dimension_access_token: "YOUR ACCESS TOKEN HERE"
```
For more information on how to acquire an access token, visit [https://t2bot.io/docs/access_tokens](https://t2bot.io/docs/access_tokens).
### Adjusting the Dimension URL
By default, this playbook installs Dimension on the `dimension.` subdomain (`dimension.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_dimension_hostname` and `matrix_dimension_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
@ -95,22 +59,13 @@ matrix_dimension_hostname: "{{ matrix_server_fqn_matrix }}"
# matrix_dimension_path_prefix: /dimension
```
After changing the domain, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
**Note**: While there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You must serve Dimension at a dedicated subdomain.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Adjusting DNS records
**Note**: while there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You'd need to serve Dimension at a dedicated subdomain.
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
### Extending the configuration
There are some additional things you may wish to configure about the component.
Take a look at:
- `roles/custom/matrix-dimension/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-dimension/templates/config.yaml.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_dimension_configuration_extension_yaml` variable
You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).
By default, you will need to create a CNAME record for `dimension`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
## Installing
@ -127,18 +82,16 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
`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
- After Dimension has been installed you may need to log out and log back in for it to pick up the new integration manager. Then you can access integrations in Element Web by opening a room, clicking the Room info button (`i`) button in the top right corner of the screen, and then clicking Add widgets, bridges & bots.
After Dimension has been installed you may need to log out and log back in for it to pick up the new integration manager. Then you can access integrations in Element Web by opening a room, clicking the room info button (`i`) on the top right corner, and then clicking the "Add widgets, bridges, & bots" link.
## Jitsi domain
### Set up a Jitsi widget
By default Dimension will use [jitsi.riot.im](https://jitsi.riot.im/) as the `conferenceDomain` of [Jitsi](https://jitsi.org/) audio/video conference widgets. For users running [a self-hosted Jitsi instance](./configuring-playbook-jitsi.md), you will likely want the widget to use your own Jitsi instance. Currently there is no way to configure this via the playbook, see [this issue](https://github.com/turt2live/matrix-dimension/issues/345) for details.
By default Dimension will use [jitsi.riot.im](https://jitsi.riot.im/) as the `conferenceDomain` of [Jitsi](https://jitsi.org/) audio/video conference widgets. For users running [a self-hosted Jitsi instance](configuring-playbook-jitsi.md), you will likely want the widget to use your own Jitsi instance.
In the interim until the above limitation is resolved, an admin user needs to configure the domain via the admin ui once dimension is running. In Element Web, go to *Manage Integrations* &rightarrow; *Settings* &rightarrow; *Widgets* &rightarrow; *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
To set up the widget, an admin user needs to configure the domain via the admin UI once Dimension is running. In Element Web, go to *Manage Integrations* → *Settings* → *Widgets* → *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
## Additional features
There is unfortunately no way to configure the widget via the playbook. See [this issue](https://github.com/turt2live/matrix-dimension/issues/345) for details.
To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-dimension/defaults/main.yml) of the Dimension component.
## 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-dimension`.
You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).

20
docs/configuring-playbook-dynamic-dns.md
View File

@ -1,11 +1,3 @@
<!--
SPDX-FileCopyrightText: 2020 Scott Crossen
SPDX-FileCopyrightText: 2020 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Dynamic DNS (optional)
The playbook can configure Dynamic DNS with [ddclient⁠](https://github.com/ddclient/ddclient) for you. It is a Perl client used to update dynamic DNS entries for accounts on Dynamic DNS Network Service Provider.
@ -31,14 +23,6 @@ matrix_dynamic_dns_domain_configurations:
domain: "{{ matrix_domain }}"
```
### Extending the configuration
There are some additional things you may wish to configure about the component.
Take a look at:
- `roles/custom/matrix-dynamic-dns/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
## Installing
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@ -57,7 +41,3 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
Additional resources:
- https://matrix.org/docs/guides/free-small-matrix-server
## 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-dynamic-dns`.

82
docs/configuring-playbook-element-call.md
View File

@ -1,82 +0,0 @@
<!--
SPDX-FileCopyrightText: 2024 wjbeckett
SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Element Call (optional)
The playbook can install and configure [Element Call](https://github.com/element-hq/element-call) for you.
Element Call is a native Matrix video conferencing application developed by [Element](https://element.io), designed for secure, scalable, privacy-respecting, and decentralized video and voice calls over the Matrix protocol. Built on MatrixRTC ([MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143)), it utilizes [MSC4195](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md) with [LiveKit Server](configuring-playbook-livekit-server.md) as its backend.
See the project's [documentation](https://github.com/element-hq/element-call) to learn more.
## Prerequisites
- A [Synapse](configuring-playbook-synapse.md) homeserver (see the warning below)
- [Federation](configuring-playbook-federation.md) being enabled for your Matrix homeserver (federation is enabled by default, unless you've explicitly disabled it), because [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) currently [requires it](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3562#issuecomment-2725250554) ([relevant source code](https://github.com/element-hq/lk-jwt-service/blob/f5f5374c4bdcc00a4fb13d27c0b28e20e4c62334/main.go#L135-L146))
- Various experimental features for the Synapse homeserver which Element Call [requires](https://github.com/element-hq/element-call/blob/93ae2aed9841e0b066d515c56bd4c122d2b591b2/docs/self-hosting.md#a-matrix-homeserver) (automatically done when Element Call is enabled)
- A [LiveKit Server](configuring-playbook-livekit-server.md) (automatically installed when Element Call is enabled)
- The [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (automatically installed when Element Call is enabled)
- A client compatible with Element Call. As of 2025-03-15, that's just [Element Web](configuring-playbook-client-element-web.md) and the Element X mobile clients (iOS and Android).
> [!WARNING]
> Because Element Call [requires](https://github.com/element-hq/element-call/blob/93ae2aed9841e0b066d515c56bd4c122d2b591b2/docs/self-hosting.md#a-matrix-homeserver) a few experimental features in the Matrix protocol, it's **very likely that it only works with the Synapse homeserver**.
## Decide on a domain and path
By default, Element Call is configured to be served on the `call.element.example.com` domain.
If you'd like to run Element Call on another hostname, see the [Adjusting the Element Call URL](#adjusting-the-element-call-url-optional) section below.
## Adjusting DNS records
By default, this playbook installs Element Call on the `call.element.` subdomain (`call.element.example.com`) and requires you to create a `CNAME` record for `call.element`, which targets `matrix.example.com`.
When setting these values, replace `example.com` with your own.
All dependency services for Element Call ([LiveKit Server](configuring-playbook-livekit-server.md) and [Livekit JWT Service](configuring-playbook-livekit-jwt-service.md)) are installed and configured automatically by the playbook. By default, these services are installed on subpaths on the `matrix.` domain (e.g. `/livekit-server`, `/livekit-jwt-service`), so no DNS record adjustments are required for them.
## Adjusting firewall rules
In addition to the HTTP/HTTPS ports (which you've already exposed as per the [prerequisites](prerequisites.md) document), you'll also need to open ports required by [LiveKit Server](configuring-playbook-livekit-server.md) as described in its own [Adjusting firewall rules](configuring-playbook-livekit-server.md#adjusting-firewall-rules) section.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_element_call_enabled: true
```
### Adjusting the Element Call URL (optional)
By tweaking the `matrix_element_call_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
Example additional configuration for your `vars.yml` file:
```yaml
matrix_element_call_hostname: element-call.example.com
```
> [!WARNING]
> A `matrix_element_call_path_prefix` variable is also available and mean to let you configure a path prefix for the Element Call service, but [Element Call does not support running under a sub-path yet](https://github.com/element-hq/element-call/issues/3084).
## Installing
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records) and [adjusting firewall rules](#adjusting-firewall-rules), 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
Once installed, Element Call integrates seamlessly with Matrix clients like [Element Web](configuring-playbook-client-element-web.md) and Element X on mobile (iOS and Android).

82
docs/configuring-playbook-email.md
View File

@ -1,71 +1,53 @@
<!--
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 Eduardo Beltrame
SPDX-FileCopyrightText: 2020 - 2025 MDAD project contributors
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Adjusting email-sending settings (optional)
By default, this playbook sets up an [Exim](https://www.exim.org/) relay SMTP mailer service (powered by [exim-relay](https://github.com/devture/exim-relay) and the [ansible-role-exim-relay](https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay) Ansible role), through which all Matrix services send emails.
By default, this playbook sets up an [Exim](https://www.exim.org/) email server through which all Matrix services send emails.
**With the default setting, exim-relay attempts to deliver emails directly with the address `matrix@matrix.example.com`**, as specified by the `exim_relay_sender_address` playbook variable. See below if you want to configure the playbook to relay email through another SMTP server.
The email server would attempt to deliver emails directly to their final destination. This may or may not work, depending on your domain configuration (SPF settings, etc.)
The [Ansible role for exim-relay](https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay) is developed and maintained by [the MASH (mother-of-all-self-hosting) project](https://github.com/mother-of-all-self-hosting). For details about configuring exim-relay, you can check them via:
- 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay/blob/main/docs/configuring-exim-relay.md) online
- 📁 `roles/galaxy/exim_relay/docs/configuring-exim-relay.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
By default, emails are sent from `matrix@matrix.example.com`, as specified by the `exim_relay_sender_address` playbook variable.
⚠️ **Warning**: On some cloud providers (Google Cloud, etc.), [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so sending email directly from your server is not possible. You will need to [relay email through another SMTP server](#relaying-email-through-another-smtp-server).
💡 To improve deliverability, we recommend [relaying email through another SMTP server](#relaying-email-through-another-smtp-server) anyway.
## Firewall settings
No matter whether you send email directly (the default) or you relay email through another host, you'll probably need to allow outgoing traffic for TCP ports 25/587 (depending on configuration).
No matter whether you send email directly (the default) or you relay email through another host (see how below), you'll probably need to allow outgoing traffic for TCP ports 25/587 (depending on configuration).
Docker automatically opens these ports in the server's firewall, so you likely don't need to do anything. If you use another firewall in front of the server, you may need to adjust it.
## Relaying email through another SMTP server
## Adjusting the playbook configuration
### Enable DKIM authentication to improve deliverability (optional)
By default, exim-relay attempts to deliver emails directly. This may or may not work, depending on your domain configuration.
To improve email deliverability, you can configure authentication methods such as DKIM (DomainKeys Identified Mail), SPF, and DMARC for your domain. Without setting any of these authentication methods, your outgoing email is most likely to be quarantined as spam at recipient's mail servers.
For details about configuring DKIM, refer [this section](https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay/blob/main/docs/configuring-exim-relay.md#enable-dkim-support-optional) on the role's documentation.
💡 If you cannot enable DKIM, SPF, or DMARC on your domain for some reason, we recommend relaying email through another SMTP server.
### Relaying email through another SMTP server (optional)
**On some cloud providers such as Google Cloud, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so sending email directly from your server is not possible.** In this case, you will need to relay email through another SMTP server.
For details about configuration, refer [this section](https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay/blob/main/docs/configuring-exim-relay.md#relaying-email-through-another-smtp-server) on the role's document.
### Disable mail service (optional)
For a low-power server you might probably want to disable exim-relay. To do so, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
If you'd like to relay email through another SMTP server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
```yaml
exim_relay_enabled: false
exim_relay_sender_address: "another.sender@example.com"
exim_relay_relay_use: true
exim_relay_relay_host_name: "mail.example.com"
exim_relay_relay_host_port: 587
exim_relay_relay_auth: true
exim_relay_relay_auth_username: "another.sender@example.com"
exim_relay_relay_auth_password: "some-password"
```
Note that disabling exim-relay will stop email-notifications and other similar functions from working.
**Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.
See [this entry on the FAQ](faq.md#how-do-i-optimize-this-setup-for-a-low-power-server) for other possible optimizations for a low-power server.
### Configuations for sending emails using Sendgrid
## Installing
An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `exim_relay_sender_address`.
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
The only other thing you need to change is the `exim_relay_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
<!-- NOTE: 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
Note that the `exim_relay_relay_auth_username` is literally the string `apikey`, it's always the same for Sendgrid.
```yaml
exim_relay_sender_address: "arbitrary@email.com"
exim_relay_relay_use: true
exim_relay_relay_host_name: "smtp.sendgrid.net"
exim_relay_relay_host_port: 587
exim_relay_relay_auth: true
exim_relay_relay_auth_username: "apikey"
exim_relay_relay_auth_password: "<your api key password>"
```
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.
## Troubleshooting
See [this section](https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay/blob/main/docs/configuring-exim-relay.md#troubleshooting) on the role's documentation for details.
If you're having trouble with email not being delivered, it may be useful to inspect the mailer logs: `journalctl -f -u matrix-exim-relay`.

108
docs/configuring-playbook-email2matrix.md
View File

@ -1,26 +1,102 @@
<!--
SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 Dennis Ciba
SPDX-FileCopyrightText: 2022 Nikita Chernyi
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-FileCopyrightText: 2024 MDAD project contributors
# Setting up Email2Matrix (optional)
SPDX-License-Identifier: AGPL-3.0-or-later
-->
**Note**: email bridging can also happen via the [Postmoogle](configuring-playbook-bridge-postmoogle.md) bridge supported by the playbook. Postmoogle is much more powerful and easier to use, so we recommend that you use it, instead of Email2Matrix.
# Setting up Email2Matrix (optional, removed)
The playbook can install and configure [email2matrix](https://github.com/devture/email2matrix) for you.
🪦 The playbook used to be able to install and configure [Email2Matrix](https://github.com/devture/email2matrix), but no longer includes this component.
See the project's [documentation](https://github.com/devture/email2matrix/blob/master/docs/README.md) to learn what it does and why it might be useful to you.
For a long time now, it been replaced by the much better and more maintained [Postmoogle](https://github.com/etkecc/postmoogle) bridge, which can also be [installed using this playbook](configuring-playbook-bridge-postmoogle.md).
## Preparation
### DNS configuration
## Uninstalling Email2Matrix manually
It's not strictly necessary, but you may increase the chances that incoming emails reach your server by adding an `MX` record for `matrix.example.com`, as described in the [Configuring DNS](configuring-dns.md) documentation page.
If you still have the Email2Matrix component installed on your Matrix server, the playbook can no longer help you uninstall it and you will need to do it manually. To uninstall manually, run these commands on the server:
### Port availability
```sh
systemctl disable --now matrix-email2matrix.service
Ensure that port 25 is available on your Matrix server and open in your firewall.
rm -rf /matrix/email2matrix
If you have `postfix` or some other email server software installed, you may need to manually remove it first (unless you need it, of course).
If you really need to run an email server on the Matrix machine for other purposes, it may be possible to run Email2Matrix on another port (with a configuration like `matrix_email2matrix_smtp_host_bind_port: "127.0.0.01:2525"`) and have your other email server relay messages there.
For details about using Email2Matrix alongside [Postfix](http://www.postfix.org/), see [here](https://github.com/devture/email2matrix/blob/master/docs/setup_with_postfix.md).
### Creating a user
Before enabling Email2Matrix, you'd most likely wish to create a dedicated user (or more) that would be sending messages on the Matrix side. Take note of the user's ID as it needs to be specified as `MatrixUserId` on your `inventory/host_vars/matrix.example.com/vars.yml` file later.
Refer to [Registering users](registering-users.md) for ways to create a user. A regular (non-admin) user works best.
### Creating a shared room
After creating the sender user, you should create one or more Matrix rooms that you share with that user. It doesn't matter who creates and owns the rooms and who joins later (you or the sender user).
What matters is that both you and the sender user are part of the same room and that the sender user has enough privileges in the room to be able to send messages there.
Inviting additional people to the room is okay too.
Take note of each room's room ID (different clients show the room ID in a different place). You'll need the room ID when [configuring the playbook](#adjusting-the-playbook-configuration) below.
### Obtain an access token for the sender user
In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
## Adjusting the playbook configuration
After doing the preparation steps above, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
```yaml
matrix_email2matrix_enabled: true
matrix_email2matrix_matrix_mappings:
- MailboxName: "mailbox1"
MatrixRoomId: "!qporfwt:{{ matrix_domain }}"
MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
MatrixUserId: "@email2matrix1:{{ matrix_domain }}"
MatrixAccessToken: "MATRIX_ACCESS_TOKEN_HERE"
IgnoreSubject: false
IgnoreBody: false
SkipMarkdown: false
- MailboxName: "mailbox2"
MatrixRoomId: "!aaabaa:{{ matrix_domain }}"
MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
MatrixUserId: "@email2matrix2:{{ matrix_domain }}"
MatrixAccessToken: "MATRIX_ACCESS_TOKEN_HERE"
IgnoreSubject: true
IgnoreBody: false
SkipMarkdown: true
```
where:
* MailboxName - local-part of the email address, through which emails are bridged to the room whose ID is defined with MatrixRoomId
* MatrixRoomId - internal ID of the room, to which received emails are sent as Matrix message
* MatrixHomeserverUrl - URL of your Matrix homeserver, through which to send Matrix messages. You can also set `MatrixHomeserverUrl` to the container URL where your homeserver's Client-Server API lives by using the `{{ matrix_addons_homeserver_client_api_url }}` variable
* MatrixUserId - the full ID of the sender user which sends bridged messages to the room. On this configuration it is `@email2matrix1:example.com` and `@email2matrix2:example.com` (where `example.com` is your base domain, not the `matrix.` domain)
* MatrixAccessToken - sender user's access token
* IgnoreSubject - if set to "true", the subject is not bridged to Matrix
* IgnoreBody - if set to "true", the message body is not bridged to Matrix
* SkipMarkdown - if set to "true", emails are bridged as plain text Matrix message instead of Markdown (actually HTML)
Refer to the official documentation [here](https://github.com/devture/email2matrix/blob/master/docs/configuration.md).
## Installing
After configuring the playbook, run it 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
```
**Notes**:
- The shortcut commands with the [`just` program](just.md) are also available: `just install-service email2matrix` or `just setup-all`
`just install-service email2matrix` is useful for maintaining your setup quickly 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 `just setup-all` runs the `ensure-matrix-users-created` tag too.
- After installation, you may wish to send a test email to the email address assigned to `mailbox1` (default: `mailbox1@matrix.example.com`) to make sure that Email2Matrix works as expected.

99
docs/configuring-playbook-etherpad.md
View File

@ -1,71 +1,28 @@
<!--
SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2021 Béla Becker
SPDX-FileCopyrightText: 2021 pushytoxin
SPDX-FileCopyrightText: 2022 Jim Myhrberg
SPDX-FileCopyrightText: 2022 Nikita Chernyi
SPDX-FileCopyrightText: 2022 felixx9
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up Etherpad (optional)
The playbook can install and configure [Etherpad](https://etherpad.org) for you.
[Etherpad](https://etherpad.org) is an open source collaborative text editor that can be embedded in a Matrix chat room using the [Dimension integration manager](https://dimension.t2bot.io) or used as standalone web app.
Etherpad is an open source collaborative text editor. It can not only be integrated with Element clients ([Element Web](configuring-playbook-client-element-web.md)/Desktop, Android and iOS) as a widget, but also be used as standalone web app.
When enabled together with the Jitsi video-conferencing platform (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
The [Ansible role for Etherpad](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad) is developed and maintained by [the MASH (mother-of-all-self-hosting) project](https://github.com/mother-of-all-self-hosting). For details about configuring Etherpad, you can check them via:
- 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad/blob/main/docs/configuring-etherpad.md) online
- 📁 `roles/galaxy/etherpad/docs/configuring-etherpad.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
## Adjusting DNS records
By default, this playbook installs Etherpad on the `etherpad.` subdomain (`etherpad.example.com`) and requires you to create a CNAME record for `etherpad`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
When enabled together with the Jitsi audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
## Adjusting the playbook configuration
To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
########################################################################
# #
# etherpad #
# #
########################################################################
etherpad_enabled: true
########################################################################
# #
# /etherpad #
# #
########################################################################
# Uncomment and adjust this part if you'd like to enable the admin web UI
# etherpad_admin_username: YOUR_USERNAME_HERE
# etherpad_admin_password: YOUR_PASSWORD_HERE
```
As the most of the necessary settings for the role have been taken care of by the playbook, you can enable Etherpad on your Matrix server with this minimum configuration.
### Adjusting the Etherpad URL
See the role's documentation for details about configuring Etherpad per your preference (such as [the name of the instance](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad/blob/main/docs/configuring-etherpad.md#set-the-name-of-the-instance-optional) and [the default pad text](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad/blob/main/docs/configuring-etherpad.md#set-the-default-text-optional)).
### Create admin user (optional)
You probably might want to enable authentication to disallow anonymous access to your Etherpad.
It is possible to enable HTTP basic authentication by **creating an admin user** with `etherpad_admin_username` and `etherpad_admin_password` variables. The admin user account is also used by plugins for authentication and authorization.
See [this section](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad/blob/main/docs/configuring-etherpad.md#create-admin-user-optional) on the role's documentation for details about how to create the admin user.
### Adjusting the Etherpad URL (optional)
By default, this playbook installs Etherpad on the `etherpad.` subdomain (`etherpad.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `etherpad_hostname` and `etherpad_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:
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
@ -76,7 +33,11 @@ etherpad_hostname: "{{ matrix_server_fqn_matrix }}"
etherpad_path_prefix: /etherpad
```
After changing the domain, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server.
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server.
By default, you will need to create a CNAME record for `etherpad`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
@ -97,20 +58,40 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
`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.
- If you change the Etherpad admin user's password (`etherpad_admin_password` in your `vars.yml` file) subsequently, the admin user's credentials on the homeserver won't be updated automatically. If you'd like to change the admin user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `etherpad_admin_password` to let the admin user know its new password.
## Usage
By default, the Etherpad UI should be available at `https://etherpad.example.com`, while the admin UI (if enabled) should then be available at `https://etherpad.example.com/admin`.
The Etherpad UI should be available at `https://etherpad.example.com`, while the admin UI (if enabled) should then be available at `https://etherpad.example.com/admin`.
If you've [decided on another hostname or path-prefix](#adjusting-the-etherpad-url-optional) (e.g. `https://matrix.example.com/etherpad`), adjust these URLs accordingly before using it.
If you've [decided on another hostname or path-prefix](#adjusting-the-etherpad-url) (e.g. `https://matrix.example.com/etherpad`), adjust these URLs accordingly before usage.
💡 For more information about usage, take a look at [this section](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad/blob/main/docs/configuring-etherpad.md#usage) on the role's documentation.
### Managing / Deleting old pads
### Integrating a Etherpad widget in a room
If you want to manage and remove old unused pads from Etherpad, you will first need to able Admin access as described above.
**Note**: this is how it works in Element Web. It might work quite similar with other clients:
Then from the plugin manager page (`https://etherpad.example.com/admin/plugins`, install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
### How to use Etherpad widgets without an integration manager (like Dimension)
This is how it works in Element Web, it might work quite similar with other clients:
To integrate a standalone Etherpad in a room, create your pad by visiting `https://etherpad.example.com`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` section.
## Troubleshooting
### Set Dimension default to the self-hosted Etherpad (optional)
See [this section](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad/blob/main/docs/configuring-etherpad.md#troubleshooting) on the role's documentation for details.
If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside Etherpad, the Dimension administrator users can configure the default URL template.
The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element Web. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab.
#### Removing the integrated Etherpad chat
If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
Example: `https://etherpad.example.com/p/$roomId_$padName?showChat=false`
## Known issues
If your Etherpad widget fails to load, this might be due to Dimension generating a Pad name so long, the Etherpad app rejects it.
`$roomId_$padName` can end up being longer than 50 characters. You can avoid having this problem by altering the template so it only contains the three word random identifier `$padName`.

9
docs/configuring-playbook-external-postgres.md
View File

@ -1,15 +1,8 @@
<!--
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Using an external PostgreSQL server (optional)
By default, this playbook would set up a PostgreSQL database server on your machine, running in a Docker container. If that's okay, you can skip this document.
**Note**: using **an external Postgres server is currently [not very seamless](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1682#issuecomment-1061461683) when it comes to enabling various other playbook services** — you will need to create a new database/credentials for each service and to point each service to its corresponding database using custom `vars.yml` configuration. **For the best experience with the playbook, stick to using the integrated Postgres server**.
**Note**: using **an external Postgres server is currently [not very seamless](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1682#issuecomment-1061461683) when it comes to enabling various other playbook services** - you will need to create a new database/credentials for each service and to point each service to its corresponding database using custom `vars.yml` configuration. **For the best experience with the playbook, stick to using the integrated Postgres server**.
If you'd like to use an external Postgres server that you manage, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):

16
docs/configuring-playbook-federation.md
View File

@ -1,16 +1,8 @@
<!--
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2022 - 2024 MDAD project contributors
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Controlling Matrix federation (optional)
By default, your server federates with the whole Matrix network. That is, people on your server can communicate with people on any other Matrix server.
**Note**: in the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user ID like `@alice:example.com` instead of `@alice:matrix.example.com` and set up [server delegation](howto-server-delegation.md) / redirection. Without a proper configuration, your server will effectively not be part of the Matrix network. If you find your server is not federated, make sure to [check whether services work](maintenance-and-troubleshooting.md#how-to-check-if-services-work) and your server is properly delegated.
**Note**: in the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user ID like `@alice:example.com` instead of `@alice:matrix.example.com` and set up [server delegation](howto-server-delegation.md) / redirection. Without a proper configuration, your server will effectively not be part of the Matrix network. If you find your server is not federated, make sure to [check whether services work](maintenance-checking-services.md) and your server is properly delegated.
## Federating only with select servers
@ -28,7 +20,7 @@ If you wish to disable federation, you can do that with an empty list (`[]`), or
By default, your server's public rooms directory is not exposed to other servers via federation.
To expose it, add the following configuration to your `vars.yml` file:
If you wish to expose it, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_synapse_allow_public_rooms_over_federation: true
@ -36,7 +28,7 @@ matrix_synapse_allow_public_rooms_over_federation: true
## Disabling federation
To completely disable federation, isolating your server from the rest of the Matrix network, add the following configuration to your `vars.yml` file:
To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_homeserver_federation_enabled: false
@ -60,7 +52,7 @@ matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
Why? This change could be useful for people running small Synapse instances on small severs/VPSes to avoid being impacted by a simple DOS/DDOS when bandwidth, RAM, an CPU resources are limited and if your hosting provider does not provide a DOS/DDOS protection.
To make it possible to proxy the federation through a CDN such as CloudFlare or any other, add the following configuration to your `vars.yml` file:
The following changes in the configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other:
```yaml
matrix_synapse_http_listener_resource_names: ["client","federation"]

310
docs/configuring-playbook-jitsi.md
View File

@ -1,91 +1,269 @@
<!--
SPDX-FileCopyrightText: 2020 - 2024 MDAD project contributors
SPDX-FileCopyrightText: 2020 - 2024 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 Aaron Raimist
SPDX-FileCopyrightText: 2020 Chris van Dijk
SPDX-FileCopyrightText: 2020 Dominik Zajac
SPDX-FileCopyrightText: 2020 Mickaël Cornière
SPDX-FileCopyrightText: 2022 François Darveau
SPDX-FileCopyrightText: 2022 Warren Bailey
SPDX-FileCopyrightText: 2023 Antonis Christofides
SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up the Jitsi video-conferencing platform (optional)
The playbook can install and configure the [Jitsi](https://jitsi.org/) video-conferencing platform for you.
The playbook can install the [Jitsi](https://jitsi.org/) video-conferencing platform and integrate it with Element clients ([Element Web](configuring-playbook-client-element-web.md)/Desktop, Android and iOS).
Jitsi is an open source video-conferencing platform. It can not only be integrated with Element clients ([Element Web](configuring-playbook-client-element-web.md)/Desktop, Android and iOS) as a widget, but also be used as standalone web app.
Jitsi installation is **not enabled by default**, because it's not a core component of Matrix services.
💡 If you're into experimental technology, you may also be interested in trying out [Element Call](configuring-playbook-element-call.md) - a native Matrix video conferencing application.
The [Ansible role for Jitsi](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi) is developed and maintained by [the MASH (mother-of-all-self-hosting) project](https://github.com/mother-of-all-self-hosting). For details about configuring Jitsi, you can check them via:
- 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md) online
- 📁 `roles/galaxy/jitsi/docs/configuring-jitsi.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
The setup done by the playbook is very similar to [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet). You can refer to the documentation there for many of the options here.
## Prerequisites
Before proceeding, make sure to check server's requirements recommended by [the official deployment guide](https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-requirements).
You may need to open the following ports to your server:
You may need to open some ports to your server, if you use another firewall in front of the server. Refer [the role's documentation](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md#prerequisites) to check which ones to be configured.
## Adjusting DNS records
By default, this playbook installs Jitsi on the `jitsi.` subdomain (`jitsi.example.com`) and requires you to create a CNAME record for `jitsi`, which targets `matrix.example.com`.
When setting, replace `example.com` with your own.
- `4443/tcp` - RTP media fallback over TCP
- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`jitsi_jvb_stun_servers`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml)).
## Adjusting the playbook configuration
To enable Jitsi, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
########################################################################
# #
# jitsi #
# #
########################################################################
jitsi_enabled: true
########################################################################
# #
# /jitsi #
# #
########################################################################
```
As the most of the necessary settings for the role have been taken care of by the playbook, you can enable Jitsi on your Matrix server with this minimum configuration.
### Adjusting the Jitsi URL
However, **since Jitsi's performance heavily depends on server resource (bandwidth, RAM, and CPU), it is recommended to review settings and optimize them as necessary before deployment.** You can check [here](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md#example-configurations) for an example set of configurations to set up a Jitsi instance, focusing on performance. If you will host a large conference, you probably might also want to consider to provision additional JVBs ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-videobridge)). See [here](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md#set-up-additional-jvbs-for-more-video-conferences-optional) for details about setting them up with the playbook.
By default, this playbook installs Jitsi on the `jitsi.` subdomain (`jitsi.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
See the role's documentation for details about configuring Jitsi per your preference (such as setting [a custom hostname](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md#set-the-hostname) and [the environment variable for running Jitsi in a LAN](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md#configure-jvb_advertise_ips-for-running-behind-nat-or-on-a-lan-environment-optional)).
By tweaking the `jitsi_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
### Enable authentication and guests mode (optional)
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
By default the Jitsi Meet instance **does not require for anyone to log in, and is open to use without an account**.
```yaml
# Change the default hostname
jitsi_hostname: call.example.com
```
If you would like to control who is allowed to start meetings on your instance, you'd need to enable Jitsi's authentication and optionally guests mode.
## Adjusting DNS records
See [this section](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md#configure-jitsi-authentication-and-guests-mode-optional) on the role's documentation for details about how to configure the authentication and guests mode. The recommended authentication method is `internal` as it also works in federated rooms. If you want to enable authentication with Matrix OpenID making use of [Matrix User Verification Service (UVS)](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook-user-verification-service.md), see [here](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md#authenticate-using-matrix-openid-auth-type-matrix) for details about how to set it up.
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Jitsi domain to the Matrix server.
### Enable Gravatar (optional)
By default, you will need to create a CNAME record for `jitsi`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
In the default Jisti Meet configuration, `gravatar.com` is enabled as an avatar service.
## (Optional) Configure Jitsi authentication and guests mode
Since the Element clients send the URL of configured Matrix avatars to the Jitsi instance, our configuration has disabled the Gravatar service.
By default the Jitsi Meet instance does not require any kind of login and is open to use for anyone without registration.
To enable the Gravatar service nevertheless, add the following configuration to your `vars.yml` file:
If you're fine with such an open Jitsi instance, please skip to [Installing](#installing).
If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow the following steps to enable Jitsi's authentication and optionally guests mode.
Currently, there are three supported authentication modes: 'internal' (default), 'matrix' and 'ldap'.
**Note**: Authentication is not tested via the playbook's self-checks. We therefore recommend that you manually verify if authentication is required by jitsi. For this, try to manually create a conference on jitsi.example.com in your browser.
### Authenticate using Jitsi accounts (Auth-Type 'internal')
The default authentication mechanism is 'internal' auth, which requires jitsi-accounts to be setup and is the recommended setup, as it also works in federated rooms. With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join. If a registered host is not yet present, guests are put on hold in individual waiting rooms.
Add these lines to your `inventory/host_vars/matrix.example.com/vars.yml` configuration:
```yaml
jitsi_enable_auth: true
jitsi_enable_guests: true
jitsi_prosody_auth_internal_accounts:
- username: "jitsi-moderator"
password: "secret-password"
- username: "another-user"
password: "another-password"
```
**Caution**: Accounts added here and subsequently removed will not be automatically removed from the Prosody server until user account cleaning is integrated into the playbook.
**If you get an error** like this: "Error: Account creation/modification not supported.", it's likely that you had previously installed Jitsi without auth/guest support. In such a case, you should look into [Rebuilding your Jitsi installation](#rebuilding-your-jitsi-installation).
### Authenticate using Matrix OpenID (Auth-Type 'matrix')
**Attention: Probably breaks Jitsi in federated rooms and does not allow sharing conference links with guests.**
Using this authentication type require a [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service). By default, this playbook creates and configures a user-verification-service to run locally, see [configuring-user-verification-service](configuring-playbook-user-verification-service.md).
To enable set this configuration at host level:
```yaml
jitsi_enable_auth: true
jitsi_auth_type: matrix
matrix_user_verification_service_enabled: true
```
For more information see also [https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification](https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification).
### Authenticate using LDAP (Auth-Type 'ldap')
An example LDAP configuration could be:
```yaml
jitsi_enable_auth: true
jitsi_auth_type: ldap
jitsi_ldap_url: "ldap://ldap.example.com"
jitsi_ldap_base: "OU=People,DC=example.com"
#jitsi_ldap_binddn: ""
#jitsi_ldap_bindpw: ""
jitsi_ldap_filter: "uid=%u"
jitsi_ldap_auth_method: "bind"
jitsi_ldap_version: "3"
jitsi_ldap_use_tls: true
jitsi_ldap_tls_ciphers: ""
jitsi_ldap_tls_check_peer: true
jitsi_ldap_tls_cacert_file: "/etc/ssl/certs/ca-certificates.crt"
jitsi_ldap_tls_cacert_dir: "/etc/ssl/certs"
jitsi_ldap_start_tls: false
```
For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet#authentication-using-ldap) and the [saslauthd `LDAP_SASLAUTHD`](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD) documentation.
## (Optional) Making your Jitsi server work on a LAN
By default the Jitsi Meet instance does not work with a client in LAN (Local Area Network), even if others are connected from WAN. There are no video and audio. In the case of WAN to WAN everything is ok.
The reason is the Jitsi VideoBridge git to LAN client the IP address of the docker image instead of the host. The [documentation](https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker/#running-behind-nat-or-on-a-lan-environment) of Jitsi in docker suggest to add `JVB_ADVERTISE_IPS` in enviornment variable to make it work.
Here is how to do it in the playbook.
Add these two lines to your `inventory/host_vars/matrix.example.com/vars.yml` configuration:
```yaml
jitsi_jvb_container_extra_arguments:
- '--env "JVB_ADVERTISE_IPS=<Local IP address of the host>"'
```
## (Optional) Fine tune Jitsi
Sample **additional** `inventory/host_vars/matrix.example.com/vars.yml` configuration to save up resources (explained below):
```yaml
jitsi_web_custom_config_extension: |
config.enableLayerSuspension = true;
config.disableAudioLevels = true;
// Limit the number of video feeds forwarded to each client
config.channelLastN = 4;
jitsi_web_config_resolution_width_ideal_and_max: 480
jitsi_web_config_resolution_height_ideal_and_max: 240
```
You may want to **suspend unused video layers** until they are requested again, to save up resources on both server and clients. Read more on this feature [here](https://jitsi.org/blog/new-off-stage-layer-suppression-feature/)
You may wish to **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved.
You may want to **limit the number of video feeds forwarded to each client**, to save up resources on both server and clients. As clients’ bandwidth and CPU may not bear the load, use this setting to avoid lag and crashes. This feature is found by default in other webconference applications such as Office 365 Teams (limit is set to 4). Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/master/doc/last-n.md) and performance evaluation on this [study](https://jitsi.org/wp-content/uploads/2016/12/nossdav2015lastn.pdf).
You may want to **limit the maximum video resolution**, to save up resources on both server and clients.
## (Optional) Specify a Max number of participants on a Jitsi conference
The playbook allows a user to set a max number of participants allowed to join a Jitsi conference. By default there is no limit.
In order to set the max number of participants use the following **additional** configuration:
```yaml
jitsi_prosody_max_participants: 4 # example value
```
## (Optional) Additional JVBs
By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-videobridge)) is deployed on the same host as the Matrix server. To allow more video-conferences to happen at the same time, you may need to provision additional JVB services on other hosts.
There is an ansible playbook that can be run with the following tag: `ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
For this role to work you will need an additional section in the ansible hosts file with the details of the JVB hosts, for example:
```INI
[jitsi_jvb_servers]
<your jvb hosts> ansible_host=<ip address of the jvb host>
```
Each JVB will require a server ID to be set so that it can be uniquely identified and this allows Jitsi to keep track of which conferences are on which JVB. The server ID is set with the variable `jitsi_jvb_server_id` which ends up as the JVB_WS_SERVER_ID environment variables in the JVB docker container. This variable can be set via the host file, a parameter to the ansible command or in the `vars.yaml` for the host which will have the additional JVB. For example:
```yaml
jitsi_jvb_server_id: 'jvb-2'
```
```INI
[jitsi_jvb_servers]
jvb-2.example.com ansible_host=192.168.0.2 jitsi_jvb_server_id=jvb-2
jvb-3.example.com ansible_host=192.168.0.3 jitsi_jvb_server_id=jvb-2
```
Note that the server ID `jvb-1` is reserved for the JVB instance running on the Matrix host and therefore should not be used as the ID of an additional jvb host.
The additional JVB will also need to expose the colibri web socket port and this can be done with the following variable:
```yaml
jitsi_jvb_container_colibri_ws_host_bind_port: 9090
```
The JVB will also need to know where the prosody xmpp server is located, similar to the server ID this can be set in the vars for the JVB by using the variable `jitsi_xmpp_server`. The Jitsi prosody container is deployed on the Matrix server by default so the value can be set to the Matrix domain. For example:
```yaml
jitsi_xmpp_server: "{{ matrix_domain }}"
```
However, it can also be set the ip address of the Matrix server. This can be useful if you wish to use a private ip. For example:
```yaml
jitsi_xmpp_server: "192.168.0.1"
```
For the JVB to be able to contact the XMPP server, the latter must expose the XMPP port (5222). By default, the Matrix server does not expose the port; only the XMPP container exposes it internally inside the host, which means that the first JVB (which runs on the Matrix server) can reach it but the additional JVB cannot. The port is exposed by setting `jitsi_prosody_container_jvb_host_bind_port` like this:
```yaml
jitsi_prosody_container_jvb_host_bind_port: 5222
```
(The default is empty; if it's set then docker forwards the port.)
Applied together this will allow you to provision extra JVB instances which will register themselves with the prosody service and be available for jicofo to route conferences too.
To make Traefik reverse-proxy to these additional JVBs (living on other hosts), **you would need to add the following Traefik configuration extension**:
```yaml
# Traefik proxying for additional JVBs. These can't be configured using Docker
# labels, like the first JVB is, because they run on different hosts, so we add
# the necessary configuration to the file provider.
traefik_provider_configuration_extension_yaml: |
http:
routers:
{% for host in groups['jitsi_jvb_servers'] %}
additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-router:
entryPoints:
- "{{ traefik_entrypoint_primary }}"
rule: "Host(`{{ jitsi_hostname }}`) && PathPrefix(`/colibri-ws/{{ hostvars[host]['jitsi_jvb_server_id'] }}/`)"
service: additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-service
{% if traefik_entrypoint_primary != 'web' %}
tls:
certResolver: "{{ traefik_certResolver_primary }}"
{% endif %}
{% endfor %}
services:
{% for host in groups['jitsi_jvb_servers'] %}
additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-service:
loadBalancer:
servers:
- url: "http://{{ host }}:9090/"
{% endfor %}
```
## (Optional) Enable Gravatar
In the default Jisti Meet configuration, gravatar.com is enabled as an avatar service. This results in third party request leaking data to gravatar. Since Element clients already send the url of configured Matrix avatars to Jitsi, we disabled gravatar.
To enable Gravatar set:
```yaml
jitsi_disable_gravatar: false
```
> [!WARNING]
> This will result in third party request leaking data to the Gravatar Service (`gravatar.com`, unless configured otherwise). Besides metadata, the Matrix user_id and possibly the room ID (via `referrer` header) will be also sent to the third party.
**Beware**: This leaks information to a third party, namely the Gravatar-Service (unless configured otherwise: gravatar.com). Besides metadata, this includes the Matrix user_id and possibly the room identifier (via `referrer` header).
## Installing
@ -106,12 +284,24 @@ You can use the self-hosted Jitsi server in multiple ways:
- **by adding a widget to a room via Element Web** (the one configured by the playbook at `https://element.example.com`). Just start a voice or a video call in a room containing more than 2 members and that would create a Jitsi widget which utilizes your self-hosted Jitsi server.
- **directly (without any Matrix integration)**. Just go to `https://jitsi.example.com`, and you can start a videoconference.
- **by adding a widget to a room via the Dimension integration manager**. You'll have to point the widget to your own Jitsi server manually. See our [Dimension integration manager](./configuring-playbook-dimension.md) documentation page for more details. Naturally, Dimension would need to be installed first (the playbook doesn't install it by default).
Note that you'll need to log in to your Jitsi's account to start a conference if you have configured authentication with `internal` auth.
- **directly (without any Matrix integration)**. Just go to `https://jitsi.example.com`
Check [the official user guide](https://jitsi.github.io/handbook/docs/category/user-guide) for details about how to use Jitsi.
**Note**: Element apps on mobile devices currently [don't support joining meetings on a self-hosted Jitsi server](https://github.com/element-hq/riot-web/blob/601816862f7d84ac47547891bd53effa73d32957/docs/jitsi.md#mobile-app-support).
## Troubleshooting
See [this section](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md#troubleshooting) on the role's documentation for details.
### Rebuilding your Jitsi installation
**If you ever run into any trouble** or **if you change configuration (`jitsi_*` variables) too much**, we urge you to rebuild your Jitsi setup.
We normally don't require such manual intervention for other services, but Jitsi services generate a lot of configuration files on their own.
These files are not all managed by Ansible (at least not yet), so you may sometimes need to delete them all and start fresh.
To rebuild your Jitsi configuration:
- ask Ansible to stop all Jitsi services: `just run-tags stop-group --extra-vars=group=jitsi`
- SSH into the server and do this and remove all Jitsi configuration & data (`rm -rf /matrix/jitsi`)
- ask Ansible to set up Jitsi anew and restart services (`just install-service jitsi`)

47
docs/configuring-playbook-jwt-service.md
View File

@ -1,47 +0,0 @@
<!--
SPDX-FileCopyrightText: 2024 wjbeckett
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up JWT Service (optional)
The playbook can install and configure [LiveKit JWT Service](https://github.com/element-hq/lk-jwt-service) for you.
LK-JWT-Service is currently used for a single reason: generate JWT tokens with a given identity for a given room, so that users can use them to authenticate against LiveKit SFU.
See the project's [documentation](https://github.com/element-hq/lk-jwt-service/) to learn more.
## Decide on a domain and path
By default, JWT Service is configured to be served:
- on the Matrix domain (`matrix.example.com`), configurable via `matrix_livekit_jwt_service_hostname`
- under a `/livekit-jwt-service` path prefix, configurable via `matrix_livekit_jwt_service_path_prefix`
This makes it easy to set it up, **without** having to adjust your DNS records manually.
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records accordingly to point to the correct server.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_livekit_jwt_service_enabled: true
```
## Installing
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
## Usage
Once installed, a new `org.matrix.msc4143.rtc_foci` section is added to the Element Web client to point to your JWT service URL (e.g., `https://matrix.example.com/livekit-jwt-service`).
## Additional Information
Refer to the LiveKit JWT-Service documentation for more details on configuring and using JWT Service.

34
docs/configuring-playbook-ldap-auth.md
View File

@ -1,21 +1,10 @@
<!--
SPDX-FileCopyrightText: 2018 - 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 - 2023 MDAD project contributors
SPDX-FileCopyrightText: 2020 Marcel Partap
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Setting up the LDAP authentication password provider module (optional, advanced)
The playbook can install and configure the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider for you.
See the project's [documentation](https://github.com/matrix-org/matrix-synapse-ldap3/blob/main/README.rst) to learn what it does and why it might be useful to you.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
If you decide that you'd like to let this playbook install it for you, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
```yaml
matrix_synapse_ext_password_provider_ldap_enabled: true
@ -32,29 +21,18 @@ matrix_synapse_ext_password_provider_ldap_bind_password: ""
matrix_synapse_ext_password_provider_ldap_filter: ""
```
### Authenticating only using a password provider
## Authenticating only using a password provider
If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, you can disable it by adding the following configuration to your `vars.yml` file:
If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it:
```yaml
matrix_synapse_password_config_localdb_enabled: false
```
## Installing
## Using ma1sd Identity Server for authentication
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
If you wish to use the ma1sd Identity Server for LDAP authentication instead of [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) consult [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication).
<!-- 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
### Handling user registration
## Handling user registration
If you wish for users to also be able to make new registrations against LDAP, you may **also** wish to [set up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md).

Some files were not shown because too many files have changed in this diff Show More