mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2026-01-27 23:23:16 +03:00
Merge branch 'master' into feature-fluffygate
This commit is contained in:
Alexis Yushin
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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 -->
|
||||
@@ -10,7 +19,7 @@ There are two installation guides available for beginners and advanced users.
|
||||
|
||||
- [Prerequisites](prerequisites.md)
|
||||
|
||||
- [Configuring your DNS settings](configuring-dns.md)
|
||||
- [Configuring DNS settings](configuring-dns.md)
|
||||
|
||||
- [Getting the playbook](getting-the-playbook.md)
|
||||
|
||||
@@ -27,23 +36,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
|
||||
|
||||
@@ -51,8 +60,6 @@ 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)
|
||||
@@ -63,7 +70,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 -->
|
||||
|
||||
@@ -84,3 +91,5 @@ 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)
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -1,5 +1,14 @@
|
||||
<!--
|
||||
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
|
||||
|
||||
# Running this playbook
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Using Ansible for the playbook
|
||||
|
||||
This playbook is meant to be run using [Ansible](https://www.ansible.com/).
|
||||
|
||||
@@ -29,9 +38,12 @@ 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 [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
|
||||
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).
|
||||
|
||||
This ensures that you're using a very recent Ansible version, which is less likely to be incompatible with the playbook.
|
||||
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`
|
||||
|
||||
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).
|
||||
|
||||
@@ -46,50 +58,54 @@ Once you have a working Docker installation on the server, **clone the playbook*
|
||||
|
||||
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: `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: `just install-all --connection=community.docker.nsenter` (or `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 \
|
||||
-v `pwd`:/work \
|
||||
--mount type=bind,src=`pwd`,dst=/work \
|
||||
--entrypoint=/bin/sh \
|
||||
docker.io/devture/ansible:2.18.1-r0-0
|
||||
ghcr.io/devture/ansible:11.1.0-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 `ansible-playbook …` (or `ansible-playbook --connection=community.docker.nsenter …`) commands as per normal now.
|
||||
Finally, you can execute `just` or `ansible-playbook …` (e.g. `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 \
|
||||
-v `pwd`:/work \
|
||||
-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
|
||||
--mount type=bind,src=`pwd`,dst=/work \
|
||||
--mount type=bind,src$HOME/.ssh/id_ed25519,dst=/root/.ssh/id_ed25519,ro \
|
||||
--entrypoint=/bin/sh \
|
||||
docker.io/devture/ansible:2.18.1-r0-0
|
||||
ghcr.io/devture/ansible:11.1.0-r0-0
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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 `ansible-playbook …` commands as per normal now.
|
||||
Finally, you execute `just` or `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 (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`).
|
||||
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`).
|
||||
|
||||
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:
|
||||
|
||||
@@ -97,7 +113,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
|
||||
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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
|
||||
|
||||
@@ -1,6 +1,23 @@
|
||||
# Configuring your DNS settings
|
||||
<!--
|
||||
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
|
||||
|
||||
<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>
|
||||
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>
|
||||
|
||||
To set up Matrix on your domain, you'd need to do some DNS configuration.
|
||||
|
||||
@@ -8,12 +25,15 @@ To set up Matrix on your domain, you'd need to do some DNS configuration.
|
||||
|
||||
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` |
|
||||
| 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 IP address (DNS `A` record or `CNAME` record is fine).
|
||||
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.
|
||||
|
||||
|
||||
191
docs/configuring-ipv6.md
Normal file
191
docs/configuring-ipv6.md
Normal file
@@ -0,0 +1,191 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -26,7 +34,8 @@ 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
|
||||
|
||||
@@ -65,8 +74,6 @@ matrix_alertmanager_receiver_config_matrix_room_mapping:
|
||||
some-room-name: "!qporfwt:{{ matrix_domain }}"
|
||||
```
|
||||
|
||||
See `roles/custom/matrix-alertmanager-receiver/defaults/main.yml` for additional configuration variables.
|
||||
|
||||
### Adjusting the matrix-alertmanager-receiver URL (optional)
|
||||
|
||||
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.
|
||||
@@ -83,22 +90,27 @@ If you've changed the default hostname, you may need to create a CNAME record fo
|
||||
|
||||
When setting, replace `example.com` with your own.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
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
|
||||
|
||||
## 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -122,3 +134,16 @@ 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
|
||||
```
|
||||
|
||||
@@ -1,3 +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.
|
||||
@@ -28,16 +35,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -28,11 +35,8 @@ The management room has to be given an alias, and your bot has to be invited to
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
> [!WARNING]
|
||||
> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
@@ -41,24 +45,28 @@ 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_master_control_room_alias: "MANAGEMENT_ROOM_ALIAS_HERE"
|
||||
matrix_appservice_draupnir_for_all_config_adminRoom: "MANAGEMENT_ROOM_ALIAS_HERE"
|
||||
```
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable.
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
matrix_appservice_draupnir_for_all_extension_yaml: |
|
||||
matrix_appservice_draupnir_for_all_configuration_extension_yaml: |
|
||||
# Your custom YAML configuration goes here.
|
||||
# This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_yaml`).
|
||||
# This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_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_appservice_draupnir_for_all_yaml`.
|
||||
# completely redefining `matrix_appservice_draupnir_for_all_configuration_yaml`.
|
||||
protectAllJoinedRooms: true
|
||||
```
|
||||
|
||||
|
||||
@@ -1,143 +1,19 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Set up a remote server for storing backups
|
||||
|
||||
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).
|
||||
|
||||
### Check the Postgres version
|
||||
|
||||
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.
|
||||
|
||||
Unless you disable the Postgres-backup support, make sure that the Postgres version of your homeserver's database is compatible with borgmatic. You can check the compatible versions [here](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg/blob/main/defaults/main.yml).
|
||||
|
||||
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.
|
||||
|
||||
### Create a new SSH key
|
||||
|
||||
Run the command below on any machine to create a new SSH key:
|
||||
|
||||
```sh
|
||||
ssh-keygen -t ed25519 -N '' -f matrix-borg-backup -C matrix
|
||||
```
|
||||
|
||||
You don't need to place the key in the `.ssh` folder.
|
||||
|
||||
### Add the public key
|
||||
|
||||
Next, add the **public** part of this SSH key (the `matrix-borg-backup.pub` file) to your BorgBackup provider/server.
|
||||
|
||||
If you are using a hosted solution, follow their instructions. If you have your own server, copy the key to it with the command like below:
|
||||
|
||||
```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'
|
||||
```
|
||||
|
||||
The **private** key needs to be added to `backup_borg_ssh_key_private` on your `inventory/host_vars/matrix.example.com/vars.yml` file as below.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable BorgBackup, add the following configuration to your `vars.yml` file (adapt to your needs):
|
||||
|
||||
```yaml
|
||||
backup_borg_enabled: true
|
||||
|
||||
# Set the repository location, where:
|
||||
# - USER is a ssh user on a provider / server
|
||||
# - HOST is a ssh host of a provider / server
|
||||
# - REPO is a BorgBackup repository name
|
||||
backup_borg_location_repositories:
|
||||
- ssh://USER@HOST/./REPO
|
||||
|
||||
# Generate a strong password used for encrypting backups. You can create one with a command like `pwgen -s 64 1`.
|
||||
backup_borg_storage_encryption_passphrase: "PASSPHRASE"
|
||||
|
||||
# Add the content of the **private** part of the SSH key you have created.
|
||||
# Note: the whole key (all of its belonging lines) under the variable needs to be indented with 2 spaces.
|
||||
backup_borg_ssh_key_private: |
|
||||
-----BEGIN OPENSSH PRIVATE KEY-----
|
||||
TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZW
|
||||
xpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRv
|
||||
bG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3
|
||||
RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXgg
|
||||
ZWEgY29tbW9kbyBjb25zZXF1YXQuIA==
|
||||
-----END OPENSSH PRIVATE KEY-----
|
||||
```
|
||||
|
||||
**Note**: `REPO` will be initialized on backup start, for example: `matrix`. See [Remote repositories](https://borgbackup.readthedocs.io/en/stable/usage/general.html#repository-urls) for the syntax.
|
||||
|
||||
### Set backup archive name (optional)
|
||||
|
||||
You can specify the backup archive name format. To set it, add the following configuration to your `vars.yml` file (adapt to your needs):
|
||||
|
||||
```yaml
|
||||
backup_borg_storage_archive_name_format: matrix-{now:%Y-%m-%d-%H%M%S}
|
||||
```
|
||||
|
||||
### Configure retention policy (optional)
|
||||
|
||||
It is also possible to configure a retention strategy. To configure it, add the following configuration to your `vars.yml` file (adapt to your needs):
|
||||
|
||||
```yaml
|
||||
backup_borg_retention_keep_hourly: 0
|
||||
backup_borg_retention_keep_daily: 7
|
||||
backup_borg_retention_keep_weekly: 4
|
||||
backup_borg_retention_keep_monthly: 12
|
||||
backup_borg_retention_keep_yearly: 2
|
||||
```
|
||||
|
||||
### Edit the backup schedule (optional)
|
||||
|
||||
By default the backup will run 4 a.m. every day based on the `backup_borg_schedule` variable. It is defined in the format of systemd timer calendar.
|
||||
|
||||
To edit the schedule, add the following configuration to your `vars.yml` file (adapt to your needs):
|
||||
|
||||
```yaml
|
||||
backup_borg_schedule: "*-*-* 04:00:00"
|
||||
```
|
||||
|
||||
**Note**: the actual job may run with a delay. See `backup_borg_schedule_randomized_delay_sec` [here](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg/blob/f5d5b473d48c6504be10b3d946255ef5c186c2a6/defaults/main.yml#L50) for its default value.
|
||||
|
||||
### Set include and/or exclude directories (optional)
|
||||
|
||||
`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 also want to exclude certain directories or file patterns from the backup using the `backup_borg_location_exclude_patterns` variable.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- [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) 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 `backup_borg_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
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
Sometimes it can be helpful to run the backup as you'd like, avoiding to wait until 4 a.m., like when you test your configuration.
|
||||
|
||||
If you want to run the backup immediately, log in to the server with SSH and run `systemctl start matrix-backup-borg`.
|
||||
|
||||
This will not return until the backup is done, so it can possibly take a long time. Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.
|
||||
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)
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
<!--
|
||||
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">
|
||||
@@ -123,7 +130,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).
|
||||
|
||||
@@ -250,7 +257,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).
|
||||
|
||||
@@ -305,7 +312,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).
|
||||
|
||||
@@ -396,11 +403,13 @@ 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.
|
||||
|
||||
## Debugging
|
||||
## Troubleshooting
|
||||
|
||||
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`
|
||||
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`.
|
||||
|
||||
The default logging level for this service is `info`, but you can increase it to `debug` (or even `trace`) with the following additional configuration:
|
||||
### 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:
|
||||
|
||||
```yaml
|
||||
# Adjust the bot's own logging level.
|
||||
|
||||
@@ -1,9 +1,19 @@
|
||||
<!--
|
||||
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`.
|
||||
@@ -54,6 +64,14 @@ After changing the domain, **you may need to adjust your DNS** records to point
|
||||
|
||||
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:
|
||||
@@ -95,4 +113,14 @@ 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.
|
||||
|
||||
You can also refer to the upstream [documentation](https://github.com/etkecc/buscarron).
|
||||
## 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
|
||||
```
|
||||
|
||||
@@ -1,11 +1,21 @@
|
||||
<!--
|
||||
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
|
||||
@@ -28,7 +38,8 @@ 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).
|
||||
|
||||
@@ -51,6 +62,14 @@ 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:
|
||||
@@ -74,4 +93,6 @@ 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.
|
||||
|
||||
You can also refer to the upstream [documentation](https://github.com/matrixgpt/matrix-chatgpt-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`.
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -6,48 +15,55 @@ See the project's [documentation](https://the-draupnir-project.github.io/draupni
|
||||
|
||||
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 skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
|
||||
If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### 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.
|
||||
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.
|
||||
|
||||
If you make the management room encrypted (E2EE), then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
|
||||
> [!WARNING]
|
||||
> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
|
||||
|
||||
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`.
|
||||
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)).
|
||||
|
||||
Finally invite the `@bot.draupnir:example.com` account that the playbook will create for you to the management room. Please note that clients can issue a warning that your attempting to invite a user that doesnt have a profile and might not exist. This warning is expected as your inviting the bot before its user account exists.
|
||||
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.
|
||||
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 information on why you might or might not care about encryption support for protected rooms.
|
||||
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.
|
||||
|
||||
**Note**: Draupnir does not support running with Pantalaimon as it would break all workflows that involve answering prompts with reactions.
|
||||
### 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.
|
||||
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:
|
||||
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_enable_experimental_rust_crypto: true
|
||||
# Enables the native E2EE support
|
||||
matrix_bot_draupnir_config_experimentalRustCrypto: true
|
||||
|
||||
# Access Token the bot uses to login.
|
||||
# Access token which the bot will use for logging in.
|
||||
# Comment out `matrix_bot_draupnir_login_native` when using this option.
|
||||
matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE"
|
||||
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`.
|
||||
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
|
||||
@@ -57,47 +73,67 @@ matrix_bot_draupnir_enabled: true
|
||||
# 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_access_token` to login you can comment out this line.
|
||||
# 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_enable_experimental_rust_crypto: true` or `matrix_bot_draupnir_access_token` to login.
|
||||
# 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_management_room: "MANAGEMENT_ROOM_ID_HERE"
|
||||
matrix_bot_draupnir_config_managementRoom: "MANAGEMENT_ROOM_ID_HERE"
|
||||
```
|
||||
|
||||
Before Proceeding run the playbook with the following command to make sure the Draupnir user has been created.
|
||||
### 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.
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created
|
||||
```
|
||||
|
||||
### Make sure the account is free from rate limiting
|
||||
**Note**: the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a heavily recomended step. If you do not configure it, Draupnir performance will be degraded.**
|
||||
Then, invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier.
|
||||
|
||||
### Make sure the account is free from rate limiting (optional, recommended)
|
||||
|
||||
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.**
|
||||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
|
||||
```
|
||||
|
||||
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).
|
||||
#### Obtain an access token for admin account
|
||||
|
||||
**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).
|
||||
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).
|
||||
|
||||
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:
|
||||
> [!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
|
||||
|
||||
```sh
|
||||
curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit
|
||||
curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit
|
||||
```
|
||||
|
||||
### Obtain an access token
|
||||
|
||||
Manual access to Synapse's Admin API requires an access token. 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.
|
||||
**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.
|
||||
|
||||
### Abuse Reports
|
||||
|
||||
@@ -106,18 +142,22 @@ Draupnir can 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:
|
||||
|
||||
```yaml
|
||||
matrix_bot_draupnir_abuse_reporting_enabled: true
|
||||
matrix_bot_draupnir_config_web_abuseReporting: 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.
|
||||
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
|
||||
|
||||
You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable.
|
||||
There are some additional things you may wish to configure about the bot.
|
||||
|
||||
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:
|
||||
|
||||
@@ -137,7 +177,7 @@ matrix_bot_draupnir_configuration_extension_yaml: |
|
||||
|
||||
Replace your `matrix_bot_mjolnir` config with `matrix_bot_draupnir` config. Also disable Mjolnir if you're doing migration.
|
||||
|
||||
Note that Pantalaimon is unsupported by Draupnir so it is recommended to consult the instructions to enable [the native E2EE support](#native-e2ee-support).
|
||||
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.
|
||||
|
||||
@@ -158,6 +198,8 @@ 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 bot password (`matrix_bot_draupnir_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_draupnir_password` to let the bot know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
You can refer to the upstream [documentation](https://the-draupnir-project.github.io/draupnir-documentation/) for additional ways to use and configure Draupnir and for a more detailed usage guide.
|
||||
|
||||
@@ -1,6 +1,16 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -26,7 +36,8 @@ 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.
|
||||
> [!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
|
||||
|
||||
@@ -219,22 +230,27 @@ After changing the domain, **you may need to adjust your DNS** records to point
|
||||
|
||||
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:
|
||||
|
||||
<!-- 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
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -245,3 +261,7 @@ 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`.
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -45,6 +53,14 @@ If you've changed the default hostname, you may need to create a CNAME record fo
|
||||
|
||||
When setting, replace `example.com` with your own.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
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
|
||||
|
||||
## 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:
|
||||
@@ -73,3 +89,15 @@ 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'
|
||||
```
|
||||
|
||||
@@ -1,3 +1,15 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -29,6 +41,15 @@ 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:
|
||||
@@ -63,3 +84,16 @@ 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
|
||||
```
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -23,6 +31,15 @@ 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:
|
||||
@@ -53,3 +70,18 @@ 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
|
||||
```
|
||||
|
||||
@@ -1,3 +1,14 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -47,6 +58,15 @@ If you've changed the default hostname, you may need to create a CNAME record fo
|
||||
|
||||
When setting, replace `example.com` with your own.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
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.
|
||||
@@ -100,4 +120,18 @@ 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.
|
||||
> [!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
|
||||
```
|
||||
|
||||
@@ -1,3 +1,14 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -24,7 +35,8 @@ 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
|
||||
|
||||
@@ -32,37 +44,57 @@ 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:
|
||||
|
||||
```yaml
|
||||
matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
|
||||
```
|
||||
|
||||
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).
|
||||
#### Obtain an access token for admin account
|
||||
|
||||
**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).
|
||||
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.
|
||||
|
||||
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:
|
||||
> [!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
|
||||
|
||||
```sh
|
||||
curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit
|
||||
curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit
|
||||
```
|
||||
|
||||
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.
|
||||
**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.
|
||||
|
||||
### 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.
|
||||
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.
|
||||
|
||||
If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)).
|
||||
> [!WARNING]
|
||||
> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
|
||||
|
||||
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`.
|
||||
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`.
|
||||
|
||||
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`.
|
||||
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.
|
||||
|
||||
```yaml
|
||||
# Enable Mjolnir
|
||||
@@ -131,7 +163,11 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
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.
|
||||
There are some additional things you may wish to configure about the bot.
|
||||
|
||||
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:
|
||||
|
||||
@@ -153,13 +189,11 @@ 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,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,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.
|
||||
@@ -169,3 +203,17 @@ 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"
|
||||
```
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -28,22 +37,28 @@ 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:
|
||||
|
||||
<!-- 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
|
||||
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`
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
`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.
|
||||
|
||||
- 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.
|
||||
|
||||
## Self-Service Bridging (Manual)
|
||||
|
||||
@@ -99,3 +114,18 @@ 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
|
||||
```
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -60,23 +69,48 @@ 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:
|
||||
|
||||
<!-- 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
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
To use the bridge, you need to start a chat with `@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"
|
||||
```
|
||||
|
||||
@@ -1,10 +1,20 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
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**.
|
||||
> [!WARNING]
|
||||
> There have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
|
||||
|
||||
## Prerequisite (optional)
|
||||
|
||||
@@ -39,19 +49,27 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
To use the bridge, you need to start a chat with `@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.
|
||||
|
||||
## 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-kakaotalk`.
|
||||
|
||||
### 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_appservice_kakaotalk_logging_level: DEBUG
|
||||
```
|
||||
|
||||
@@ -1,3 +1,14 @@
|
||||
<!--
|
||||
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**:
|
||||
@@ -61,7 +72,21 @@ matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
|
||||
# matrix_appservice_slack_team_sync_enabled: true
|
||||
```
|
||||
|
||||
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
|
||||
### 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"
|
||||
```
|
||||
|
||||
## Installing
|
||||
|
||||
@@ -69,16 +94,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -86,7 +107,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:
|
||||
@@ -121,7 +142,7 @@ Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
As always, check the logs: `journalctl -fu matrix-appservice-slack`
|
||||
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`.
|
||||
|
||||
### Linking: "Room is now pending-name"
|
||||
|
||||
@@ -129,8 +150,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 you logs, if they say something like
|
||||
Check the logs, and if you find the message like below, unlink your room, reinvite the bot and re-link it again.
|
||||
|
||||
`WARN SlackEventHandler Ignoring message from unrecognised Slack channel ID : %s (%s) <the channel ID> <some other ID>`
|
||||
|
||||
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.
|
||||
This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -14,9 +25,6 @@ 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.
|
||||
#
|
||||
@@ -24,22 +32,27 @@ 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:
|
||||
|
||||
<!-- 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
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -85,3 +98,16 @@ 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'
|
||||
```
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
<!--
|
||||
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 - 2025 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.
|
||||
@@ -36,16 +46,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -55,6 +61,16 @@ You then need to send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to e
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2022 Vladimir Panteleev
|
||||
SPDX-FileCopyrightText: 2024 - 2025 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.
|
||||
@@ -36,17 +43,26 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
To use the bridge, you need to start a chat with `@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'
|
||||
```
|
||||
|
||||
@@ -1,8 +1,16 @@
|
||||
<!--
|
||||
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).
|
||||
|
||||
@@ -43,22 +51,26 @@ If you've changed the default hostname, you may need to create a CNAME record fo
|
||||
|
||||
When setting, replace `example.com` with your own.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the bridge.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-bridge-heisenbridge/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -69,3 +81,7 @@ 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`.
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -38,7 +48,12 @@ Take special note of the `matrix_hookshot_*_enabled` variables. Services that ne
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
You can configure additional options by adding the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables.
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
@@ -91,9 +106,8 @@ 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.
|
||||
|
||||
@@ -120,21 +134,57 @@ 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`.
|
||||
|
||||
### 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.
|
||||
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`.
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -30,26 +38,33 @@ 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:
|
||||
|
||||
<!-- 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
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
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`.
|
||||
|
||||
74
docs/configuring-playbook-bridge-mautrix-bluesky.md
Normal file
74
docs/configuring-playbook-bridge-mautrix-bluesky.md
Normal file
@@ -0,0 +1,74 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2025 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2025 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2025 Suguru Hirahara
|
||||
|
||||
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 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'
|
||||
```
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -15,7 +24,7 @@ To enable the bridge, add the following configuration to your `inventory/host_va
|
||||
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).
|
||||
**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.
|
||||
|
||||
@@ -144,16 +153,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
|
||||
@@ -1,3 +1,15 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -45,16 +57,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -71,3 +79,16 @@ If you'd like to bridge guilds, send `guilds status` to see the list of guilds,
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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-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 and re-run the playbook:
|
||||
|
||||
```yaml
|
||||
# Valid values: fatal, error, warn, info, debug, trace
|
||||
matrix_mautrix_discord_logging_level: 'debug'
|
||||
```
|
||||
|
||||
@@ -1,8 +1,20 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -38,16 +50,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -59,6 +67,16 @@ If you run into trouble, check the [Troubleshooting](#troubleshooting) section b
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -35,16 +43,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -53,3 +57,16 @@ To use the bridge, you need to start a chat with `@gmessagesbot:example.com` (wh
|
||||
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/gmessages/authentication.html).
|
||||
|
||||
After logging in, the bridge will create portal rooms for recent 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-gmessages`.
|
||||
|
||||
### 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_gmessages_logging_level: 'debug'
|
||||
```
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -37,16 +46,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -54,4 +59,16 @@ To use the bridge, you need to start a chat with `@googlechatbot:example.com` (w
|
||||
|
||||
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/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.
|
||||
After logging in, the bridge will create portal rooms for 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-googlechat`.
|
||||
|
||||
### 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_googlechat_logging_level: DEBUG
|
||||
```
|
||||
|
||||
@@ -1,58 +1,27 @@
|
||||
# Setting up Mautrix Hangouts bridging (optional, deprecated)
|
||||
<!--
|
||||
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
|
||||
|
||||
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
|
||||
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.
|
||||
|
||||
## Prerequisite (optional)
|
||||
You may wish to use the [Google Chat bridge](https://github.com/mautrix/googlechat) instead.
|
||||
|
||||
### Enable Shared Secret Auth
|
||||
## 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:
|
||||
|
||||
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 [Google Hangouts](https://hangouts.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_hangouts_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.
|
||||
|
||||
## 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
|
||||
systemctl disable --now matrix-mautrix-hangouts.service
|
||||
|
||||
rm -rf /matrix/mautrix-hangouts
|
||||
|
||||
/matrix/postgres/bin/cli-non-interactive 'DROP DATABASE matrix_mautrix_hangouts;'
|
||||
```
|
||||
|
||||
**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 `@hangoutsbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
|
||||
You then need to 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.
|
||||
|
||||
@@ -1,8 +1,17 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -28,19 +37,27 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
To use the bridge, you need to start a chat with `@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.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -51,16 +58,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -69,3 +72,16 @@ To use the bridge, you need to start a chat with `@instagrambot:example.com` (wh
|
||||
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html).
|
||||
|
||||
After logging in, the bridge will sync recent 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-meta-instagram`.
|
||||
|
||||
### 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
|
||||
# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
|
||||
matrix_mautrix_meta_instagram_logging_min_level: debug
|
||||
```
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -45,8 +53,8 @@ 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).
|
||||
|
||||
@@ -64,16 +72,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -84,3 +88,16 @@ You can then follow instructions on the bridge's [official documentation on Auth
|
||||
After logging in, the bridge will sync recent chats.
|
||||
|
||||
**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.
|
||||
|
||||
## 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-meta-messenger`.
|
||||
|
||||
### 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
|
||||
# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
|
||||
matrix_mautrix_meta_messenger_logging_min_level: debug
|
||||
```
|
||||
|
||||
@@ -1,3 +1,19 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -40,16 +56,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -60,3 +72,16 @@ You can then follow instructions on the bridge's [official documentation on Auth
|
||||
After logging in, the bridge will bridge chats as you receive messages.
|
||||
|
||||
**Note**: Signal does not support any kind of message history (even on official apps), so the bridge won't backfill any 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-signal`.
|
||||
|
||||
### 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_signal_logging_level: 'debug'
|
||||
```
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -45,16 +54,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -63,3 +68,16 @@ To use the bridge, you need to start a chat with `@slackbot:example.com` (where
|
||||
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/slack/authentication.html).
|
||||
|
||||
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.
|
||||
|
||||
## 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-slack`.
|
||||
|
||||
### 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_slack_logging_level: 'debug'
|
||||
```
|
||||
|
||||
@@ -1,3 +1,16 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -75,16 +88,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -93,3 +102,15 @@ To use the bridge, you need to start a chat with `@telegrambot:example.com` (whe
|
||||
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:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_telegram_logging_level: DEBUG
|
||||
```
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -37,16 +46,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -54,4 +59,17 @@ To use the bridge, you need to start a chat with `@twitterbot:example.com` (wher
|
||||
|
||||
You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/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.
|
||||
After logging in, the bridge will create portal rooms for 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-twitter`.
|
||||
|
||||
### 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_twitter_logging_level: 'debug'
|
||||
```
|
||||
|
||||
@@ -1,3 +1,16 @@
|
||||
<!--
|
||||
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 - 2025 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>
|
||||
@@ -36,16 +49,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
@@ -56,3 +65,16 @@ You can then follow instructions on the bridge's [official documentation on Auth
|
||||
Approximately in a minute after logging in, the bridge will create portal rooms for recent chats.
|
||||
|
||||
**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.
|
||||
|
||||
## 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-whatsapp`.
|
||||
|
||||
### 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_whatsapp_logging_level: 'debug'
|
||||
```
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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>
|
||||
@@ -28,12 +36,6 @@ 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.
|
||||
|
||||
### 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.
|
||||
|
||||
### Adjusting the wsproxy URL (optional)
|
||||
|
||||
By tweaking the `matrix_mautrix_wsproxy_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
|
||||
@@ -47,23 +49,29 @@ 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.
|
||||
|
||||
### 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.
|
||||
|
||||
## 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
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`.
|
||||
|
||||
@@ -1,6 +1,15 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2020 Hugues Morisset
|
||||
SPDX-FileCopyrightText: 2022 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2024 - 2025 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.
|
||||
|
||||
@@ -22,16 +31,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2021 Cody Neiman
|
||||
SPDX-FileCopyrightText: 2021 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2022 Cody Wyatt Neiman
|
||||
SPDX-FileCopyrightText: 2024 - 2025 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.
|
||||
@@ -18,16 +27,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2021 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2024 - 2025 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.
|
||||
@@ -18,16 +25,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
|
||||
@@ -1,5 +1,13 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -1,3 +1,14 @@
|
||||
<!--
|
||||
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 - 2025 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.
|
||||
@@ -27,16 +38,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2020 - 2021 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2020 Hugues Morisset
|
||||
SPDX-FileCopyrightText: 2020 Panagiotis Vasilopoulos
|
||||
SPDX-FileCopyrightText: 2024 - 2025 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.
|
||||
@@ -18,16 +27,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2020 Tulir Asokan
|
||||
SPDX-FileCopyrightText: 2021 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2024 - 2025 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.
|
||||
@@ -29,16 +37,12 @@ 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
|
||||
@@ -1,6 +1,13 @@
|
||||
# Setting up Postmoogle email bridging (optional)
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2022 Nikita Chernyi
|
||||
SPDX-FileCopyrightText: 2023 Luke D Iremadze
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
**Note**: email bridging can also happen via the [email2matrix](configuring-playbook-email2matrix.md) bridge supported by the playbook.
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up Postmoogle email bridging (optional)
|
||||
|
||||
The playbook can install and configure [Postmoogle](https://github.com/etkecc/postmoogle) for you.
|
||||
|
||||
@@ -55,6 +62,14 @@ matrix_postmoogle_password: PASSWORD_FOR_THE_BOT
|
||||
# matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
|
||||
```
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
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
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
@@ -84,11 +99,13 @@ 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).
|
||||
|
||||
### Debug/Logs
|
||||
## Troubleshooting
|
||||
|
||||
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`
|
||||
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`.
|
||||
|
||||
The default logging level for this bridge is `INFO`, but you can increase it to `DEBUG` with the following additional configuration:
|
||||
### 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_postmoogle_loglevel: 'DEBUG'
|
||||
|
||||
@@ -1,9 +1,19 @@
|
||||
<!--
|
||||
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/).
|
||||
|
||||
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:
|
||||
@@ -12,19 +22,26 @@ 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,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,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.
|
||||
@@ -34,3 +51,16 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
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).
|
||||
|
||||
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'
|
||||
```
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
|
||||
SPDX-FileCopyrightText: 2023 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2024 - 2025 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.
|
||||
@@ -8,9 +17,9 @@ 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).
|
||||
|
||||
@@ -25,23 +34,21 @@ If you wish to adjust it, see the section [below](#adjusting-the-cactus-comments
|
||||
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)
|
||||
@@ -61,30 +68,36 @@ If you've changed the default hostname, you may need to create a CNAME record fo
|
||||
|
||||
When setting, replace `example.com` with your own.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
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
|
||||
|
||||
## 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,ensure-matrix-users-created,start
|
||||
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`
|
||||
|
||||
- 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.
|
||||
`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
|
||||
|
||||
Upon starting Cactus Comments, a `bot.cactusbot` user account is created automatically.
|
||||
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).
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Now you are good to go and can embed the comment section on your website!
|
||||
|
||||
@@ -98,7 +111,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 `<YourSiteName>` 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 `YOUR_SITE_NAME_HERE` with the one that has been registered above:
|
||||
|
||||
```html
|
||||
<script>
|
||||
@@ -106,7 +119,7 @@ initComments({
|
||||
node: document.getElementById("comment-section"),
|
||||
defaultHomeserverUrl: "https://matrix.example.com:8448",
|
||||
serverName: "example.com",
|
||||
siteName: "<YourSiteName>",
|
||||
siteName: "YOUR_SITE_NAME_HERE",
|
||||
commentSectionId: "1"
|
||||
})
|
||||
</script>
|
||||
@@ -124,3 +137,18 @@ 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
|
||||
```
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -40,6 +48,15 @@ After changing the domain, **you may need to adjust your DNS** records to point
|
||||
|
||||
**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.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
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
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
@@ -52,3 +69,7 @@ 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`.
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -17,13 +27,30 @@ When setting, replace `example.com` with your own.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
### Set the country code for phone number inputs
|
||||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
matrix_client_element_default_country_code: "FR"
|
||||
```
|
||||
|
||||
### 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.
|
||||
#### Change the default theme
|
||||
|
||||
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`
|
||||
|
||||
To pull the themes from the `element-themes` project and use them for your Element Web instance, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
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
|
||||
@@ -112,3 +139,7 @@ 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
Normal file
66
docs/configuring-playbook-client-fluffychat-web.md
Normal file
@@ -0,0 +1,66 @@
|
||||
<!--
|
||||
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`.
|
||||
@@ -1,3 +1,12 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -37,6 +46,15 @@ After changing the domain, **you may need to adjust your DNS** records to point
|
||||
|
||||
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:
|
||||
@@ -49,3 +67,7 @@ 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`.
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -22,13 +30,30 @@ 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
|
||||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
matrix_client_schildichat_default_country_code: "FR"
|
||||
```
|
||||
|
||||
### 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.
|
||||
#### Change the default theme
|
||||
|
||||
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`
|
||||
|
||||
To pull the themes from the `element-themes` project and use them for your SchildiChat Web instance, add the following configuration to your `vars.yml` file:
|
||||
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
|
||||
@@ -109,3 +134,7 @@ 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`.
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -6,13 +13,11 @@ See the project's [documentation](https://docs.conduit.rs/) to learn what it doe
|
||||
|
||||
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**: The playbook also supports installing a (currently) faster-moving Conduit fork called [Conduwuit](./configuring-playbook-conduwuit.md).
|
||||
💡 **Note**: The playbook also supports installing a (currently) faster-moving Conduit fork called [conduwuit](./configuring-playbook-conduwuit.md).
|
||||
|
||||
⚠️ **Warnings**:
|
||||
|
||||
- **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
|
||||
> [!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
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
@@ -42,7 +47,7 @@ matrix_conduit_template_conduit_config: "{{ playbook_dir }}/inventory/host_vars/
|
||||
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)
|
||||
@@ -75,3 +80,7 @@ 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`.
|
||||
|
||||
@@ -1,22 +1,27 @@
|
||||
# Configuring Conduwuit (optional)
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2025 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2025 Suguru Hirahara
|
||||
|
||||
The playbook can install and configure the [Conduwuit](https://conduwuit.puppyirl.gay/) Matrix server for you.
|
||||
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).
|
||||
💡 **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).
|
||||
|
||||
⚠️ **Warnings**:
|
||||
|
||||
- **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
|
||||
> [!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:
|
||||
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
|
||||
@@ -51,7 +56,7 @@ matrix_conduwuit_environment_variables_extension: |
|
||||
|
||||
## 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.
|
||||
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.
|
||||
|
||||
@@ -64,9 +69,9 @@ The **first user account that you create will be marked as an admin** and **will
|
||||
|
||||
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.
|
||||
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.
|
||||
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`.
|
||||
@@ -93,3 +98,7 @@ Then, send its content to the existing admin room:
|
||||
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`.
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -6,11 +14,9 @@ See the project's [documentation](https://element-hq.github.io/dendrite/) to lea
|
||||
|
||||
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.
|
||||
|
||||
⚠️ **Warnings**:
|
||||
|
||||
- **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
|
||||
> [!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
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
@@ -62,3 +68,18 @@ 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
|
||||
```
|
||||
|
||||
@@ -1,3 +1,18 @@
|
||||
<!--
|
||||
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**:
|
||||
@@ -34,7 +49,8 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=dimension p
|
||||
|
||||
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.
|
||||
> [!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
|
||||
|
||||
@@ -85,6 +101,17 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
|
||||
|
||||
**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.
|
||||
|
||||
### 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).
|
||||
|
||||
## 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:
|
||||
@@ -100,16 +127,18 @@ 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.
|
||||
|
||||
- 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.
|
||||
## Usage
|
||||
|
||||
## Jitsi domain
|
||||
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.
|
||||
|
||||
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.
|
||||
### Set up a Jitsi widget
|
||||
|
||||
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* → *Settings* → *Widgets* → *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
|
||||
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.
|
||||
|
||||
## Additional features
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).
|
||||
## 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`.
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -6,7 +14,7 @@ Most cloud providers / ISPs will charge you extra for a static IP address. If yo
|
||||
|
||||
## Prerequisite
|
||||
|
||||
You'll need to get a username and password from your DNS provider. Please consult with the provider about how to retrieve them.
|
||||
You'll need to authenticate with your DNS provider somehow, in most cases this is simply a username and password but can differ from provider to provider. Please consult with your providers documentation and the upstream [ddclient documentation](https://github.com/ddclient/ddclient/blob/main/ddclient.conf.in) to determine what you'll need to provide to authenticate.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
@@ -23,6 +31,16 @@ matrix_dynamic_dns_domain_configurations:
|
||||
domain: "{{ matrix_domain }}"
|
||||
```
|
||||
|
||||
Keep in mind that certain providers may require a different configuration of the `matrix_dynamic_dns_domain_configurations` variable, for provider specific examples see the [upstream documentation](https://github.com/ddclient/ddclient/blob/main/ddclient.conf.in).
|
||||
|
||||
### 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:
|
||||
@@ -41,3 +59,8 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
Additional resources:
|
||||
|
||||
- https://matrix.org/docs/guides/free-small-matrix-server
|
||||
- https://github.com/linuxserver/docker-ddclient
|
||||
|
||||
## 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`. However, due to an [upstream issue](https://github.com/linuxserver/docker-ddclient/issues/54#issuecomment-1153143132) the logging output is not always complete. For advanced debugging purposes running the `ddclient` tool outside of the container is useful via the following: `ddclient -file ./ddclient.conf -daemon=0 -debug -verbose -noquiet`.
|
||||
|
||||
122
docs/configuring-playbook-element-call.md
Normal file
122
docs/configuring-playbook-element-call.md
Normal file
@@ -0,0 +1,122 @@
|
||||
<!--
|
||||
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) and its supporting components that are part of the [Matrix RTC stack](configuring-playbook-matrix-rtc.md).
|
||||
|
||||
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)
|
||||
- The [Matrix RTC (Real-Time Communication) stack](configuring-playbook-matrix-rtc.md) (automatically done 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).
|
||||
- (Optional) Guest accounts being enabled for your Matrix server, if you'd like guests to be able to use Element Call. See [Allowing guests to use Element Call](#allowing-guests-to-use-element-call-optional)
|
||||
|
||||
> [!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 between Element Call vs just the Matrix RTC stack
|
||||
|
||||
All clients that can currently use Element Call (Element Web and Element X on mobile) already embed the Element Call frontend within them.
|
||||
These **clients will use their own embedded Element Call frontend**, so **self-hosting the Element Call frontend by the playbook is largely unnecessary**.
|
||||
|
||||
💡 A reason you may wish to continue installing the Element Call frontend (despite Matrix clients not making use of it), is if you need to use it standalone - directly via a browser (without a Matrix client). Note that unless you [allow guest accounts to use Element Call](#allowing-guests-to-use-element-call-optional), you will still need a Matrix user account **on the same homeserver** to be able to use Element Call.
|
||||
|
||||
The playbook makes a distiction between enabling Element Call (`matrix_element_call_enabled`) and enabling the Matrix RTC Stack (`matrix_rtc_enabled`). Enabling Element Call automatically enables the Matrix RTC stack. Because installing the Element Call frontend is now unnecessary, **we recommend only installing the Matrix RTC stack, without the Element Call frontend**.
|
||||
|
||||
| Description / Variable | Element Call frontend | [LiveKit Server](configuring-playbook-livekit-server.md) | [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) |
|
||||
|------------------------|-----------------------|----------------|---------------------|
|
||||
| Description | Static website that provides the Element Call UI (but often embedded by clients) | Scalable, multi-user conferencing solution based on WebRTC | A helper component that allows Element Call to integrate with LiveKit Server |
|
||||
| Required for Element Call to function | No | Yes | Yes |
|
||||
| `matrix_element_call_enabled` | ✅ Installed | ✅ Installed | ✅ Installed |
|
||||
| `matrix_rtc_enabled` | ❌ Not Installed, but usually unnecessary | ✅ Installed | ✅ Installed |
|
||||
|
||||
All documentation below assumes that you've decided to install Element Call and not just the Matrix RTC stack.
|
||||
|
||||
## Decide on a domain and path
|
||||
|
||||
By default, the Element Call frontend 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
|
||||
# Enable the Element Call frontend UI to allow standalone use of Element Call.
|
||||
# Enabling this also auto-enables the Matrix RTC stack.
|
||||
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).
|
||||
|
||||
### Allowing guests to use Element Call (optional)
|
||||
|
||||
By default, Element Call can only be used by people having accounts on your Matrix server.
|
||||
|
||||
If you'd like guests to be able to use Element Call as well, you need to enable guest accounts support for your homeserver.
|
||||
|
||||
> [!WARNING]
|
||||
> Enabling guest accounts means that your homeserver's user database may get polluted with guest account signups (potentially made by bots).
|
||||
> Guest accounts should be limited in what (damage) they can do to your server and the rest of the Matrix ecosystem, but it's better to not enable them unless necessary.
|
||||
|
||||
For [Synapse](configuring-playbook-synapse.md) (the default homeserver implementation), the configuration is like this:
|
||||
|
||||
```yml
|
||||
matrix_synapse_allow_guest_access: true
|
||||
```
|
||||
|
||||
For [Dendrite](configuring-playbook-dendrite.md), the configuration is like this:
|
||||
|
||||
```yml
|
||||
matrix_dendrite_guests_disabled: false
|
||||
```
|
||||
|
||||
## 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).
|
||||
@@ -1,53 +1,71 @@
|
||||
<!--
|
||||
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/) email server through which all Matrix services send emails.
|
||||
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.
|
||||
|
||||
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.)
|
||||
**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.
|
||||
|
||||
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.
|
||||
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)
|
||||
|
||||
## Firewall settings
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
## Relaying email through another SMTP server
|
||||
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.
|
||||
|
||||
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):
|
||||
## 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:
|
||||
|
||||
```yaml
|
||||
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"
|
||||
exim_relay_enabled: false
|
||||
```
|
||||
|
||||
**Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.
|
||||
Note that disabling exim-relay will stop email-notifications and other similar functions from working.
|
||||
|
||||
### Configuations for sending emails using Sendgrid
|
||||
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.
|
||||
|
||||
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`.
|
||||
## Installing
|
||||
|
||||
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`.
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
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>"
|
||||
<!-- 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
|
||||
|
||||
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`.
|
||||
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.
|
||||
|
||||
@@ -1,117 +1,26 @@
|
||||
# Setting up Email2Matrix (optional)
|
||||
<!--
|
||||
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
|
||||
|
||||
**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.
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
The playbook can install and configure [email2matrix](https://github.com/devture/email2matrix) for you.
|
||||
# Setting up Email2Matrix (optional, removed)
|
||||
|
||||
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.
|
||||
🪦 The playbook used to be able to install and configure [Email2Matrix](https://github.com/devture/email2matrix), but no longer includes this component.
|
||||
|
||||
## Preparation
|
||||
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).
|
||||
|
||||
### Port availability
|
||||
|
||||
Ensure that port 25 is available on your Matrix server and open in your firewall.
|
||||
## Uninstalling Email2Matrix manually
|
||||
|
||||
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).
|
||||
|
||||
### Register a dedicated Matrix user (optional, recommended)
|
||||
|
||||
We recommend that you create a dedicated Matrix user for Email2Matrix.
|
||||
|
||||
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):
|
||||
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:
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=email2matrix password=PASSWORD_FOR_THE_USER admin=no' --tags=register-user
|
||||
systemctl disable --now matrix-email2matrix.service
|
||||
|
||||
rm -rf /matrix/email2matrix
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### Obtain an access token
|
||||
|
||||
Email2Matrix requires an access token for the sender user to be able to send messages to the room. 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.
|
||||
|
||||
### Join to rooms as the sender user manually
|
||||
|
||||
ℹ️ **Email2Matrix does not accept room invitations automatically**. To deliver messages to rooms, the sender user must be joined to all rooms manually.
|
||||
|
||||
For each new room you would like the user to deliver messages to, invite the user to the room.
|
||||
|
||||
Then, log in as the sender user using any Matrix client of your choosing, accept the room invitation from the user's account.
|
||||
|
||||
Make sure that 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, then log out.
|
||||
|
||||
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.
|
||||
|
||||
## Adjusting DNS records
|
||||
|
||||
To increase the chances that incoming emails reach your server, you can set up a `MX` record for `matrix.example.com` that looks like this:
|
||||
|
||||
| Type | Host | Priority | Weight | Port | Target |
|
||||
|------|----------|----------|--------|------|------------------------------------|
|
||||
| MX | `matrix` | 10 | 0 | - | `matrix.example.com` |
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Email2Matrix, add the following configuration to your `vars.yml` file. Make sure to replace `ACCESS_TOKEN_FOR_EMAIL2MATRIX1_HERE` and `ACCESS_TOKEN_FOR_EMAIL2MATRIX2_HERE` with the ones created [above](#obtain-an-access-token).
|
||||
|
||||
```yaml
|
||||
matrix_email2matrix_enabled: true
|
||||
|
||||
# You need at least 1 mailbox.
|
||||
matrix_email2matrix_matrix_mappings:
|
||||
- MailboxName: "mailbox1"
|
||||
MatrixRoomId: "!qporfwt:{{ matrix_domain }}"
|
||||
MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
|
||||
MatrixUserId: "@email2matrix1:{{ matrix_domain }}"
|
||||
MatrixAccessToken: "ACCESS_TOKEN_FOR_EMAIL2MATRIX1_HERE"
|
||||
IgnoreSubject: false
|
||||
IgnoreBody: false
|
||||
SkipMarkdown: false
|
||||
|
||||
- MailboxName: "mailbox2"
|
||||
MatrixRoomId: "!aaabaa:{{ matrix_domain }}"
|
||||
MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
|
||||
MatrixUserId: "@email2matrix2:{{ matrix_domain }}"
|
||||
MatrixAccessToken: "ACCESS_TOKEN_FOR_EMAIL2MATRIX2_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.
|
||||
|
||||
@@ -1,10 +1,27 @@
|
||||
<!--
|
||||
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 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 audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
|
||||
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
|
||||
|
||||
@@ -17,13 +34,33 @@ When setting, replace `example.com` with your own.
|
||||
To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
########################################################################
|
||||
# #
|
||||
# etherpad #
|
||||
# #
|
||||
########################################################################
|
||||
|
||||
etherpad_enabled: true
|
||||
|
||||
# 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
|
||||
########################################################################
|
||||
# #
|
||||
# /etherpad #
|
||||
# #
|
||||
########################################################################
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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 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.
|
||||
@@ -43,65 +80,33 @@ After changing the domain, **you may need to adjust your DNS** records to point
|
||||
|
||||
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
|
||||
|
||||
### Configure the default text (optional)
|
||||
|
||||
You can also edit the default text on a new pad with the variable `etherpad_default_pad_text`.
|
||||
|
||||
To do so, add the following configuration to your `vars.yml` file (adapt to your needs):
|
||||
|
||||
```yaml
|
||||
# Note: the whole text (all of its belonging lines) under the variable needs to be indented with 2 spaces.
|
||||
etherpad_default_pad_text: |
|
||||
Welcome to Etherpad!
|
||||
|
||||
This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!
|
||||
|
||||
Get involved with Etherpad at https://etherpad.org
|
||||
```
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- [etherpad role](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad)'s [`defaults/main.yml`](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad/blob/main/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 `etherpad_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:
|
||||
|
||||
<!-- 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
|
||||
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`
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the Etherpad admin user (`etherpad_admin_username`).
|
||||
|
||||
- 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 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.
|
||||
`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
|
||||
|
||||
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`.
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
### Managing / Deleting old pads
|
||||
|
||||
If you want to manage and remove old unused pads from Etherpad, you will first need to create the Etherpad admin user as described above.
|
||||
|
||||
After logging in to the admin web UI, go to the plugin manager page, and install the `adminpads2` plugin.
|
||||
|
||||
Once the plugin is installed, you should have a "Manage pads" section in the UI.
|
||||
💡 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.
|
||||
|
||||
### Integrating a Etherpad widget in a room
|
||||
|
||||
**Note**: 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
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,8 +1,15 @@
|
||||
<!--
|
||||
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):
|
||||
|
||||
|
||||
@@ -1,8 +1,16 @@
|
||||
<!--
|
||||
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-checking-services.md) 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-and-troubleshooting.md#how-to-check-if-services-work) and your server is properly delegated.
|
||||
|
||||
## Federating only with select servers
|
||||
|
||||
|
||||
@@ -1,19 +1,36 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
Jitsi 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 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.
|
||||
|
||||
See the project's [documentation](https://jitsi.github.io/handbook/) to learn what it does and why it might be useful to you.
|
||||
💡 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.
|
||||
|
||||
**Note**: the configuration by the playbook is similar to the one by [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet). You can refer to the official documentation for Docker deployment [here](https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker/).
|
||||
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)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You may need to open the following ports to your server:
|
||||
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).
|
||||
|
||||
- `4443/tcp` - RTP media fallback over TCP
|
||||
- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT configuration, 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)).
|
||||
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
|
||||
|
||||
@@ -26,180 +43,49 @@ When setting, replace `example.com` with your own.
|
||||
To enable Jitsi, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
########################################################################
|
||||
# #
|
||||
# jitsi #
|
||||
# #
|
||||
########################################################################
|
||||
|
||||
jitsi_enabled: true
|
||||
|
||||
########################################################################
|
||||
# #
|
||||
# /jitsi #
|
||||
# #
|
||||
########################################################################
|
||||
```
|
||||
|
||||
### Adjusting the Jitsi URL (optional)
|
||||
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.
|
||||
|
||||
By tweaking the `jitsi_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
|
||||
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.
|
||||
|
||||
Example additional configuration for your `vars.yml` file:
|
||||
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)).
|
||||
|
||||
```yaml
|
||||
# Change the default hostname
|
||||
jitsi_hostname: call.example.com
|
||||
```
|
||||
### Enable authentication and guests mode (optional)
|
||||
|
||||
After changing the domain, **you may need to adjust your DNS** records to point the Jitsi domain to the Matrix server.
|
||||
By default the Jitsi Meet instance **does not require for anyone to log in, and is open to use without an account**.
|
||||
|
||||
### Configure Jitsi authentication and guests mode (optional)
|
||||
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.
|
||||
|
||||
By default the Jitsi instance does not require for anyone to log in, and is open to use without an account. To control who is allowed to start meetings on your Jitsi instance, you'd need to enable Jitsi's authentication and optionally guests mode.
|
||||
|
||||
Authentication type must be one of them: `internal` (default), `jwt`, `matrix` or `ldap`. Currently, only `internal`, `matrix` and `ldap` mechanisms are supported by the [Jitsi role](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi).
|
||||
|
||||
With authentication enabled, all meetings have to be started by a registered user. After the meeting is started by that user, then guests are free to join. If the registered user is not yet present, the guests are put on hold in individual waiting rooms.
|
||||
|
||||
**Note**: authentication is not tested by the playbook's self-checks. We therefore recommend that you would make sure by yourself that authentication is configured properly. To test it, start a meeting at `jitsi.example.com` on your browser.
|
||||
|
||||
#### Authenticate using Jitsi accounts: Auth-Type `internal` (recommended)
|
||||
|
||||
The default authentication mechanism is `internal` auth, which requires a Jitsi account to have been configured. This is a recommended method, as it also works in federated rooms.
|
||||
|
||||
To enable authentication with a Jitsi account, add the following configuration to your `vars.yml` file. Make sure to replace `USERNAME_…` and `PASSWORD_…` with your own values.
|
||||
|
||||
```yaml
|
||||
jitsi_enable_auth: true
|
||||
jitsi_enable_guests: true
|
||||
jitsi_prosody_auth_internal_accounts:
|
||||
- username: "USERNAME_FOR_THE_FIRST_USER_HERE"
|
||||
password: "PASSWORD_FOR_THE_FIRST_USER_HERE"
|
||||
- username: "USERNAME_FOR_THE_SECOND_USER_HERE"
|
||||
password: "PASSWORD_FOR_THE_SECOND_USER_HERE"
|
||||
```
|
||||
|
||||
**Note**: as Jitsi account removal function is not integrated into the playbook, these accounts will not be able to be removed from the Prosody server automatically, even if they are removed from your `vars.yml` file subsequently.
|
||||
|
||||
#### Authenticate using Matrix OpenID: Auth-Type `matrix`
|
||||
|
||||
⚠️ **Warning**: this breaks the Jitsi instance on federated rooms probably and does not allow sharing conference links with guests.
|
||||
|
||||
This authentication method requires [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service), which can be installed using this [playbook](configuring-playbook-user-verification-service.md). It verifies against Matrix openID, and requires a user-verification-service to run.
|
||||
|
||||
To enable authentication with Matrix OpenID, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```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`
|
||||
|
||||
To enable authentication with LDAP, add the following configuration to your `vars.yml` file (adapt to your needs):
|
||||
|
||||
```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.
|
||||
|
||||
### Configure `JVB_ADVERTISE_IPS` for running behind NAT or on a LAN environment (optional)
|
||||
|
||||
When running Jitsi in a LAN environment, or on the public Internet via NAT, the `JVB_ADVERTISE_IPS` enviornment variable should be set.
|
||||
|
||||
This variable allows to control which IP addresses the JVB will advertise for WebRTC media traffic. It is necessary to set it regardless of the use of a reverse proxy, since it's the IP address that will receive the media (audio / video) and not HTTP traffic, hence it's oblivious to the reverse proxy.
|
||||
|
||||
If your users are coming in over the Internet (and not over LAN), this will likely be your public IP address. If this is not set up correctly, calls will crash when more than two users join a meeting.
|
||||
|
||||
To set the variable, add the following configuration to your `vars.yml` file. Make sure to replace `LOCAL_IP_ADDRESS_OF_THE_HOST_HERE` with a proper value.
|
||||
|
||||
```yaml
|
||||
jitsi_jvb_container_extra_arguments:
|
||||
- '--env "JVB_ADVERTISE_IPS=LOCAL_IP_ADDRESS_OF_THE_HOST_HERE"'
|
||||
```
|
||||
|
||||
Check [the official documentation](https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker/#running-behind-nat-or-on-a-lan-environment) for more details about it.
|
||||
|
||||
### Set a maximum number of participants on a Jitsi conference (optional)
|
||||
|
||||
You can set a maximum number of participants allowed to join a Jitsi conference. By default the number is not specified.
|
||||
|
||||
To set it, add the following configuration to your `vars.yml` file (adapt to your needs):
|
||||
|
||||
```yaml
|
||||
jitsi_prosody_max_participants: 4 # example value
|
||||
```
|
||||
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.
|
||||
|
||||
### Enable Gravatar (optional)
|
||||
|
||||
In the default Jisti Meet configuration, `gravatar.com` is enabled as an avatar service.
|
||||
|
||||
Since the Element clients send the URL of configured Matrix avatars to the Jitsi instance, our default configuration has disabled the Gravatar service.
|
||||
Since the Element clients send the URL of configured Matrix avatars to the Jitsi instance, our configuration has disabled the Gravatar service.
|
||||
|
||||
To enable the Gravatar service, add the following configuration to your `vars.yml` file:
|
||||
To enable the Gravatar service nevertheless, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```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.
|
||||
|
||||
### Fine tune Jitsi (optional)
|
||||
|
||||
If you'd like to have Jitsi save up resources, add the following configuration to your `vars.yml` file (adapt to your needs):
|
||||
|
||||
```yaml
|
||||
jitsi_web_config_resolution_width_ideal_and_max: 480
|
||||
jitsi_web_config_resolution_height_ideal_and_max: 240
|
||||
jitsi_web_custom_config_extension: |
|
||||
config.enableLayerSuspension = true;
|
||||
|
||||
config.disableAudioLevels = true;
|
||||
|
||||
config.channelLastN = 4;
|
||||
```
|
||||
|
||||
These configurations:
|
||||
|
||||
- **limit the maximum video resolution**, to save up resources on both server and clients
|
||||
- **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/).
|
||||
- **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved
|
||||
- **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 available by default on other webconference applications such as Office 365 Teams (the number is limited to 4). Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/5ff195985edf46c9399dcf263cb07167f0a2c724/doc/allocation.md).
|
||||
|
||||
### Example configurations
|
||||
|
||||
Here is an example set of configurations for running a Jitsi instance with:
|
||||
|
||||
- authentication using a Jitsi account (username: `US3RNAME`, password: `passw0rd`)
|
||||
- guests: allowed
|
||||
- maximum participants: 6 people
|
||||
- fine tuning with the configurations presented above
|
||||
- other miscellaneous options (see the official Jitsi documentation [here](https://jitsi.github.io/handbook/docs/dev-guide/dev-guide-configuration) and [here](https://jitsi.github.io/handbook/docs/user-guide/user-guide-advanced))
|
||||
|
||||
```yaml
|
||||
jitsi_enabled: true
|
||||
jitsi_enable_auth: true
|
||||
jitsi_enable_guests: true
|
||||
jitsi_prosody_auth_internal_accounts:
|
||||
- username: "US3RNAME"
|
||||
password: "passw0rd"
|
||||
jitsi_prosody_max_participants: 6
|
||||
jitsi_web_config_resolution_width_ideal_and_max: 480
|
||||
jitsi_web_config_resolution_height_ideal_and_max: 240
|
||||
jitsi_web_custom_config_extension: |
|
||||
config.enableLayerSuspension = true;
|
||||
config.disableAudioLevels = true;
|
||||
config.channelLastN = 4;
|
||||
config.requireDisplayName = true; // force users to set a display name
|
||||
config.startAudioOnly = true; // start the conference in audio only mode (no video is being received nor sent)
|
||||
```
|
||||
> [!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.
|
||||
|
||||
## Installing
|
||||
|
||||
@@ -220,170 +106,12 @@ 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`
|
||||
- **directly (without any Matrix integration)**. Just go to `https://jitsi.example.com`, and you can start a videoconference.
|
||||
|
||||
### Set up additional JVBs for more video-conferences (optional)
|
||||
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.
|
||||
|
||||
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'd need to provision additional JVB services on other hosts.
|
||||
|
||||
These settings below will allow you to provision those extra JVB instances. The instances will register themselves with the Prosody service, and be available for Jicofo to route conferences too.
|
||||
|
||||
#### Add the `jitsi_jvb_servers` section on `hosts` file
|
||||
|
||||
For additional JVBs, you'd need to add the section titled `jitsi_jvb_servers` on the ansible `hosts` file with the details of the JVB hosts as below:
|
||||
|
||||
```INI
|
||||
[jitsi_jvb_servers]
|
||||
jvb-2.example.com ansible_host=192.168.0.2
|
||||
```
|
||||
|
||||
Make sure to replace `jvb-2.example.com` with your hostname for the JVB and `192.168.0.2` with your JVB's external IP address, respectively.
|
||||
|
||||
You could add JVB hosts as many as you would like. When doing so, add lines with the details of them.
|
||||
|
||||
#### Prepare `vars.yml` files for additional JVBs
|
||||
|
||||
If the main server is `matrix.example.com` and the additional JVB instance is going to be deployed at `jvb-2.example.com`, the variables for the latter need to be specified on `vars.yml` in its directory (`inventory/host_vars/jvb-2.example.com`).
|
||||
|
||||
Note that most (if not all) variables are common for both servers.
|
||||
|
||||
If you are setting up multiple JVB instances, you'd need to create `vars.yml` files for each of them too (`inventory/host_vars/jvb-3.example.com/vars.yml`, for example).
|
||||
|
||||
#### Set the server ID to each JVB
|
||||
|
||||
Each JVB requires a server ID to be set, so that it will be uniquely identified. The server ID allows Jitsi to keep track of which conferences are on which JVB.
|
||||
|
||||
The server ID can be set with the variable `jitsi_jvb_server_id`. It will end up as the `JVB_WS_SERVER_ID` environment variables in the JVB docker container.
|
||||
|
||||
To set the server ID to `jvb-2`, add the following configuration to either `hosts` or `vars.yml` files (adapt to your needs).
|
||||
|
||||
- On `hosts`:
|
||||
|
||||
Add `jitsi_jvb_server_id=jvb-2` after your JVB's external IP addresses as below:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
- On `vars.yml` files:
|
||||
|
||||
```yaml
|
||||
jitsi_jvb_server_id: 'jvb-2'
|
||||
```
|
||||
|
||||
Alternatively, you can specify the variable as a parameter to [the ansible command](#run-the-playbook).
|
||||
|
||||
**Note**: the server ID `jvb-1` is reserved for the JVB instance running on the Matrix host, therefore should not be used as the ID of an additional JVB host.
|
||||
|
||||
#### Set colibri WebSocket port
|
||||
|
||||
The additional JVBs will need to expose the colibri WebSocket port.
|
||||
|
||||
To expose the port, add the following configuration to your `vars.yml` files:
|
||||
|
||||
```yaml
|
||||
jitsi_jvb_container_colibri_ws_host_bind_port: 9090
|
||||
```
|
||||
|
||||
#### Set Prosody XMPP server
|
||||
|
||||
The JVB will also need to know the location of the Prosody XMPP server.
|
||||
|
||||
Similar to the server ID (`jitsi_jvb_server_id`), this can be set with the variable for the JVB by using the variable `jitsi_xmpp_server`.
|
||||
|
||||
##### Set the Matrix domain
|
||||
|
||||
The Jitsi Prosody container is deployed on the Matrix server by default, so the value can be set to the Matrix domain. To set the value, add the following configuration to your `vars.yml` files:
|
||||
|
||||
```yaml
|
||||
jitsi_xmpp_server: "{{ matrix_domain }}"
|
||||
```
|
||||
|
||||
##### Set an IP address of the Matrix server
|
||||
|
||||
Alternatively, the IP address of the Matrix server can be set. This can be useful if you would like to use a private IP address.
|
||||
|
||||
To set the IP address of the Matrix server, add the following configuration to your `vars.yml` files:
|
||||
|
||||
```yaml
|
||||
jitsi_xmpp_server: "192.168.0.1"
|
||||
```
|
||||
|
||||
##### Expose XMPP port
|
||||
|
||||
By default, the Matrix server does not expose the XMPP port (`5222`); only the XMPP container exposes it internally inside the host. This means that the first JVB (which runs on the Matrix server) can reach it but the additional JVBs cannot. Therefore, the XMPP server needs to expose the port, so that the additional JVBs can connect to it.
|
||||
|
||||
To expose the port and have Docker forward the port, add the following configuration to your `vars.yml` files:
|
||||
|
||||
```yaml
|
||||
jitsi_prosody_container_jvb_host_bind_port: 5222
|
||||
```
|
||||
|
||||
#### Reverse-proxy with Traefik
|
||||
|
||||
To make Traefik reverse-proxy to these additional JVBs, add the following configuration to your main `vars.yml` file (`inventory/host_vars/matrix.example.com/vars.yml`):
|
||||
|
||||
```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 %}
|
||||
```
|
||||
|
||||
#### Run the playbook
|
||||
|
||||
After configuring `hosts` and `vars.yml` files, run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start
|
||||
```
|
||||
Check [the official user guide](https://jitsi.github.io/handbook/docs/category/user-guide) for details about how to use Jitsi.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `Error: Account creation/modification not supported`
|
||||
|
||||
If you get an error like `Error: Account creation/modification not supported` with authentication enabled, it's likely that you had previously installed Jitsi without auth/guest support.
|
||||
|
||||
In this case, you should consider to rebuild your Jitsi installation.
|
||||
|
||||
### Rebuilding your Jitsi installation
|
||||
|
||||
If you ever run into any trouble or if you have changed configuration (`jitsi_*` variables) too much, you can rebuild your Jitsi installation.
|
||||
|
||||
We normally don't recommend manual intervention, but Jitsi services tend to generate a lot of configuration files, and it is often wise to start afresh setting the services up, rather than messing with the existing configuration files. Since not all of those files are managed by Ansible (at least not yet), you may sometimes need to delete them by yourself manually.
|
||||
|
||||
To rebuild your Jitsi configuration, follow the procedure below:
|
||||
|
||||
- run this command locally to stop all Jitsi services: `just run-tags stop-group --extra-vars=group=jitsi`
|
||||
- log in the server with SSH
|
||||
- run this command remotely to remove all Jitsi configuration & data: `rm -rf /matrix/jitsi`
|
||||
- run this command locally to set up Jitsi anew and restart services: `just install-service jitsi`
|
||||
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.
|
||||
|
||||
47
docs/configuring-playbook-jwt-service.md
Normal file
47
docs/configuring-playbook-jwt-service.md
Normal file
@@ -0,0 +1,47 @@
|
||||
<!--
|
||||
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.
|
||||
@@ -1,10 +1,21 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
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):
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
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
|
||||
@@ -21,20 +32,29 @@ 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**, feel free to disable it:
|
||||
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:
|
||||
|
||||
```yaml
|
||||
matrix_synapse_password_config_localdb_enabled: false
|
||||
```
|
||||
|
||||
## Using ma1sd Identity Server for authentication (not recommended)
|
||||
## Installing
|
||||
|
||||
The playbook can instead configure [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for LDAP authentication. However, **we recommend not bothering with installing it** as ma1sd has been unmaintained for years.
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
If you wish to install it anyway, consult the [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
|
||||
```
|
||||
|
||||
## Handling user registration
|
||||
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
|
||||
|
||||
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).
|
||||
|
||||
18
docs/configuring-playbook-livekit-jwt-service.md
Normal file
18
docs/configuring-playbook-livekit-jwt-service.md
Normal file
@@ -0,0 +1,18 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2025 Slavi Pantaleev
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up LiveKit JWT Service (optional)
|
||||
|
||||
The playbook can install and configure [LiveKit JWT Service](https://github.com/element-hq/lk-jwt-service/) for you.
|
||||
|
||||
This is a helper component which is part of the [Matrix RTC stack](configuring-playbook-matrix-rtc.md) that allows [Element Call](configuring-playbook-element-call.md) to integrate with [LiveKit Server](configuring-playbook-livekit-server.md).
|
||||
|
||||
💡 LiveKit JWT Service is automatically installed and configured when either [Element Call](configuring-playbook-element-call.md) or the [Matrix RTC stack](configuring-playbook-matrix-rtc.md) is enabled, so you don't need to do anything extra.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-livekit-jwt-service/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
- `roles/custom/matrix-livekit-jwt-service/templates/env.j2` for the component's default configuration.
|
||||
38
docs/configuring-playbook-livekit-server.md
Normal file
38
docs/configuring-playbook-livekit-server.md
Normal file
@@ -0,0 +1,38 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2024 wjbeckett
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up LiveKit Server (optional)
|
||||
|
||||
The playbook can install and configure [LiveKit Server](https://github.com/livekit/livekit) for you.
|
||||
|
||||
LiveKit Server is an open source project that provides scalable, multi-user conferencing based on WebRTC. It's designed to provide everything you need to build real-time video audio data capabilities in your applications.
|
||||
|
||||
💡 LiveKit Server is automatically installed and configured when either [Element Call](configuring-playbook-element-call.md) or the [Matrix RTC stack](configuring-playbook-matrix-rtc.md) is enabled, so you don't need to do anything extra.
|
||||
|
||||
The [Ansible role for LiveKit Server](https://github.com/mother-of-all-self-hosting/ansible-role-livekit-server) 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 LiveKit Server, you can check them via:
|
||||
- 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-livekit-server/blob/main/docs/configuring-livekit-server.md) online
|
||||
- 📁 `roles/galaxy/livekit-server/docs/configuring-livekit-server.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
|
||||
|
||||
## Adjusting firewall rules
|
||||
|
||||
To ensure LiveKit Server functions correctly, the following firewall rules and port forwarding settings are required:
|
||||
|
||||
- `7881/tcp`: ICE/TCP
|
||||
|
||||
- `7882/udp`: ICE/UDP Mux
|
||||
|
||||
- `3479/udp`: TURN/UDP. Also see the [Limitations](#limitations) section below.
|
||||
|
||||
- `5350/tcp`: TURN/TCP. Also see the [Limitations](#limitations) section below.
|
||||
|
||||
💡 The suggestions above are inspired by the upstream [Ports and Firewall](https://docs.livekit.io/home/self-hosting/ports-firewall/) documentation based on how LiveKit is configured in the playbook. If you've using custom configuration for the LiveKit Server role, you may need to adjust the firewall rules accordingly.
|
||||
|
||||
## Limitations
|
||||
|
||||
For some reason, LiveKit Server's TURN ports (`3479/udp` and `5350/tcp`) are not reachable over IPv6 regardless of whether you've [enabled IPv6](./configuring-ipv6.md) for your server.
|
||||
|
||||
It seems like LiveKit Server intentionally only listens on `udp4` and `tcp4` as seen [here](https://github.com/livekit/livekit/blob/154b4d26b769c68a03c096124094b97bf61a996f/pkg/service/turn.go#L128) and [here](https://github.com/livekit/livekit/blob/154b4d26b769c68a03c096124094b97bf61a996f/pkg/service/turn.go#L92).
|
||||
@@ -1,6 +1,20 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2019 - 2020 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2019 Noah Fleischmann
|
||||
SPDX-FileCopyrightText: 2020 Justin Croonenberghs
|
||||
SPDX-FileCopyrightText: 2020 Marcel Partap
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up ma1sd Identity Server (optional)
|
||||
|
||||
**⚠️Note**: ma1sd itself has also been unmaintained for years (the latest commit and release being from 2021). The role of identity servers in the Matrix specification also has an uncertain future. **We recommend not bothering with installing it unless it's the only way you can do what you need to do**. For example, certain things like LDAP integration can also be implemented via [the LDAP provider module for Synapse](./configuring-playbook-ldap-auth.md).
|
||||
> [!WARNING]
|
||||
> Since ma1sd has been unmaintained for years (the latest commit and release being from 2021) and the future of identity server's role in the Matrix specification is uncertain, **we recommend not bothering with installing it unless it's the only way you can do what you need to do**.
|
||||
>
|
||||
> Please note that certain things can be achieved with other components. For example, if you wish to implement LDAP integration, you might as well check out [the LDAP provider module for Synapse](./configuring-playbook-ldap-auth.md) instead.
|
||||
|
||||
The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you. It is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.
|
||||
|
||||
@@ -47,15 +61,15 @@ To enable matrix.org forwarding, add the following configuration to your `vars.y
|
||||
matrix_ma1sd_matrixorg_forwarding_enabled: true
|
||||
```
|
||||
|
||||
### Additional features
|
||||
### Extending the configuration
|
||||
|
||||
What this playbook configures for your is some bare minimum Identity Server functionality, so that you won't need to rely on external 3rd party services.
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
A few variables can be toggled in this playbook to alter the ma1sd configuration that gets generated.
|
||||
Take a look at:
|
||||
|
||||
Still, ma1sd can do much more. You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
|
||||
- `roles/custom/matrix-ma1sd/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_ma1sd_configuration_extension_yaml` variable
|
||||
|
||||
To use a more custom configuration, you can define a `matrix_ma1sd_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_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
|
||||
You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
|
||||
|
||||
#### Customizing email templates
|
||||
|
||||
@@ -65,15 +79,15 @@ If you'd like to change the default email templates used by ma1sd, take a look a
|
||||
|
||||
To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) feature of ma1sd, you can make use of the following variables:
|
||||
|
||||
- `matrix_synapse_enable_registration` - to enable user-initiated registration in Synapse
|
||||
- `matrix_synapse_enable_registration` — to enable user-initiated registration in Synapse
|
||||
|
||||
- `matrix_synapse_enable_registration_captcha` - to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring-captcha.md) documentation.
|
||||
- `matrix_synapse_enable_registration_captcha` — to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring-captcha.md) documentation.
|
||||
|
||||
- `matrix_synapse_registrations_require_3pid` - a list of 3pid types (among `'email'`, `'msisdn'`) required by the Synapse server for registering
|
||||
- `matrix_synapse_registrations_require_3pid` — a list of 3pid types (among `'email'`, `'msisdn'`) required by the Synapse server for registering
|
||||
|
||||
- variables prefixed with `matrix_ma1sd_container_labels_` (e.g. `matrix_ma1sd_container_labels_matrix_client_3pid_registration_enabled`) - to configure the Traefik reverse-proxy to capture and send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality
|
||||
- variables prefixed with `matrix_ma1sd_container_labels_` (e.g. `matrix_ma1sd_container_labels_matrix_client_3pid_registration_enabled`) — to configure the Traefik reverse-proxy to capture and send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality
|
||||
|
||||
- `matrix_ma1sd_configuration_extension_yaml` - to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`.
|
||||
- `matrix_ma1sd_configuration_extension_yaml` — to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`.
|
||||
|
||||
**Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) or the `openid` APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the `openid` APIs (only!) on the federation port. Make sure the federation port (usually `https://matrix.example.com:8448`) is whitelisted in your firewall (even if you don't actually use/need federation).
|
||||
|
||||
@@ -150,10 +164,13 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
|
||||
If email address validation emails sent by ma1sd are not reaching you, you should look into [Adjusting email-sending settings](configuring-playbook-email.md).
|
||||
|
||||
If you'd like additional logging information, temporarily enable verbose logging for ma1sd.
|
||||
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-ma1sd`.
|
||||
|
||||
To enable it, add the following configuration to your `vars.yml` file:
|
||||
### 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
|
||||
# See: https://github.com/ma1uta/ma1sd/blob/master/docs/troubleshooting.md#increase-verbosity
|
||||
matrix_ma1sd_verbose_logging: true
|
||||
```
|
||||
|
||||
@@ -1,6 +1,13 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up Matrix Authentication Service (optional)
|
||||
|
||||
The playbook can install and configure [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) (MAS) - a service operating alongside your existing [Synapse](./configuring-playbook-synapse.md) homeserver and providing [better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/).
|
||||
The playbook can install and configure [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) (MAS) — a service operating alongside your existing [Synapse](./configuring-playbook-synapse.md) homeserver and providing [better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/).
|
||||
|
||||
Matrix Authentication Service is an implementation of [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and still work in progress, tracked at the [areweoidcyet.com](https://areweoidcyet.com/) website.
|
||||
|
||||
@@ -36,8 +43,6 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
|
||||
|
||||
- ⚠️ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
|
||||
|
||||
- ⚠️ **email sending** configured (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.
|
||||
|
||||
- ❌ **disabling all password providers** for Synapse (things like [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc.) More details about this are available in the [Expectations](#expectations) section below.
|
||||
|
||||
## Expectations
|
||||
@@ -54,28 +59,21 @@ This section details what you can expect when switching to the Matrix Authentica
|
||||
|
||||
> cannot initialize matrix bot error="olm account is marked as shared, keys seem to have disappeared from the server"
|
||||
|
||||
- [matrix-reminder-bot](./configuring-playbook-bot-matrix-reminder-bot.md) fails to start (see [element-hq/matrix-authentication-service#3439](https://github.com/element-hq/matrix-authentication-service/issues/3439))
|
||||
- Other services may be similarly affected. This list is not exhaustive.
|
||||
|
||||
- ❌ **Encrypted appservices** do not work yet (related to [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190) and [PR 17705 for Synapse](https://github.com/element-hq/synapse/pull/17705)), so all bridges/bots that rely on encryption will fail to start (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3658) for Hookshot). You can use these bridges/bots only if you **keep end-to-bridge encryption disabled** (which is the default setting).
|
||||
|
||||
- ⚠️ **You will need to have email sending configured** (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.
|
||||
|
||||
- ⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) is **possible**, but requires **some playbook-assisted manual work**. Migration is **reversible with no or minor issues if done quickly enough**, but as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.
|
||||
|
||||
- ⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) does not currently seem to preserve the "admin" flag for users (as found in the Synapse database). All users are imported as non-admin - see [element-hq/matrix-authentication-service#3440](https://github.com/element-hq/matrix-authentication-service/issues/3440). You may need update the Matrix Authentication Service's database manually and adjust the `can_request_admin` column in the `users` table to `true` for users that need to be administrators (e.g. `UPDATE users SET can_request_admin = true WHERE username = 'someone';`)
|
||||
|
||||
- ⚠️ Delegating user authentication to MAS causes **your Synapse server to be completely dependant on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch.
|
||||
|
||||
- ⚠️ If you've got [OIDC configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to migrate your OIDC configuration to MAS by adding an [Upstream OAuth2 configuration](#upstream-oauth2-configuration).
|
||||
|
||||
- ⚠️ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed - all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md).
|
||||
- ⚠️ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed — all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md).
|
||||
|
||||
- ✅ Your **existing login sessions will continue to work** (you won't get logged out). Migration will require a bit of manual work and minutes of downtime, but it's not too bad.
|
||||
|
||||
- ✅ Various clients ([Cinny](./configuring-playbook-client-cinny.md), [Element Web](./configuring-playbook-client-element-web.md), Element X, FluffyChat) will be able to use the **new SSO-based login flow** provided by Matrix Authentication Service
|
||||
|
||||
- ✅ The **old login flow** (called `m.login.password`) **will still continue to work**, so clients (old Element Web, etc.) and bridges/bots that don't support the new OIDC-based login flow will still work. Going through the old login flow does not require users to have a verified email address, as [is the case](https://github.com/element-hq/matrix-authentication-service/issues/1505) for the new SSO-based login flow.
|
||||
- ✅ The **old login flow** (called `m.login.password`) **will still continue to work**, so clients (old Element Web, etc.) and bridges/bots that don't support the new OIDC-based login flow will still work
|
||||
|
||||
- ✅ [Registering users](./registering-users.md) via **the playbook's `register-user` tag remains unchanged**. The playbook automatically does the right thing regardless of homeserver implementation (Synapse, Dendrite, etc.) and whether MAS is enabled or not. When MAS is enabled, the playbook will forward user-registration requests to MAS. Registering users via the command-line is no longer done via the `/matrix/synapse/bin/register` script, but via `/matrix/matrix-authentication-service/bin/register-user`.
|
||||
|
||||
@@ -248,7 +246,7 @@ matrix_authentication_service_config_upstream_oauth2_providers:
|
||||
#action: force
|
||||
#template: "{% raw %}{{ user.preferred_username }}{% endraw %}"
|
||||
# The display name is the user's display name.
|
||||
displayname:
|
||||
#displayname:
|
||||
#action: suggest
|
||||
#template: "{% raw %}{{ user.name }}{% endraw %}"
|
||||
# An email address to import.
|
||||
@@ -276,6 +274,15 @@ matrix_authentication_service_config_upstream_oauth2_providers:
|
||||
- go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process
|
||||
- remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-authentication-service/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
- `roles/custom/matrix-authentication-service/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_authentication_service_configuration_extension_yaml` variable
|
||||
|
||||
## Installing
|
||||
|
||||
Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
@@ -428,7 +435,9 @@ If successful, you should see some output that looks like this:
|
||||
✅ The legacy login API at "https://matrix.example.com/_matrix/client/v3/login" is reachable and is handled by MAS.
|
||||
```
|
||||
|
||||
## Management
|
||||
## Usage
|
||||
|
||||
### Management
|
||||
|
||||
You can use the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) (exposed via the `/matrix/matrix-authentication-service/bin/mas-cli` script) to perform administrative tasks against MAS.
|
||||
|
||||
@@ -440,18 +449,26 @@ This documentation page already mentions:
|
||||
|
||||
There are other sub-commands available. Run `/matrix/matrix-authentication-service/bin/mas-cli` to get an overview.
|
||||
|
||||
## User registration
|
||||
### User registration
|
||||
|
||||
After Matrix Authentication Service is [installed](#installing), users need to be managed there (unless you're managing them in an [upstream OAuth2 provider](#upstream-oauth2-configuration)).
|
||||
|
||||
You can register users new users as described in the [Registering users](./registering-users.md) documentation (via `mas-cli manage register-user` or the Ansible playbook's `register-user` tag).
|
||||
|
||||
## Working around email deliverability issues
|
||||
### Working around email deliverability issues
|
||||
|
||||
Because Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user, you may need to work around email deliverability issues if [your email-sending configuration](./configuring-playbook-email.md) is not working.
|
||||
Matrix Authentication Service only sends emails when:
|
||||
|
||||
Matrix Authentication Service attempts to verify email addresses by sending a verification email to the address specified by the user whenever they log in to an account without a verified email address.
|
||||
- it verifies email addresses for users who are self-registering with a password
|
||||
|
||||
If email delivery is not working, **you can retrieve the email configuration code from the Matrix Authentication Service's logs** (`journalctl -fu matrix-authentication-service`).
|
||||
- a user tries to add an email to their account
|
||||
|
||||
If Matrix Authentication Service tries to send an email and it fails because [your email-sending configuration](./configuring-playbook-email.md) is not working, you may need to work around email deliverability.
|
||||
|
||||
If email delivery is not working, **you can retrieve the email verification code from the Matrix Authentication Service's logs** (`journalctl -fu matrix-authentication-service`).
|
||||
|
||||
Alternatively, you can use the [`mas-cli` management tool](#management) to manually verify email addresses for users. Example: `/matrix/matrix-authentication-service/bin/mas-cli manage verify-email some.username email@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-authentication-service`.
|
||||
|
||||
@@ -1,10 +1,15 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2025 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up Matrix Corporal (optional, advanced)
|
||||
|
||||
<hr/>
|
||||
|
||||
⚠️ **Warning**: This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal](https://github.com/devture/matrix-corporal). If you're unsure whether you have such a need, you most likely don't.
|
||||
|
||||
<hr/>
|
||||
> [!WARNING]
|
||||
> This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal](https://github.com/devture/matrix-corporal). If you're unsure whether you have such a need, you most likely don't.
|
||||
|
||||
The playbook can install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you.
|
||||
|
||||
@@ -115,6 +120,15 @@ aux_file_definitions:
|
||||
|
||||
To learn more about what the policy configuration, see the matrix-corporal documentation on [policy](https://github.com/devture/matrix-corporal/blob/master/docs/policy.md).
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-corporal/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
- `roles/custom/matrix-corporal/templates/config.json.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_corporal_configuration_extension_json` variable
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
@@ -138,4 +152,16 @@ The following local filesystem paths are mounted in the `matrix-corporal` contai
|
||||
|
||||
- `/matrix/corporal/cache` is mounted at `/var/cache/matrix-corporal` (read and write)
|
||||
|
||||
As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config`) needs to refer to these files via the local container paths - `/etc/matrix-corporal` (read-only), `/var/matrix-corporal` (read and write), `/var/cache/matrix-corporal` (read and write).
|
||||
As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config`) needs to refer to these files via the local container paths — `/etc/matrix-corporal` (read-only), `/var/matrix-corporal` (read and write), `/var/cache/matrix-corporal` (read and write).
|
||||
|
||||
## 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-corporal`.
|
||||
|
||||
### 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_corporal_debug: true
|
||||
```
|
||||
|
||||
@@ -1,22 +1,33 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up matrix-ldap-registration-proxy (optional)
|
||||
|
||||
The playbook can install and configure [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) for you.
|
||||
|
||||
This proxy handles Matrix registration requests and forwards them to LDAP.
|
||||
|
||||
See the project's [documentation](https://gitlab.com/activism.international/matrix_ldap_registration_proxy/-/blob/main/README.md) to learn what it does and why it might be useful to you.
|
||||
|
||||
**Note**: This does support the full Matrix specification for registrations. It only provide a very coarse implementation of a basic password registration.
|
||||
|
||||
## Quickstart
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
To enable the component, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
|
||||
```yaml
|
||||
matrix_ldap_registration_proxy_enabled: true
|
||||
|
||||
# LDAP credentials
|
||||
matrix_ldap_registration_proxy_ldap_uri: <URI>
|
||||
matrix_ldap_registration_proxy_ldap_base_dn: <DN>
|
||||
matrix_ldap_registration_proxy_ldap_user: <USER>
|
||||
matrix_ldap_registration_proxy_ldap_password: <password>
|
||||
matrix_ldap_registration_proxy_ldap_uri: YOUR_URI_HERE
|
||||
matrix_ldap_registration_proxy_ldap_base_dn: YOUR_DN_HERE
|
||||
matrix_ldap_registration_proxy_ldap_user: YOUR_USER_HERE
|
||||
matrix_ldap_registration_proxy_ldap_password: YOUR_PASSWORD_HERE
|
||||
```
|
||||
|
||||
If you already use the [synapse external password provider via LDAP](configuring-playbook-ldap-auth.md) (that is, you have `matrix_synapse_ext_password_provider_ldap_enabled: true` and other options in your configuration) you can use the following values as configuration:
|
||||
@@ -32,6 +43,14 @@ matrix_ldap_registration_proxy_systemd_wanted_services_list_custom:
|
||||
- matrix-synapse.service
|
||||
```
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-ldap-registration-proxy/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:
|
||||
@@ -44,3 +63,7 @@ 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-ldap-registration-proxy`.
|
||||
|
||||
@@ -1,39 +1,81 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2023 - 2024 Michael Hollister
|
||||
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
|
||||
-->
|
||||
|
||||
# Storing Matrix media files using matrix-media-repo (optional)
|
||||
|
||||
[matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/) (often abbreviated "MMR") is a highly customizable multi-domain media repository for Matrix. Intended for medium to large environments consisting of several homeservers, this media repo de-duplicates media (including remote media) while being fully compliant with the specification.
|
||||
The playbook can install and configure [matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/) (often abbreviated "MMR") for you.
|
||||
|
||||
Smaller/individual homeservers can still make use of this project's features, though it may be difficult to set up or have higher than expected resource consumption. Please do your research before deploying this as this project may not be useful for your environment.
|
||||
MMR is a highly customizable multi-domain media repository for Matrix. Intended for medium to large environments consisting of several homeservers, this media repo de-duplicates media (including remote media) while being fully compliant with the specification.
|
||||
|
||||
For a simpler alternative (which allows you to offload your media repository storage to S3, etc.), you can [configure S3 storage](configuring-playbook-s3.md) instead of setting up matrix-media-repo.
|
||||
**Notes**:
|
||||
- If MMR is enabled, other media store roles should be disabled (if using Synapse with other media store roles).
|
||||
- Smaller/individual homeservers can still make use of this project's features, though it may be difficult to set up or have higher than expected resource consumption. Please do your research before deploying this as this project may not be useful for your environment.
|
||||
- For a simpler alternative (which allows you to offload your media repository storage to S3, etc.), you can [configure S3 storage](configuring-playbook-s3.md) instead of setting up matrix-media-repo.
|
||||
|
||||
| **Table of Contents** |
|
||||
| :------------------------------------------------------------------------------------------ |
|
||||
| [Quickstart](#quickstart) |
|
||||
| [Additional configuration options](#configuring-the-media-repo) |
|
||||
| [Importing data from an existing media store](#importing-data-from-an-existing-media-store) |
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
## Quickstart
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file and [re-run the installation process](./installing.md) for the playbook:
|
||||
To enable matrix-media-repo, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_media_repo_enabled: true
|
||||
|
||||
# (optional) Turned off by default
|
||||
# matrix_media_repo_metrics_enabled: true
|
||||
```
|
||||
|
||||
The repo is pre-configured for integrating with the Postgres database, Traefik proxy and [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) (if metrics enabled) from this playbook for all the available homeserver roles. When the media repo is enabled, other media store roles should be disabled (if using Synapse with other media store roles).
|
||||
|
||||
By default, the media-repo will use the local filesystem for data storage. You can alternatively use a `s3` cloud backend as well. Access token caching is also enabled by default since the logout endpoints are proxied through the media repo.
|
||||
|
||||
## Configuring the media-repo
|
||||
### Enable metrics
|
||||
|
||||
Additional common configuration options:
|
||||
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_media_repo_metrics_enabled: true
|
||||
```
|
||||
|
||||
# The postgres database pooling options
|
||||
**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/matrix-media-repo` by adding the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_media_repo_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_media_repo_container_labels_traefik_metrics_middleware_basic_auth_enabled: true
|
||||
matrix_media_repo_container_labels_traefik_metrics_middleware_basic_auth_users: ''
|
||||
```
|
||||
|
||||
To `matrix_media_repo_container_labels_traefik_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.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-media-repo/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
|
||||
Here is a list of additional common configuration options:
|
||||
|
||||
```yaml
|
||||
# The Postgres database pooling options
|
||||
|
||||
# The maximum number of connects to hold open. More of these allow for more concurrent
|
||||
# processes to happen.
|
||||
@@ -60,10 +102,10 @@ matrix_media_repo_admins: []
|
||||
# To disable this datastore, making it readonly, specify `forKinds: []`.
|
||||
#
|
||||
# The kinds available are:
|
||||
# thumbnails - Used to store thumbnails of media (local and remote).
|
||||
# remote_media - Original copies of remote media (servers not configured by this repo).
|
||||
# local_media - Original uploads for local media.
|
||||
# archives - Archives of content (GDPR and similar requests).
|
||||
# thumbnails — Used to store thumbnails of media (local and remote).
|
||||
# remote_media — Original copies of remote media (servers not configured by this repo).
|
||||
# local_media — Original uploads for local media.
|
||||
# archives — Archives of content (GDPR and similar requests).
|
||||
matrix_media_repo_datastore_file_for_kinds: ["thumbnails", "remote_media", "local_media", "archives"]
|
||||
matrix_media_repo_datastore_s3_for_kinds: []
|
||||
|
||||
@@ -85,11 +127,8 @@ matrix_media_repo_datastore_s3_opts_bucket_name: "your-media-bucket"
|
||||
# An optional storage class for tuning how the media is stored at s3.
|
||||
# See https://aws.amazon.com/s3/storage-classes/ for details; uncomment to use.
|
||||
# matrix_media_repo_datastore_s3_opts_storage_class: "STANDARD"
|
||||
|
||||
```
|
||||
|
||||
Full list of configuration options with documentation can be found in [`roles/custom/matrix-media-repo/defaults/main.yml`](../roles/custom/matrix-media-repo/defaults/main.yml)
|
||||
|
||||
## Signing Keys
|
||||
|
||||
Authenticated media endpoints ([MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916)) requires MMR to have a configured signing key to authorize outbound federation requests. Additionally, the signing key must be merged with your homeserver's signing key file.
|
||||
@@ -161,3 +200,15 @@ docker exec -it matrix-media-repo \
|
||||
Enter `1` for the Machine ID when prompted (you are not doing any horizontal scaling) unless you know what you're doing.
|
||||
|
||||
This should output a `msg="Import completed"` when finished successfully!
|
||||
|
||||
## 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-media-repo`.
|
||||
|
||||
### Increase logging verbosity
|
||||
|
||||
If you want to turn on sentry's built-in debugging, add the following configuration to your `vars.yml` file and re-run the playbook:
|
||||
|
||||
```yaml
|
||||
matrix_media_repo_sentry_debug: true
|
||||
```
|
||||
|
||||
@@ -1,8 +1,16 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2022 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up matrix-registration (optional)
|
||||
|
||||
⚠️ **Warnings**:
|
||||
- This is a poorly maintained and buggy project. It's better to avoid using it.
|
||||
- This is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md)
|
||||
> [!WARNING]
|
||||
> - This is a poorly maintained and buggy project. It's better to avoid using it.
|
||||
> - This is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md)
|
||||
|
||||
The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you. It is a simple python application to have a token based Matrix registration.
|
||||
|
||||
@@ -47,6 +55,15 @@ If you've changed the default hostname, you may need to create a CNAME record fo
|
||||
|
||||
When setting, replace `example.com` with your own.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-registration/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
- `roles/custom/matrix-registration/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_registration_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:
|
||||
@@ -64,7 +81,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
|
||||
**matrix-registration** gets exposed at `https://matrix.example.com/matrix-registration`
|
||||
|
||||
It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) - for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using `curl`.
|
||||
It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) — for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using `curl`.
|
||||
|
||||
We make the most common APIs easy to use via the playbook (see below).
|
||||
|
||||
@@ -92,3 +109,7 @@ ansible-playbook -i inventory/hosts setup.yml \
|
||||
```
|
||||
|
||||
The shortcut command with `just` program is also available: `just run-tags list-matrix-registration-tokens`
|
||||
|
||||
## 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-registration`.
|
||||
|
||||
59
docs/configuring-playbook-matrix-rtc.md
Normal file
59
docs/configuring-playbook-matrix-rtc.md
Normal file
@@ -0,0 +1,59 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2024 wjbeckett
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up the Matrix RTC stack (optional)
|
||||
|
||||
The playbook can install and configure the Matrix RTC (Real-Time Communication) stack.
|
||||
|
||||
The Matrix RTC stack is a set of supporting components ([LiveKit Server](configuring-playbook-livekit-server.md) and [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md)) that allow the new [Element Call](configuring-playbook-element-call.md) audio/video calls to function.
|
||||
|
||||
💡 If you only plan on doing audio/video calls via Matrix client (which typically embed the Element Call frontend UI within them), you only need to install the Matrix RTC stack and don't necessarily need to install [Element Call](configuring-playbook-element-call.md). See the [Decide between Element Call vs just the Matrix RTC stack](configuring-playbook-element-call.md#decide-between-element-call-vs-just-the-matrix-rtc-stack) section of the [Element Call documentation](configuring-playbook-element-call.md) for more details.
|
||||
|
||||
## 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 or the Matrix RTC stack is enabled](#decide-between-element-call-vs-just-the-matrix-rtc-stack))
|
||||
- The [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (automatically installed when [Element Call or the Matrix RTC stack is enabled](#decide-between-element-call-vs-just-the-matrix-rtc-stack))
|
||||
- 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**.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
# Enable the Matrix RTC stack.
|
||||
# This provides all supporting services for Element Call, without the Element Call frontend.
|
||||
matrix_rtc_enabled: true
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## 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, Matrix clients which support Element Call (like [Element Web](configuring-playbook-client-element-web.md) and Element X on mobile (iOS and Android)) will automatically use the Matrix RTC stack.
|
||||
|
||||
These clients typically embed the Element Call frontend UI within them, so installing [Element Call](configuring-playbook-element-call.md) is only necessary if you'd like to use it standalone - directly via a browser.
|
||||
@@ -1,3 +1,14 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2019 - 2020 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2019 Paul Tötterman
|
||||
SPDX-FileCopyrightText: 2020 - 2021 Agustin Ferrario
|
||||
SPDX-FileCopyrightText: 2021 Aaron Raimist
|
||||
SPDX-FileCopyrightText: 2021 Stuart Thomson
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Configure Nginx (optional, advanced)
|
||||
|
||||
Since 2024-01, this playbook no longer uses nginx as its reverse-proxy.
|
||||
|
||||
@@ -1,12 +1,47 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2022 - 2024 Nikita Chernyi
|
||||
SPDX-FileCopyrightText: 2022 Julian Foad
|
||||
SPDX-FileCopyrightText: 2022 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2023 Felix Stupp
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up the ntfy push notifications server (optional)
|
||||
|
||||
The playbook can install and configure the [ntfy](https://ntfy.sh/) push notifications server for you.
|
||||
The playbook can install and configure the [ntfy](https://ntfy.sh/) (pronounced "notify") push notifications server for you.
|
||||
|
||||
Using the [UnifiedPush](https://unifiedpush.org) standard, ntfy enables self-hosted (Google-free) push notifications from Matrix (and other) servers to UnifiedPush-compatible Matrix compatible client apps running on Android and other devices.
|
||||
ntfy lets you send push notifications to your phone or desktop via scripts from any computer, using simple HTTP PUT or POST requests. It makes it possible to send/receive notifications, without relying on servers owned and controlled by third parties.
|
||||
|
||||
This role is intended to support UnifiedPush notifications for use with the Matrix and Matrix-related services that this playbook installs. This role is not intended to support all of ntfy's other features.
|
||||
With the [UnifiedPush](https://unifiedpush.org) standard, ntfy also enables self-hosted push notifications from Matrix (and other) servers to UnifiedPush-compatible Matrix client apps running on Android devices.
|
||||
|
||||
**Note**: In contrast to push notifications using Google's FCM or Apple's APNs, the use of UnifiedPush allows each end-user to choose the push notification server that they prefer. As a consequence, deploying this ntfy server does not by itself ensure any particular user or device or client app will use it.
|
||||
See the project's [documentation](https://docs.ntfy.sh/) to learn what ntfy does and why it might be useful to you.
|
||||
|
||||
The [Ansible role for ntfy](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy) 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 ntfy, you can check them via:
|
||||
- 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md) online
|
||||
- 📁 `roles/galaxy/ntfy/docs/configuring-ntfy.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
|
||||
|
||||
**Note**: this playbook focuses on setting up a ntfy server for getting it send push notifications with UnifiedPush to Matrix-related services that this playbook installs, while the installed server will be available for other non-Matrix apps like [Tusky](https://tusky.app/) and [DAVx⁵](https://www.davx5.com/) as well. This playbook does not intend to support all of ntfy's features. If you want to use them as well, refer the role's documentation for details to configure them by yourself.
|
||||
|
||||
### Improve push notification's privacy with ntfy
|
||||
|
||||
By default, push notifications received on Matrix apps on Android/iOS act merely as "wake-up calls" for the application, which contain only event IDs, and do not transmit actual message payload such as text message data.
|
||||
|
||||
While your messages remain private even without ntfy, it makes it possible to improve privacy and sovereignty of your Matrix installation, offering greater control over your data, by avoiding routing these "application wake-up calls" through Google or Apple servers and having them pass through the self-hosted ntfy instance on your Matrix server.
|
||||
|
||||
### How ntfy works with UnifiedPush
|
||||
|
||||
⚠️ [UnifiedPush does not work on iOS.](https://unifiedpush.org/users/faq/#will-unifiedpush-ever-work-on-ios)
|
||||
|
||||
ntfy implements UnifiedPush, the standard which makes it possible to send and receive push notifications without using Google's Firebase Cloud Messaging (FCM) service.
|
||||
|
||||
Working as a **Push Server**, a ntfy server can forward messages via [the ntfy Android app](https://docs.ntfy.sh/subscribe/phone/) as a **Distributor** to a UnifiedPush-compatible Matrix client such as Element Android and FluffyChat Android (see [here](https://unifiedpush.org/users/distributors/#definitions) for the definition of the Push Server and the Distributor).
|
||||
|
||||
Note that UnifiedPush-compatible applications must be able to communicate with the ntfy Android app which works as the Distributor on the same device, in order to receive push notifications from the Push Server.
|
||||
|
||||
As the ntfy Android app functions as the Distributor, you do not have to install something else on your device, besides a UnifiedPush-compatible Matrix client.
|
||||
|
||||
## Adjusting DNS records
|
||||
|
||||
@@ -16,23 +51,27 @@ When setting, replace `example.com` with your own.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable ntfy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
To enable a ntfy server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
# Enabling it is the only required setting
|
||||
########################################################################
|
||||
# #
|
||||
# ntfy #
|
||||
# #
|
||||
########################################################################
|
||||
|
||||
ntfy_enabled: true
|
||||
|
||||
# Uncomment to enable the ntfy web app (disabled by default)
|
||||
# ntfy_web_root: app # defaults to "disable"
|
||||
|
||||
# Uncomment and change to inject additional configuration options.
|
||||
# ntfy_configuration_extension_yaml: |
|
||||
# log_level: DEBUG
|
||||
########################################################################
|
||||
# #
|
||||
# /ntfy #
|
||||
# #
|
||||
########################################################################
|
||||
```
|
||||
|
||||
For a more complete list of variables that you could override, see the [`defaults/main.yml` file](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/defaults/main.yml) of the ntfy Ansible role.
|
||||
As the most of the necessary settings for the role have been taken care of by the playbook, you can enable the ntfy server on your Matrix server with this minimum configuration.
|
||||
|
||||
For a complete list of ntfy config options that you could put in `ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
|
||||
See the role's documentation for details about configuring ntfy per your preference (such as [setting access control with authentication](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#enable-access-control-with-authentication-optional)).
|
||||
|
||||
### Adjusting the ntfy URL (optional)
|
||||
|
||||
@@ -47,6 +86,20 @@ ntfy_hostname: push.example.com
|
||||
|
||||
After changing the domain, **you may need to adjust your DNS** records to point the ntfy domain to the Matrix server.
|
||||
|
||||
### Enable web app (optional)
|
||||
|
||||
The ntfy server can be accessed via its web app where you can subscribe to and push to "topics" from the browser. The web app may be helpful to troubleshoot notification issues or to use ntfy for other purposes than getting ntfy send UnifiedPush notifications to your Matrix-related services.
|
||||
|
||||
**Note**: subscribing to a topic is not necessary for using the nfty server as the Push Server for UnifiedPush.
|
||||
|
||||
To enable the web app, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
ntfy_web_root: app
|
||||
```
|
||||
|
||||
See [the official documentation](https://docs.ntfy.sh/subscribe/web/) for details about how to use it.
|
||||
|
||||
## 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:
|
||||
@@ -62,59 +115,47 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
|
||||
## Usage
|
||||
|
||||
To make use of your ntfy installation, on Android for example, you need two things:
|
||||
To receive push notifications with UnifiedPush from the ntfy server, you need to **install [the ntfy Android app](https://docs.ntfy.sh/subscribe/phone/)** which works as the Distrubutor, **log in to the account on the ntfy app** if you have enabled the access control, and then **configure a UnifiedPush-compatible Matrix client**. After setting up the ntfy Android app, the Matrix client listens to it, and push notitications are "distributed" from it.
|
||||
|
||||
* the `ntfy` app
|
||||
* a UnifiedPush-compatible Matrix app
|
||||
For details about installing and configuring the ntfy Android app, take a look at [this section](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#install-the-ntfy-androidios-app) on the role's documentation.
|
||||
|
||||
You need to install the `ntfy` app on each device on which you want to receive push notifications through your ntfy server. The `ntfy` app will provide UnifiedPush notifications to any number of UnifiedPush-compatible messaging apps installed on the same device.
|
||||
⚠️ Though the ntfy app is available for iOS ([App Store](https://apps.apple.com/us/app/ntfy/id1625396347); the app's source code can be retrieved from [here](https://github.com/binwiederhier/ntfy-ios)), **any Matrix clients for iOS currently do not support ntfy** due to [technical limitations of the iOS platform](https://github.com/binwiederhier/ntfy-ios/blob/main/docs/TECHNICAL_LIMITATIONS.md). If you develop your own Matrix client app for iOS, you may need to use the [Sygnal](configuring-playbook-sygnal.md) push gateway service to deliver push notifications to it.
|
||||
|
||||
### Setting up the `ntfy` Android app
|
||||
### Setting up a UnifiedPush-compatible Matrix client
|
||||
|
||||
1. Install the [ntfy Android app](https://ntfy.sh/docs/subscribe/phone/) from F-droid or Google Play.
|
||||
2. In its Settings -> `General: Default server`, enter your ntfy server URL, such as `https://ntfy.example.com`.
|
||||
3. In its Settings -> `Advanced: Connection protocol`, choose `WebSockets`.
|
||||
Having configured the ntfy Android app, you can configure a UnifiedPush-compatible Matrix client on the same device.
|
||||
|
||||
That is all you need to do in the ntfy app. It has many other features, but for our purposes you can ignore them. In particular you do not need to follow any instructions about subscribing to a notification topic as UnifiedPush will do that automatically.
|
||||
Steps needed for specific Matrix clients:
|
||||
|
||||
### Setting up a UnifiedPush-compatible Matrix app
|
||||
* FluffyChat-Android: this should auto-detect and use the app. No manual settings required.
|
||||
|
||||
Install any UnifiedPush-enabled Matrix app on that same device. The Matrix app will learn from the `ntfy` app that you have configured UnifiedPush on this device, and then it will tell your Matrix server to use it.
|
||||
|
||||
Steps needed for specific Matrix apps:
|
||||
|
||||
* FluffyChat-android:
|
||||
- Should auto-detect and use it. No manual settings.
|
||||
|
||||
* SchildiChat-android:
|
||||
* SchildiChat-Android:
|
||||
1. enable `Settings` -> `Notifications` -> `UnifiedPush: Force custom push gateway`.
|
||||
2. choose `Settings` -> `Notifications` -> `UnifiedPush: Re-register push distributor`. *(For info, a more complex alternative to achieve the same is: delete the relevant unifiedpush registration in `ntfy` app, force-close SchildiChat, re-open it.)*
|
||||
2. choose `Settings` -> `Notifications` -> `UnifiedPush: Re-register push distributor`. *(For info, a more complex alternative to achieve the same is: delete the relevant unifiedpush registration in the ntfy Android app, force-close SchildiChat, re-open it.)*
|
||||
3. verify `Settings` -> `Notifications` -> `UnifiedPush: Notification targets` as described below in the "Troubleshooting" section.
|
||||
|
||||
* Element-android v1.4.26+:
|
||||
* Element-Android v1.4.26+:
|
||||
1. choose `Settings` -> `Notifications` -> `Notification method` -> `ntfy`
|
||||
2. verify `Settings` -> `Troubleshoot` -> `Troubleshoot notification settings`
|
||||
|
||||
If the Matrix app asks, "Choose a distributor: FCM Fallback or ntfy", then choose "ntfy".
|
||||
If the Matrix client asks, "Choose a distributor: FCM Fallback or ntfy", then choose "ntfy".
|
||||
|
||||
If the Matrix app doesn't seem to pick it up, try restarting it and try the Troubleshooting section below.
|
||||
|
||||
### Web App
|
||||
|
||||
ntfy also has a web app to subscribe to and push to topics from the browser. This may be helpful to further troubleshoot UnifiedPush problems or to use ntfy for other purposes. The web app only runs in the browser locally (after downloading the JavaScript).
|
||||
|
||||
The web app is disabled in this playbook by default as the expectation is that most users won't use it. You can either use the [official hosted one](https://ntfy.sh/app) (it supports using other public reachable ntfy instances) or host it yourself by setting `ntfy_web_root: "app"` and re-running Ansible.
|
||||
If the Matrix client doesn't seem to pick it up, try restarting it and try the Troubleshooting section below.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
First check that the Matrix client app you are using supports UnifiedPush. There may well be different variants of the app.
|
||||
The simple [UnifiedPush troubleshooting](https://unifiedpush.org/users/troubleshooting/) app [UP-Example](https://f-droid.org/en/packages/org.unifiedpush.example/) can be used to manually test UnifiedPush registration and operation on an Android device.
|
||||
|
||||
Set the ntfy server's log level to 'DEBUG', as shown in the example settings above, and watch the server's logs with `sudo journalctl -fu matrix-ntfy`.
|
||||
### Check the Matrix client
|
||||
|
||||
To check if UnifiedPush is correctly configured on the client device, look at "Settings -> Notifications -> Notification Targets" in Element Android or SchildiChat Android, or "Settings -> Notifications -> Devices" in FluffyChat. There should be one entry for each Matrix client app that has enabled push notifications, and when that client is using UnifiedPush you should see a URL that begins with your ntfy server's URL.
|
||||
Make sure that the Matrix client you are using supports UnifiedPush. There may well be different variants of the app.
|
||||
|
||||
To check if UnifiedPush is correctly configured on the client device, look at "Settings -> Notifications -> Notification Targets" in Element Android or SchildiChat Android, or "Settings -> Notifications -> Devices" in FluffyChat. There should be one entry for each Matrix client that has enabled push notifications, and when that client is using UnifiedPush you should see a URL that begins with your ntfy server's URL.
|
||||
|
||||
In the "Notification Targets" screen in Element Android or SchildiChat Android, two relevant URLs are shown, "push\_key" and "Url", and both should begin with your ntfy server's URL. If "push\_key" shows your server but "Url" shows an external server such as `up.schildi.chat` then push notifications will still work but are being routed through that external server before they reach your ntfy server. To rectify that, in SchildiChat (at least around version 1.4.20.sc55) you must enable the `Force custom push gateway` setting as described in the "Usage" section above.
|
||||
|
||||
If it is not working, useful tools are "Settings -> Notifications -> Re-register push distributor" and "Settings -> Notifications -> Troubleshoot Notifications" in SchildiChat Android (possibly also Element Android). In particular the "Endpoint/FCM" step of that troubleshooter should display your ntfy server's URL that it has discovered from the ntfy client app.
|
||||
|
||||
The simple [UnifiedPush troubleshooting](https://unifiedpush.org/users/troubleshooting/) app [UP-Example](https://f-droid.org/en/packages/org.unifiedpush.example/) can be used to manually test UnifiedPush registration and operation on an Android device.
|
||||
### Check the service's logs
|
||||
|
||||
See [this section](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#check-the-services-logs) on the role's documentation for details.
|
||||
|
||||
@@ -1,3 +1,21 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2018 - 2025 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2019 - 2024 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2020 - 2021 Agustin Ferrario
|
||||
SPDX-FileCopyrightText: 2020 Eneko Nieto
|
||||
SPDX-FileCopyrightText: 2020 Julian Foad
|
||||
SPDX-FileCopyrightText: 2020 Tomas Strand
|
||||
SPDX-FileCopyrightText: 2021 Aaron Raimist
|
||||
SPDX-FileCopyrightText: 2021 Colin Shea
|
||||
SPDX-FileCopyrightText: 2022 François Darveau
|
||||
SPDX-FileCopyrightText: 2022 Jaden Down
|
||||
SPDX-FileCopyrightText: 2023 - 2024 Jost Alemann
|
||||
SPDX-FileCopyrightText: 2023 Tilo Spannagel
|
||||
SPDX-FileCopyrightText: 2024 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Using your own webserver, instead of this playbook's Traefik reverse-proxy (optional, advanced)
|
||||
|
||||
By default, this playbook installs its own [Traefik](https://traefik.io/) reverse-proxy server (in a Docker container) which listens on ports 80 and 443. If that's okay, you can skip this document.
|
||||
@@ -8,7 +26,7 @@ By default, this playbook installs its own [Traefik](https://traefik.io/) revers
|
||||
|
||||
- serving public traffic and providing SSL-termination with certificates obtained from [Let's Encrypt](https://letsencrypt.org/). See [Adjusting SSL certificate retrieval](./configuring-playbook-ssl-certificates.md).
|
||||
|
||||
- assists internal communication between addon services (briges, bots, etc.) and the homeserver via an internal entrypoint (`matrix-internal-matrix-client-api`).
|
||||
- assists internal communication between addon services (bridges, bots, etc.) and the homeserver via an internal entrypoint (`matrix-internal-matrix-client-api`).
|
||||
|
||||
There are 2 ways to use Traefik with this playbook, as described below.
|
||||
|
||||
@@ -18,8 +36,6 @@ To have the playbook install and use Traefik, add the following configuration to
|
||||
|
||||
```yaml
|
||||
matrix_playbook_reverse_proxy_type: playbook-managed-traefik
|
||||
|
||||
traefik_config_certificatesResolvers_acme_email: YOUR_EMAIL_ADDRESS
|
||||
```
|
||||
|
||||
Traefik will manage SSL certificates for all services seamlessly.
|
||||
@@ -56,10 +72,10 @@ By default, the playbook configured a `default` certificate resolver and multipl
|
||||
|
||||
You need to configure 4 entrypoints for your Traefik server:
|
||||
|
||||
- `web` (TCP port `80`) - used for redirecting to HTTPS (`web-secure`)
|
||||
- `web-secure` (TCP port `443`) - used for exposing the Matrix Client-Server API and all other services
|
||||
- `matrix-federation` (TCP port `8448`) - used for exposing the Matrix Federation API
|
||||
- `matrix-internal-matrix-client-api` (TCP port `8008`) - used internally for addon services (bridges, bots) to communicate with the homserver
|
||||
- `web` (TCP port `80`) — used for redirecting to HTTPS (`web-secure`)
|
||||
- `web-secure` (TCP port `443`) — used for exposing the Matrix Client-Server API and all other services
|
||||
- `matrix-federation` (TCP port `8448`) — used for exposing the Matrix Federation API
|
||||
- `matrix-internal-matrix-client-api` (TCP port `8008`) — used internally for addon services (bridges, bots) to communicate with the homserver
|
||||
|
||||
Below is some configuration for running Traefik yourself, although we recommend using [Traefik managed by the playbook](#traefik-managed-by-the-playbook).
|
||||
|
||||
@@ -127,7 +143,7 @@ Doing this is possible, but requires manual work.
|
||||
|
||||
There are 2 ways to go about it:
|
||||
|
||||
- (recommended) [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) - using the playbook-managed reverse-proxy (Traefik), but disabling SSL termination for it, exposing this reverse-proxy on a few local ports (e.g. `127.0.0.1:81`, etc.) and forwarding traffic from your own webserver to those few ports
|
||||
- (recommended) [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) — using the playbook-managed reverse-proxy (Traefik), but disabling SSL termination for it, exposing this reverse-proxy on a few local ports (e.g. `127.0.0.1:81`, etc.) and forwarding traffic from your own webserver to those few ports
|
||||
|
||||
- (difficult) [Using no reverse-proxy on the Matrix side at all](#using-no-reverse-proxy-on-the-matrix-side-at-all) disabling the playbook-managed reverse-proxy (Traefik), exposing services one by one using `_host_bind_port` variables and forwarding traffic from your own webserver to those ports
|
||||
|
||||
@@ -201,7 +217,7 @@ To put it another way:
|
||||
|
||||
### Using no reverse-proxy on the Matrix side at all
|
||||
|
||||
Instead of [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy), you can also go another way -- completely disabling the playbook-managed Traefik reverse-proxy. You would then need to reverse-proxy from your own webserver directly to each individual Matrix service.
|
||||
Instead of [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy), you can also go another way — completely disabling the playbook-managed Traefik reverse-proxy. You would then need to reverse-proxy from your own webserver directly to each individual Matrix service.
|
||||
|
||||
This is more difficult, as you would need to handle the configuration for each service manually. Enabling additional services would come with extra manual work you need to do.
|
||||
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
SPDX-FileCopyrightText: 2024 Slavi Pantaleev
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up Pantalaimon (E2EE aware proxy daemon) (optional)
|
||||
|
||||
The playbook can install and configure the [pantalaimon](https://github.com/matrix-org/pantalaimon) E2EE aware proxy daemon for you.
|
||||
@@ -14,7 +21,13 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
|
||||
matrix_pantalaimon_enabled: true
|
||||
```
|
||||
|
||||
The default configuration should suffice. For advanced configuration, you can override the variables documented in the role's [defaults](../roles/custom/matrix-pantalaimon/defaults/main.yml).
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-pantalaimon/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_pantalaimon_configuration` variable
|
||||
|
||||
## Installing
|
||||
|
||||
@@ -28,3 +41,14 @@ 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-pantalaimon`.
|
||||
|
||||
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: Error, Warning, Info, Debug
|
||||
matrix_pantalaimon_log_level: Debug
|
||||
```
|
||||
|
||||
@@ -1,38 +1,17 @@
|
||||
# Setting up postgres backup (optional)
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2021 foxcris
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you via the [ansible-role-postgres-backup](https://github.com/mother-of-all-self-hosting/ansible-role-postgres-backup) Ansible role.
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
For a more complete backup solution (one that includes not only Postgres, but also other configuration/data files), you may wish to look into [BorgBackup](configuring-playbook-backup-borg.md) instead.
|
||||
# Setting up Postgres backup (optional)
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you.
|
||||
|
||||
To enable Postgres backup, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
The [Ansible role for docker-postgres-backup-local](https://github.com/mother-of-all-self-hosting/ansible-role-postgres-backup) 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 docker-postgres-backup-local, you can check them via:
|
||||
- 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-postgres-backup/blob/main/docs/configuring-postgres-backup.md) online
|
||||
- 📁 `roles/galaxy/postgres_backup/docs/configuring-postgres-backup.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
|
||||
|
||||
```yaml
|
||||
postgres_backup_enabled: true
|
||||
```
|
||||
|
||||
Refer to the table below for additional configuration variables and their default values.
|
||||
|
||||
| Name | Default value | Description |
|
||||
| :-------------------------------- | :--------------------------- | :--------------------------------------------------------------- |
|
||||
|`postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
|
||||
|`postgres_backup_schedule`| `'@daily'` |Cron-schedule specifying the interval between postgres backups.|
|
||||
|`postgres_backup_keep_days`|`7`|Number of daily backups to keep|
|
||||
|`postgres_backup_keep_weeks`|`4`|Number of weekly backups to keep|
|
||||
|`postgres_backup_keep_months`|`12`|Number of monthly backups to keep|
|
||||
|`postgres_backup_base_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Base path for postgres-backup. Also see `postgres_backup_data_path` |
|
||||
|`postgres_backup_data_path` | `"{{ postgres_backup_base_path }}/data"` | Storage path for postgres-backup database backups |
|
||||
|
||||
## 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.
|
||||
**Note**: for a more complete backup solution (one that includes not only Postgres, but also other configuration/data files), you may wish to look into [BorgBackup](configuring-playbook-backup-borg.md) instead.
|
||||
|
||||
@@ -1,6 +1,24 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2021 - 2024 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2021 Aaron Raimist
|
||||
SPDX-FileCopyrightText: 2021 Kim Brose
|
||||
SPDX-FileCopyrightText: 2021 Luca Di Carlo
|
||||
SPDX-FileCopyrightText: 2022 Olivér Falvai
|
||||
SPDX-FileCopyrightText: 2023 Michael Hollister
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server (optional)
|
||||
|
||||
The playbook can install [Grafana](https://grafana.com/) with [Prometheus](https://prometheus.io/) and configure performance metrics of your homeserver with graphs for you.
|
||||
The playbook can install [Prometheus](https://prometheus.io/) with [Grafana](https://grafana.com/) and configure performance metrics of your homeserver with graphs for you.
|
||||
|
||||
> [!WARNING]
|
||||
> Metrics and graphs contain a lot of information, and anyone who has access to them can make an educated guess about your server usage patterns. This especially applies to small personal/family scale homeservers, where the number of samples is fairly limited. Analyzing the metrics over time, one might be able to figure out your life cycle, such as when you wake up, go to bed, etc. Before enabling (anonymous) access, you should carefully evaluate the risk, and if you do enable it, it is highly recommended to change your Grafana password from the default one.
|
||||
>
|
||||
> Most of our Docker containers run with limited system access, but the `prometheus-node-exporter` can access the host network stack and (readonly) root filesystem. If it is fine, you can enable it and have it capture metrics about them (see [below](#enable-metrics-and-graphs-for-generic-system-information-optional) for the instruction). Even if `prometheus-node-exporter` is not enabled, you will still get Synapse homeserver metrics. Note that both of these dashboards are always be enabled, so you can still see historical data even after disabling either source.
|
||||
|
||||
## Adjusting DNS records
|
||||
|
||||
@@ -8,35 +26,111 @@ By default, this playbook installs Grafana web user-interface on the `stats.` su
|
||||
|
||||
When setting, replace `example.com` with your own.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
**Note**: It is possible to install Prometheus without installing Grafana. In this case it is not required to create the CNAME record.
|
||||
|
||||
To enable Grafana and/or Prometheus, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
## Adjusting the playbook configuration — Prometheus
|
||||
|
||||
Prometheus is an open-source systems monitoring and alerting toolkit. It is a time series database, which holds all the data we're going to talk about.
|
||||
|
||||
To enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
prometheus_enabled: true
|
||||
|
||||
# You can remove this, if unnecessary.
|
||||
prometheus_node_exporter_enabled: true
|
||||
|
||||
# You can remove this, if unnecessary.
|
||||
prometheus_postgres_exporter_enabled: true
|
||||
|
||||
# You can remove this, if unnecessary.
|
||||
matrix_prometheus_nginxlog_exporter_enabled: true
|
||||
|
||||
grafana_enabled: true
|
||||
|
||||
grafana_anonymous_access: false
|
||||
|
||||
# This has no relation to your Matrix user ID. It can be any username you'd like.
|
||||
# Changing the username subsequently won't work.
|
||||
grafana_default_admin_user: "some_username_chosen_by_you"
|
||||
|
||||
# Changing the password subsequently won't work.
|
||||
grafana_default_admin_password: "some_strong_password_chosen_by_you"
|
||||
```
|
||||
|
||||
The retention policy of Prometheus metrics is [15 days by default](https://prometheus.io/docs/prometheus/latest/storage/#operational-aspects). Older data gets deleted automatically.
|
||||
**Note**: the retention policy of Prometheus metrics is [15 days by default](https://prometheus.io/docs/prometheus/latest/storage/#operational-aspects). Older data gets deleted automatically.
|
||||
|
||||
### Enable metrics and graphs for generic system information (optional)
|
||||
|
||||
You can enable the [Node Exporter](https://prometheus.io/docs/guides/node-exporter/), an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures.
|
||||
|
||||
To enable it, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
prometheus_node_exporter_enabled: true
|
||||
```
|
||||
|
||||
### Enable metrics and graphs for Postgres (optional)
|
||||
|
||||
Expanding on the metrics exposed by the Synapse exporter and the Node exporter, the playbook can also install and configure the [PostgreSQL Server Exporter](https://github.com/prometheus-community/postgres_exporter) that exposes more detailed information about what's happening on your Postgres database.
|
||||
|
||||
Enabling the exporter sets up the docker container, connects it to the database and adds a 'job' to the Prometheus config which tells Prometheus about this new exporter.
|
||||
|
||||
To enable it, add the following configuration to your `vars.yml` file:
|
||||
|
||||
**Note**: `prometheus_postgres_exporter_database_username` has nothing to do with your Matrix user ID. It can be any string you'd like.
|
||||
|
||||
```yaml
|
||||
prometheus_postgres_exporter_enabled: true
|
||||
|
||||
# The username for the user that the exporter uses to connect to the database.
|
||||
# Uncomment and adjust this part if you'd like to use a username different than the default.
|
||||
# prometheus_postgres_exporter_database_username: "matrix_prometheus_postgres_exporter"
|
||||
|
||||
# The password for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook.
|
||||
# Uncomment and adjust this part if you'd like to set the password by yourself.
|
||||
# prometheus_postgres_exporter_database_password: "PASSWORD_HERE"
|
||||
```
|
||||
|
||||
### Enable metrics and graphs for nginx logs (optional)
|
||||
|
||||
The playbook can also install and configure the [prometheus-nginxlog-exporter](https://github.com/martin-helmich/prometheus-nginxlog-exporter/) service for you.
|
||||
|
||||
It is an addon of sorts to expose nginx logs to Prometheus. The exporter will collect access logs from various nginx reverse-proxies which may be used internally (e.g. `matrix-synapse-reverse-proxy-companion`, if Synapse workers are enabled) and will make them available at a Prometheus-compatible `/metrics` endpoint.
|
||||
|
||||
See the project's [documentation](https://github.com/martin-helmich/prometheus-nginxlog-exporter/blob/master/README.adoc) to learn what it does and why it might be useful to you.
|
||||
|
||||
To enable it, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_prometheus_nginxlog_exporter_enabled: true
|
||||
```
|
||||
|
||||
If you enable Grafana, a dedicated `NGINX PROXY` Grafana dashboard will be created.
|
||||
|
||||
**Note**: nginx is only used internally by this Ansible playbook. With Traefik being our default reverse-proxy, collecting nginx metrics is less relevant.
|
||||
|
||||
#### Docker image compatibility (optional)
|
||||
|
||||
At the moment of writing only images for `amd64` and `arm64` architectures are available. The playbook currently does not support [self-building](./self-building.md) a container image on other architectures. You can however use a custom-build image by setting:
|
||||
|
||||
```yaml
|
||||
matrix_prometheus_nginxlog_exporter_docker_image_arch_check_enabled: false
|
||||
matrix_prometheus_nginxlog_exporter_docker_image: path/to/docker/image:tag
|
||||
```
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about Prometheus and its add-on.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- [Prometheus role](https://github.com/mother-of-all-self-hosting/ansible-role-prometheus)'s [`defaults/main.yml`](https://github.com/mother-of-all-self-hosting/ansible-role-prometheus/blob/main/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 `prometheus_configuration_extension_yaml` variable
|
||||
- `roles/custom/matrix-prometheus-nginxlog-exporter/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
|
||||
## Adjusting the playbook configuration — Grafana
|
||||
|
||||
Grafana is an open source visualization and analytics software. To enable it, add the following configuration to your `vars.yml` file. Make sure to replace `USERNAME_HERE` and `PASSWORD_HERE`.
|
||||
|
||||
**Notes**:
|
||||
- `grafana_default_admin_user` has nothing to do with your Matrix user ID. It can be any string you'd like.
|
||||
- Changing the username/password subsequently won't work.
|
||||
|
||||
```yaml
|
||||
grafana_enabled: true
|
||||
|
||||
grafana_default_admin_user: "USERNAME_HERE"
|
||||
grafana_default_admin_password: "PASSWORD_HERE"
|
||||
|
||||
# Uncomment to allow viewing Grafana without logging in.
|
||||
# grafana_anonymous_access: true
|
||||
```
|
||||
|
||||
Name | Description
|
||||
-----|----------
|
||||
`grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.example.com` subdomain) the dashboards with the graphs that we're interested in.
|
||||
`grafana_default_admin_user`<br>`grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. You are asked to change the credentials on first login. If you feel this is insecure and you want to change them beforehand, you can do that here.
|
||||
`grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
|
||||
|
||||
### Adjusting the Grafana URL (optional)
|
||||
|
||||
@@ -51,8 +145,6 @@ grafana_hostname: grafana.example.com
|
||||
|
||||
After changing the domain, **you may need to adjust your DNS** records to point the Grafana domain to the Matrix server.
|
||||
|
||||
**Note**: It is possible to install Prometheus without installing Grafana. This case it is not required to create the CNAME record.
|
||||
|
||||
## 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:
|
||||
@@ -66,54 +158,57 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
|
||||
`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.
|
||||
|
||||
## What does it do?
|
||||
|
||||
Name | Description
|
||||
-----|----------
|
||||
`prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
|
||||
`prometheus_node_exporter_enabled`|[Node Exporter](https://prometheus.io/docs/guides/node-exporter/) is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
|
||||
`prometheus_postgres_exporter_enabled`|[Postgres Exporter](configuring-playbook-prometheus-postgres.md) is an addon of sorts to expose Postgres database metrics to Prometheus.
|
||||
`matrix_prometheus_nginxlog_exporter_enabled`|[NGINX Log Exporter](configuring-playbook-prometheus-nginxlog.md) is an addon of sorts to expose NGINX logs to Prometheus.
|
||||
`grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.example.com` subdomain) the dashboards with the graphs that we're interested in
|
||||
`grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
|
||||
`grafana_default_admin_user`<br>`grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
|
||||
|
||||
## Security and privacy
|
||||
|
||||
Metrics and resulting graphs can contain a lot of information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
|
||||
|
||||
Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
|
||||
|
||||
## Collecting metrics to an external Prometheus server
|
||||
|
||||
**If the integrated Prometheus server is enabled** (`prometheus_enabled: true`), metrics are collected by it from each service via communication that happens over the container network. Each service does not need to expose its metrics "publicly".
|
||||
|
||||
When you'd like **to collect metrics from an external Prometheus server**, you need to expose service metrics outside of the container network.
|
||||
|
||||
The playbook provides a single endpoint (`https://matrix.example.com/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/hookshot`, etc). To expose all services on this `/metrics/*` feature, use `matrix_metrics_exposure_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` below.
|
||||
The playbook provides a single endpoint (`https://matrix.example.com/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/nginxlog`, `/metrics/hookshot`, etc).
|
||||
|
||||
When using `matrix_metrics_exposure_enabled`, you don't need to expose metrics for individual services one by one.
|
||||
To expose all services on this `/metrics/*` feature, you can use `matrix_metrics_exposure_enabled`. When using it, you don't need to expose metrics for individual services one by one. If you think this is too much, refer [this section](#expose-metrics-of-other-services-roles) for details about exposing metrics on a per-service basis.
|
||||
|
||||
To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), you can use `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`. When enabled, all endpoints beneath `/metrics` will be protected with the same credentials. Alternatively, you can protect each endpoint with dedicated credentials. Refer [the section](#expose-metrics-of-other-services-roles) below for details about it.
|
||||
|
||||
The following variables may be of interest:
|
||||
|
||||
Name | Description
|
||||
-----|----------
|
||||
`matrix_metrics_exposure_enabled`|Set this to `true` to **enable metrics exposure for all services** on `https://matrix.example.com/metrics/*`. If you think this is too much, refer to the helpful (but nonexhaustive) list of individual `matrix_SERVICE_metrics_proxying_enabled` (or similar) variables below for exposing metrics on a per-service basis.
|
||||
`matrix_metrics_exposure_http_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.example.com/metrics/*` endpoints with [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) (see the other variables below for supplying the actual credentials). When enabled, all endpoints beneath `/metrics` will be protected with the same credentials
|
||||
`matrix_metrics_exposure_enabled`|Set this to `true` to **enable metrics exposure for all services** on `https://matrix.example.com/metrics/*`.
|
||||
`matrix_metrics_exposure_http_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.example.com/metrics/*` endpoints with [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) (see the other variables below for supplying the actual credentials).
|
||||
`matrix_metrics_exposure_http_basic_auth_users`|Set this to the Basic Authentication credentials (raw `htpasswd` file content) used to protect `/metrics/*`. This htpasswd-file needs to be generated with the `htpasswd` tool and can include multiple username/password pairs.
|
||||
`matrix_synapse_metrics_enabled`|Set this to `true` to make Synapse expose metrics (locally, on the container network)
|
||||
`matrix_synapse_metrics_proxying_enabled`|Set this to `true` to expose Synapse's metrics on `https://matrix.example.com/metrics/synapse/main-process` and `https://matrix.example.com/metrics/synapse/worker/TYPE-ID`. Read [below](#collecting-synapse-worker-metrics-to-an-external-prometheus-server) if you're running a Synapse worker setup (`matrix_synapse_workers_enabled: true`). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
|
||||
`prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network)
|
||||
`prometheus_node_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.example.com/metrics/node-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
|
||||
`prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](configuring-playbook-prometheus-postgres.md) (locally, on the container network)
|
||||
`prometheus_postgres_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.example.com/metrics/postgres-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
|
||||
`matrix_prometheus_nginxlog_exporter_enabled`|Set this to `true` to enable the [NGINX Log exporter](configuring-playbook-prometheus-nginxlog.md) (locally, on the container network)
|
||||
`matrix_sliding_sync_metrics_enabled`|Set this to `true` to make [Sliding Sync](configuring-playbook-sliding-sync-proxy.md) expose metrics (locally, on the container network)
|
||||
`matrix_sliding_sync_metrics_proxying_enabled`|Set this to `true` to expose the [Sliding Sync](configuring-playbook-sliding-sync-proxy.md) metrics on `https://matrix.example.com/metrics/sliding-sync`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
|
||||
`matrix_bridge_hookshot_metrics_enabled`|Set this to `true` to make [Hookshot](configuring-playbook-bridge-hookshot.md) expose metrics (locally, on the container network)
|
||||
`matrix_bridge_hookshot_metrics_proxying_enabled`|Set this to `true` to expose the [Hookshot](configuring-playbook-bridge-hookshot.md) metrics on `https://matrix.example.com/metrics/hookshot`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
|
||||
`matrix_SERVICE_metrics_proxying_enabled`|Various other services/roles may provide similar `_metrics_enabled` and `_metrics_proxying_enabled` variables for exposing their metrics. Refer to each role for details. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above or `matrix_SERVICE_container_labels_metrics_middleware_basic_auth_enabled`/`matrix_SERVICE_container_labels_metrics_middleware_basic_auth_users` variables provided by each role.
|
||||
`matrix_media_repo_metrics_enabled`|Set this to `true` to make media-repo expose metrics (locally, on the container network)
|
||||
`prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network).
|
||||
`prometheus_node_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.example.com/metrics/node-exporter`.
|
||||
`prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](#enable-metrics-and-graphs-for-postgres-optional) (locally, on the container network).
|
||||
`prometheus_postgres_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the [Postgres exporter](#enable-metrics-and-graphs-for-postgres-optional) metrics on `https://matrix.example.com/metrics/postgres-exporter`.
|
||||
`matrix_prometheus_nginxlog_exporter_enabled`|Set this to `true` to enable the [nginx Log exporter](#enable-metrics-and-graphs-for-nginx-logs-optional) (locally, on the container network).
|
||||
`matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [nginx Log exporter](#enable-metrics-and-graphs-for-nginx-logs-optional) metrics on `https://matrix.example.com/metrics/nginxlog`.
|
||||
|
||||
### Expose metrics of other services/roles
|
||||
|
||||
Various other services/roles may provide similar `_metrics_enabled` and `_metrics_proxying_enabled` variables for exposing their metrics. Refer to each role for details.
|
||||
|
||||
To password-protect the metrics of a specific role, you can use `matrix_SERVICE_container_labels_metrics_middleware_basic_auth_enabled` and `matrix_SERVICE_container_labels_metrics_middleware_basic_auth_users` variables provided by the role.
|
||||
|
||||
**Note**: alternatively you can use `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` in order to password-protect the metrics of all services.
|
||||
|
||||
For example, you can enable and expose metrics for Synapse protecting them with dedicated credentials by adding the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
# Expose metrics (locally, on the container network).
|
||||
matrix_synapse_metrics_enabled: true
|
||||
|
||||
# Uncomment to expose metrics on https://matrix.example.com/metrics/synapse/main-process and https://matrix.example.com/metrics/synapse/worker/TYPE-ID.
|
||||
# Read the section below ("Collecting Synapse worker metrics to an external Prometheus server") if you're running a Synapse worker setup by setting `matrix_synapse_workers_enabled` to true.
|
||||
# matrix_synapse_metrics_proxying_enabled: true
|
||||
|
||||
# Uncomment to password-protect the metrics for Synapse.
|
||||
# matrix_synapse_container_labels_public_metrics_middleware_basic_auth_enabled: true
|
||||
|
||||
# Uncomment and set this part to the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoints.
|
||||
# See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users
|
||||
# matrix_synapse_container_labels_public_metrics_middleware_basic_auth_users: ''
|
||||
```
|
||||
|
||||
### Collecting Synapse worker metrics to an external Prometheus server
|
||||
|
||||
@@ -147,6 +242,15 @@ scrape_configs:
|
||||
index: 18111
|
||||
```
|
||||
|
||||
## 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 the commands below:
|
||||
- `journalctl -fu matrix-prometheus` for Prometheus
|
||||
- `journalctl -fu matrix-prometheus-node-exporter` for Node Exporter
|
||||
- `journalctl -fu matrix-prometheus-postgres-exporter` for PostgreSQL Server Exporter
|
||||
- `journalctl -fu matrix-prometheus-nginxlog-exporter` for prometheus-nginxlog-exporter
|
||||
- `journalctl -fu matrix-grafana` for Grafana
|
||||
|
||||
## More information
|
||||
|
||||
- [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md)
|
||||
@@ -154,3 +258,4 @@ scrape_configs:
|
||||
- [The Prometheus scraping rules](https://github.com/element-hq/synapse/tree/master/contrib/prometheus) (we use v2)
|
||||
- [The Synapse Grafana dashboard](https://github.com/element-hq/synapse/tree/master/contrib/grafana)
|
||||
- [The Node Exporter dashboard](https://github.com/rfrail3/grafana-dashboards) (for generic non-synapse performance graphs)
|
||||
- [The PostgresSQL dashboard](https://grafana.com/grafana/dashboards/9628) (generic Postgres dashboard)
|
||||
|
||||
@@ -1,59 +0,0 @@
|
||||
# Enabling metrics and graphs for NginX logs (optional)
|
||||
|
||||
It can be useful to have some (visual) insight into [nginx](https://nginx.org/) logs.
|
||||
|
||||
This adds [prometheus-nginxlog-exporter](https://github.com/martin-helmich/prometheus-nginxlog-exporter/) to your Matrix deployment.
|
||||
|
||||
It will collect access logs from various nginx reverse-proxies which may be used internally (e.g. `matrix-synapse-reverse-proxy-companion`, if Synapse workers are enabled) and will make them available at a Prometheus-compatible `/metrics` endpoint.
|
||||
|
||||
**Note**: nginx is only used internally by this Ansible playbook. With Traefik being our default reverse-proxy, collecting nginx metrics is less relevant.
|
||||
|
||||
To make use of this, you need to install [Prometheus](./configuring-playbook-prometheus-grafana.md) either via the playbook or externally. When using an external Prometheus, configuration adjustments are necessary - see [Save metrics on an external Prometheus server](#save-metrics-on-an-external-prometheus-server).
|
||||
|
||||
If your setup includes [Grafana](./configuring-playbook-prometheus-grafana.md), a dedicated `NGINX PROXY` Grafana dashboard will be created.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_prometheus_nginxlog_exporter_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,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.
|
||||
|
||||
## Docker Image Compatibility
|
||||
|
||||
At the moment of writing only images for `amd64` and `arm64` architectures are available. The playbook currently does not support [self-building](./self-building.md) a container image on other architectures. You can however use a custom-build image by setting:
|
||||
|
||||
```yaml
|
||||
matrix_prometheus_nginxlog_exporter_docker_image_arch_check_enabled: false
|
||||
matrix_prometheus_nginxlog_exporter_docker_image: path/to/docker/image:tag
|
||||
```
|
||||
|
||||
## Security and privacy
|
||||
|
||||
Metrics and resulting graphs can contain a lot of information. NginX logs contain information like IP address, URLs, UserAgents and more. This information can reveal usage patterns and could be considered Personally Identifiable Information (PII). Think about this before enabling (anonymous) access. Please make sure you change the default Grafana password.
|
||||
|
||||
## Save metrics on an external Prometheus server
|
||||
|
||||
The playbook will automatically integrate the metrics into the [Prometheus](./configuring-playbook-prometheus-grafana.md) server provided with this playbook (if enabled). In such cases, the metrics endpoint is not exposed publicly - it's only available on the container network.
|
||||
|
||||
When using an external Prometheus server, you'll need to expose metrics publicly. See [Collecting metrics to an external Prometheus server](./configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server).
|
||||
|
||||
You can either use `matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled: true` to expose just this one service, or `matrix_metrics_exposure_enabled: true` to expose all services.
|
||||
|
||||
Whichever way you go with, this service will expose its metrics endpoint **without password-protection** at `https://matrix.example.com/metrics/nginxlog` by default.
|
||||
|
||||
For password-protection, use (`matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`) or (`matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_enabled` and `matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_users`).
|
||||
@@ -1,37 +0,0 @@
|
||||
# Enabling metrics and graphs for Postgres (optional)
|
||||
|
||||
Expanding on the metrics exposed by the [synapse exporter and the node exporter](configuring-playbook-prometheus-grafana.md), the playbook enables the [postgres exporter](https://github.com/prometheus-community/postgres_exporter) that exposes more detailed information about what's happening on your postgres database.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable the postgres exporter, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
prometheus_postgres_exporter_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,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.
|
||||
|
||||
## What does it do?
|
||||
|
||||
Name | Description
|
||||
-----|----------
|
||||
`prometheus_postgres_exporter_enabled`|Enable the postgres prometheus exporter. This sets up the docker container, connects it to the database and adds a 'job' to the prometheus config which tells prometheus about this new exporter. The default is 'false'
|
||||
`prometheus_postgres_exporter_database_username`| The 'username' for the user that the exporter uses to connect to the database. The default is 'matrix_prometheus_postgres_exporter'
|
||||
`prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook
|
||||
`prometheus_postgres_exporter_container_labels_traefik_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.example.com/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` on that other documentation page.
|
||||
|
||||
## More information
|
||||
|
||||
- [The PostgresSQL dashboard](https://grafana.com/grafana/dashboards/9628) (generic postgres dashboard)
|
||||
@@ -1,3 +1,10 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2023 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up the rageshake bug report server (optional)
|
||||
|
||||
The playbook can install and configure the [rageshake](https://github.com/matrix-org/rageshake) bug report server for you.
|
||||
@@ -20,18 +27,6 @@ To enable rageshake, add the following configuration to your `inventory/host_var
|
||||
matrix_rageshake_enabled: true
|
||||
```
|
||||
|
||||
rageshake has various options which don't have dedicated Ansible variables. You can see the full list of options in the [`rageshake.sample.yaml` file](https://github.com/matrix-org/rageshake/blob/master/rageshake.sample.yaml).
|
||||
|
||||
To set these, you can make use of the `matrix_rageshake_configuration_extension_yaml` variable like this:
|
||||
|
||||
```yaml
|
||||
matrix_rageshake_configuration_extension_yaml: |
|
||||
github_token: secrettoken
|
||||
|
||||
github_project_mappings:
|
||||
my-app: octocat/HelloWorld
|
||||
```
|
||||
|
||||
### Adjusting the rageshake URL (optional)
|
||||
|
||||
By tweaking the `matrix_rageshake_hostname` and `matrix_rageshake_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
|
||||
@@ -51,6 +46,31 @@ After changing the domain, **you may need to adjust your DNS** records to point
|
||||
|
||||
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 server.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-rageshake/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
- `roles/custom/matrix-rageshake/templates/config.yaml.j2` for the server's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_rageshake_configuration_extension_yaml` variable
|
||||
|
||||
```yaml
|
||||
matrix_rageshake_configuration_extension_yaml: |
|
||||
# Your custom YAML configuration goes here.
|
||||
# This configuration extends the default starting configuration (`matrix_rageshake_configuration_extension_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_rageshake_configuration_extension_yaml`.
|
||||
|
||||
github_token: secrettoken
|
||||
|
||||
github_project_mappings:
|
||||
my-app: octocat/HelloWorld
|
||||
```
|
||||
|
||||
## 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,3 +87,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
## Usage
|
||||
|
||||
Refer to the project's [documentation](https://github.com/matrix-org/rageshake/blob/main/README.md) for available APIs, etc.
|
||||
|
||||
## 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-rageshake`.
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2018 - 2019 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2019 - 2020 Marcel Partap
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up the REST authentication password provider module (optional, advanced)
|
||||
|
||||
The playbook can install and configure [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) for you.
|
||||
@@ -16,9 +24,9 @@ matrix_synapse_ext_password_provider_rest_auth_registration_profile_name_autofil
|
||||
matrix_synapse_ext_password_provider_rest_auth_login_profile_name_autofill: false
|
||||
```
|
||||
|
||||
## 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**, feel free to disable it:
|
||||
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:
|
||||
|
||||
```yaml
|
||||
matrix_synapse_password_config_localdb_enabled: false
|
||||
@@ -36,3 +44,12 @@ 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
|
||||
|
||||
### Use ma1sd Identity Server for the backend (not recommended)
|
||||
|
||||
This module does not provide direct integration with any backend. For the backend you can use [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server, which can be configured with the playbook.
|
||||
|
||||
> [!WARNING]
|
||||
> We recommend not bothering with installing ma1sd as it has been unmaintained for years. If you wish to install it anyway, consult the [ma1sd Identity Server configuration](configuring-playbook-ma1sd.md).
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Configuring Riot-web (optional)
|
||||
|
||||
By default, this playbook **used to install** the [Riot-web](https://github.com/element-hq/riot-web) Matrix client web application.
|
||||
@@ -21,9 +29,9 @@ We used to set up Riot at the `riot.example.com` domain. The playbook now sets u
|
||||
|
||||
There are a few options for handling this:
|
||||
|
||||
- (**avoiding changes** - using the old `riot.example.com` domain and avoiding DNS changes) -- to keep using `riot.example.com` instead of `element.example.com`, override the domain at which the playbook serves Element Web: `matrix_server_fqn_element: "riot.{{ matrix_domain }}"`
|
||||
- (**avoiding changes** — using the old `riot.example.com` domain and avoiding DNS changes) — to keep using `riot.example.com` instead of `element.example.com`, override the domain at which the playbook serves Element Web: `matrix_server_fqn_element: "riot.{{ matrix_domain }}"`
|
||||
|
||||
- (**embracing changes** - using only `element.example.com`) - set up the `element.example.com` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.example.com` in this case.
|
||||
- (**embracing changes** — using only `element.example.com`) — set up the `element.example.com` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.example.com` in this case.
|
||||
|
||||
### Re-running the playbook
|
||||
|
||||
|
||||
@@ -1,12 +1,21 @@
|
||||
# Storing Matrix media files on Amazon S3 with Goofys (optional)
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2022 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service), you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
Another (and better performing) way to use S3 storage with Synapse is [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md).
|
||||
# Storing Synapse media files on Amazon S3 with Goofys (optional)
|
||||
|
||||
Using a Goofys-backed media store works, but performance may not be ideal. If possible, try to use a region which is close to your Matrix server.
|
||||
The playbook can install and configure [Goofys](https://github.com/kahing/goofys) for you.
|
||||
|
||||
If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.
|
||||
Goofys makes it possible to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service) object storage.
|
||||
|
||||
See the project's [documentation](https://github.com/kahing/goofys/blob/master/README.md) to learn what it does and why it might be useful to you.
|
||||
|
||||
**Note**: as performance of a Goofys-backed media store may not be ideal, you may wish to use [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) instead, another (and better performing) way to mount a S3 bucket for Synapse.
|
||||
|
||||
If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), you can refer our migration instructions below.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
@@ -124,3 +133,7 @@ After making the backup, follow one of the guides below for a migration path fro
|
||||
7. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
|
||||
|
||||
8. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
|
||||
|
||||
## 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-goofys`.
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2018 - 2023 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2023 Michael Hollister
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Storing Synapse media files on Amazon S3 or another compatible Object Storage (optional)
|
||||
|
||||
By default, this playbook configures your server to store Synapse's content repository (`media_store`) files on the local filesystem. If that's okay, you can skip this document.
|
||||
@@ -18,7 +26,7 @@ You can create [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible
|
||||
|
||||
Amazon S3, Backblaze B2, and Storj are pay-as-you with no minimum charges for storing too little data.
|
||||
|
||||
All these providers have different prices, with Storj appearing to be the cheapest (as of 2024-10, storage fee is $0.004 per GB/month, and egress fee is $0.007 per GB). Backblaze egress is free, but for only certain users for up to 3x the amount of data stored. Beyond that you will pay $0.01/GB of egress.
|
||||
All these providers have different prices, with Storj appearing to be the cheapest (as of 2024-10, storage fee is $0.004 per GB/month, and egress fee is $0.007 per GB; check actual pricing [here](https://storj.dev/dcs/pricing)). Backblaze egress is free, but for only certain users for up to 3x the amount of data stored. Beyond that you will pay $0.01/GB of egress.
|
||||
|
||||
Wasabi has a minimum charge of 1TB if you're storing less than 1TB, which becomes expensive if you need to store less data than that. Likewise, Digital Ocean Spaces has also a minimum charge of 250GB ($5/month as of 2022-10).
|
||||
|
||||
@@ -29,7 +37,7 @@ Here are some of the important aspects of choosing the right provider:
|
||||
- if a provider has a data region close to your Matrix server (if it's farther away, high latency may cause slowdowns)
|
||||
- if a provider's infrastructure such as data center is centralized or distributed
|
||||
- if a provider's price model is transparent (whether it includes hidden costs like minimum charge, minimum storage term, etc.)
|
||||
- if a provider has free or cheap egress fee (in case you need to get the data out often, for some reason) - likely not too important for the common use-case
|
||||
- if a provider has free or cheap egress fee (in case you need to get the data out often, for some reason) — likely not too important for the common use-case
|
||||
|
||||
## Bucket creation and Security Configuration
|
||||
|
||||
@@ -83,17 +91,15 @@ The `keyID` value is your **Access Key** and `applicationKey` is your **Secret K
|
||||
|
||||
For configuring [Goofys](configuring-playbook-s3-goofys.md) or [s3-synapse-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) you will need:
|
||||
|
||||
- **Endpoint URL** - this is the **Endpoint** value you saw above, but prefixed with `https://`
|
||||
|
||||
- **Region** - use the value you see in the Endpoint (e.g. `us-west-002`)
|
||||
|
||||
- **Storage Class** - use `STANDARD`. Backblaze B2 does not have different storage classes, so it doesn't make sense to use any other value.
|
||||
- **Endpoint URL** — this is the **Endpoint** value you saw above, but prefixed with `https://`
|
||||
- **Region** — use the value you see in the Endpoint (e.g. `us-west-002`)
|
||||
- **Storage Class** — use `STANDARD`. Backblaze B2 does not have different storage classes, so it doesn't make sense to use any other value.
|
||||
|
||||
## Other providers
|
||||
|
||||
For other S3-compatible providers, you may not need to configure security policies, etc. (just like for [Backblaze B2](#backblaze-b2)).
|
||||
For other S3-compatible providers, you most likely just need to create an S3 bucket and get some credentials (access key and secret key) for accessing the bucket in a read/write manner. You may not need to configure security policies, etc.
|
||||
|
||||
You most likely just need to create an S3 bucket and get some credentials (access key and secret key) for accessing the bucket in a read/write manner.
|
||||
For details about setting up a bucket at Storj, please see the instruction [here](https://storj.dev/dcs/getting-started) to get started.
|
||||
|
||||
## Setting up
|
||||
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2018 - 2020 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2020 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up the Shared Secret Auth password provider module (optional, advanced)
|
||||
|
||||
The playbook can install and configure [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) for you.
|
||||
@@ -15,9 +23,9 @@ matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true
|
||||
matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: YOUR_SHARED_SECRET_GOES_HERE
|
||||
```
|
||||
|
||||
## 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**, feel free to disable it:
|
||||
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:
|
||||
|
||||
```yaml
|
||||
matrix_synapse_password_config_localdb_enabled: false
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user