ansol/matrix-docker-ansible-deploy
7
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-01-20 01:47:10 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'master' into conduit

Browse Source
This commit is contained in:
Slavi Pantaleev 2022-08-09 10:46:03 +03:00 committed by GitHub
commit 04f224e634
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
559 changed files with 10081 additions and 4434 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
.config/ansible-lint.yml Normal file
View File

@ -0,0 +1,13 @@
---
use_default_rules: true
skip_list:
- unnamed-task
- no-handler
- no-jinja-nesting
- schema
- command-instead-of-shell
- role-name
offline: false

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

@ -7,10 +7,18 @@ on: # yamllint disable-line rule:truthy
jobs:
yamllint:
name: 🧹 yamllint
name: yamllint
runs-on: ubuntu-latest
steps:
- name: ⤵️ Check out configuration from GitHub
- name: Check out
uses: actions/checkout@v3
- name: 🚀 Run yamllint
uses: frenck/action-yamllint@v1.1.2
- name: Run yamllint
uses: frenck/action-yamllint@v1.2.0
ansible-lint:
name: ansible-lint
runs-on: ubuntu-latest
steps:
- name: Check out
uses: actions/checkout@v3
- name: Run ansible-lint
uses: ansible-community/ansible-lint-action@main

197
CHANGELOG.md
View File

@ -1,3 +1,200 @@
# 2022-07-29
## mautrix-discord support
Thanks to [MdotAmaan](https://github.com/MdotAmaan)'s efforts, the playbook now supports bridging to [Discord](https://discordapp.com/) via the [mautrix-discord](https://mau.dev/mautrix/discord) bridge. See our [Setting up Mautrix Discord bridging](docs/configuring-playbook-bridge-mautrix-discord.md) documentation page for getting started.
**Note**: this is a new Discord bridge. The playbook still retains Discord bridging via [matrix-appservice-discord](docs/configuring-playbook-bridge-appservice-discord.md) and [mx-puppet-discord](docs/configuring-playbook-bridge-mx-puppet-discord.md). You're free too use the bridge that serves you better, or even all three of them (for different users and use-cases).
# 2022-07-27
## matrix-appservice-kakaotalk support
The playbook now supports bridging to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) via [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) - a bridge based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code. Thanks to [hnarjis](https://github.com/hnarjis) for helping us add support for this!
See our [Setting up Appservice Kakaotalk bridging](docs/configuring-playbook-bridge-appservice-kakaotalk.md) documentation to get started.
# 2022-07-20
## maubot support
Thanks to [Stuart Mumford (@Cadair)](https://github.com/cadair) for starting ([PR #373](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/373) and [PR #622](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/622)) and to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s) for finishing up (in [PR #1894](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1894)), the playbook can now help you set up [maubot](https://github.com/maubot/maubot) - a plugin-based Matrix bot system.
See our [Setting up maubot](docs/configuring-playbook-bot-maubot.md) documentation to get started.
# 2022-07-14
## mx-puppet-skype removal
The playbook no longer includes the [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) bridge, because it has been broken and unmaintaned for a long time. Users that have `matrix_mx_puppet_skype_enabled` in their configuration files will encounter an error when running the playbook until they remove references to this bridge from their configuration.
To completely clean up your server from `mx-puppet-skype`'s presence on it:
- ensure your Ansible configuration (`vars.yml` file) no longer contains `matrix_mx_puppet_skype_*` references
- stop and disable the systemd service (run `systemctl disable --now matrix-mx-puppet-skype` on the server)
- delete the systemd service (run `rm /etc/systemd/system/matrix-mx-puppet-skype.service` on the server)
- delete `/matrix/mx-puppet-skype` (run `rm -rf /matrix/mx-puppet-skype` on the server)
- drop the `matrix_mx_puppet_skype` database (run `/usr/local/bin/matrix-postgres-cli` on the server, and execute the `DROP DATABASE matrix_mx_puppet_skype;` query there)
If you still need bridging to [Skype](https://www.skype.com/), consider switching to [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) instead. See [Setting up Go Skype Bridge bridging](docs/configuring-playbook-bridge-go-skype-bridge.md).
If you think this is a mistake and `mx-puppet-skype` works for you (or you get it to work somehow), let us know and we may reconsider this removal.
## signald (0.19.0+) upgrade requires data migration
In [Pull Request #1921](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1921) we upgraded [signald](https://signald.org/) (used by the mautrix-signal bridge) from `v0.18.5` to `v0.20.0`.
Back in the [`v0.19.0` released of signald](https://gitlab.com/signald/signald/-/blob/main/releases/0.19.0.md) (which we skipped and migrated straight to `v0.20.0`), a new `--migrate-data` command had been added that migrates avatars, group images, attachments, etc., into the database (those were previously stored in the filesystem).
If you've been using the mautrix-signal bridge for a while, you may have files stored in the local filesystem, which will need to be upgraded.
We attempt to do this data migration automatically every time Signald starts (`matrix-mautrix-signal-daemon.service`) using a `ExecStartPre` systemd unit definition.
Keep an eye on your Signal bridge and let us know (in our [support room](README.md#support) or in [Pull Request #1921](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1921)) if you experience any trouble!
# 2022-07-05
## Ntfy push notifications support
Thanks to [Julian Foad](https://matrix.to/#/@julian:foad.me.uk), the playbook can now install a [ntfy](https://ntfy.sh/) push notifications server for you.
See our [Setting up the ntfy push notifications server](docs/configuring-playbook-ntfy.md) documentation to get started.
# 2022-06-23
## (Potential Backward Compatibility Break) Changes around metrics collection
**TLDR**: we've made extensive **changes to metrics exposure/collection, which concern people using an external Prometheus server**. If you don't know what that is, you don't need to read below.
**Why do major changes to metrics**? Because various services were exposing metrics in different, hacky, ways. Synapse was exposing metrics at `/_synapse/metrics` and `/_synapse-worker-.../metrics` on the `matrix.DOMAIN`. The Hookshot role was **repurposing** the Granana web UI domain (`stats.DOMAIN`) for exposing its metrics on `stats.DOMAIN/hookshot/metrics`, while protecting these routes using Basic Authentication **normally used for Synapse** (`/_synapse/metrics`). Node-exporter and Postgres-exporter roles were advising for more `stats.DOMAIN` usage in manual ways. Each role was doing things differently and mixing variables from other roles. Each metrics endpoint was ending up in a different place, protected by who knows what Basic Authentication credentials (if protected at all).
**The solution**: a completely revamped way to expose metrics to an external Prometheus server. We are **introducing new `https://matrix.DOMAIN/metrics/*` endpoints**, where various services *can* expose their metrics, for collection by external Prometheus servers. To enable the `/metrics/*` endpoints, use `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`. There's also a way to protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). See the `matrix-nginx-proxy` role or our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation for additional variables around `matrix_nginx_proxy_proxy_matrix_metrics_enabled`.
**If you are using the [Hookshot bridge](docs/configuring-playbook-bridge-hookshot.md)**, you may find that:
1. **Metrics may not be enabled by default anymore**:
- If Prometheus is enabled (`matrix_prometheus_enabled: true`), then Hookshot metrics will be enabled automatically (`matrix_hookshot_metrics_enabled: true`). These metrics will be collected from the local (in-container) Prometheus over the container network.
- **If Prometheus is not enabled** (you are either not using Prometheus or are using an external one), **Hookshot metrics will not be enabled by default anymore**. Feel free to enable them by setting `matrix_hookshot_metrics_enabled: true`. Also, see below.
2. When metrics are meant to be **consumed by an external Prometheus server**, `matrix_hookshot_metrics_proxying_enabled` needs to be set to `true`, so that metrics would be exposed (proxied) "publicly" on `https://matrix.DOMAIN/metrics/hookshot`. To make use of this, you'll also need to enable the new `https://matrix.DOMAIN/metrics/*` endpoints mentioned above, using `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. Learn more in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation.
3. **We've changed the URL we're exposing Hookshot metrics at** for external Prometheus servers. Until now, you were advised to consume Hookshot metrics from `https://stats.DOMAIN/hookshot/metrics` (working in conjunction with `matrix_nginx_proxy_proxy_synapse_metrics`). From now on, **this no longer works**. As described above, you need to start consuming metrics from `https://matrix.DOMAIN/metrics/hookshot`.
**If you're using node-exporter** (`matrix_prometheus_node_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_node_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.DOMAIN/metrics/node-exporter`.
**If you're using [postgres-exporter](docs/configuring-playbook-prometheus-postgres.md)** (`matrix_prometheus_postgres_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_postgres_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.DOMAIN/metrics/postgres-exporter`.
**If you're using Synapse** and would like to collect its metrics from an external Prometheus server, you may find that:
1. Exposing metrics is now done using `matrix_synapse_metrics_proxying_enabled`, not `matrix_nginx_proxy_proxy_synapse_metrics: true`. You may still need to enable metrics using `matrix_synapse_metrics_enabled: true` before exposing them.
2. Protecting metrics endpoints using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) is now done in another way. See our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation
3. If Synapse metrics are exposed, they will be made available at `https://matrix.DOMAIN/metrics/synapse/main-process` or `https://matrix.DOMAIN/metrics/synapse/worker/TYPE-ID` (when workers are enabled), not at `https://matrix.DOMAIN/_synapse/metrics` and `https://matrix.DOMAIN/_synapse-worker-.../metrics`
4. The playbook still generates an `external_prometheus.yml.example` sample file for scraping Synapse from Prometheus as described in [Collecting Synapse worker metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-synapse-worker-metrics-to-an-external-prometheus-server), but it's now saved under `/matrix/synapse` (not `/matrix`).
**If you where already using a external Prometheus server** before this change, and you gave a hashed version of the password as a variable, the playbook will now take care of hashing the password for you. Thus, you need to provide the non-hashed version now.
# 2022-06-13
## go-skype-bridge bridging support
Thanks to [CyberShadow](https://github.com/CyberShadow), the playbook can now install the [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) bridge for bridging Matrix to [Skype](https://www.skype.com/).
See our [Setting up Go Skype Bridge](docs/configuring-playbook-bridge-go-skype-bridge.md) documentation to get started.
The playbook has supported [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) bridging (see [Setting up MX Puppet Skype bridging](docs/configuring-playbook-bridge-mx-puppet-skype.md)) since [2020-04-09](#2020-04-09), but `mx-puppet-skype` is reportedly broken.
# 2022-06-09
## Running Ansible in a container can now happen on the Matrix server itself
If you're tired of being on an old and problematic Ansible version, you can now run [run Ansible in a container on the Matrix server itself](docs/ansible.md#running-ansible-in-a-container-on-the-matrix-server-itself).
# 2022-05-31
## Synapse v1.60 upgrade may cause trouble and require manual intervention
Synapse v1.60 will try to add a new unique index to `state_group_edges` upon startup and could fail if your database is corrupted.
We haven't observed this problem yet, but [the Synapse v1.60.0 upgrade notes](https://github.com/matrix-org/synapse/blob/v1.60.0/docs/upgrade.md#adding-a-new-unique-index-to-state_group_edges-could-fail-if-your-database-is-corrupted) mention it, so we're giving you a heads up here in case you're unlucky.
**If Synapse fails to start** after your next playbook run, you'll need to:
- SSH into the Matrix server
- launch `/usr/local/bin/matrix-postgres-cli`
- switch to the `synapse` database: `\c synapse`
- run the following SQL query:
```sql
BEGIN;
DELETE FROM state_group_edges WHERE (ctid, state_group, prev_state_group) IN (
SELECT row_id, state_group, prev_state_group
FROM (
SELECT
ctid AS row_id,
MIN(ctid) OVER (PARTITION BY state_group, prev_state_group) AS min_row_id,
state_group,
prev_state_group
FROM state_group_edges
) AS t1
WHERE row_id <> min_row_id
);
COMMIT;
```
You could then restart services: `ansible-playbook -i inventory/hosts setup.yml --tags=start`
# 2022-04-25
## buscarron bot support
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up [the Buscarron bot](https://gitlab.com/etke.cc/buscarron). It's a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) Matrix room
See our [Setting up Buscarron](docs/configuring-playbook-bot-buscarron.md) documentation to get started.
# 2022-04-21
## matrix-registration-bot support
Thanks to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s), the playbook can now help you set up [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) - a bot that is used to create and manage registration tokens for a Matrix server.
See our [Setting up matrix-registration-bot](docs/configuring-playbook-bot-matrix-registration-bot.md) documentation to get started.
# 2022-04-19
## Borg backup support
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up [Borg](https://www.borgbackup.org/) backups with [borgmatic](https://torsion.org/borgmatic/) of your Matrix server.
See our [Setting up borg backup](docs/configuring-playbook-backup-borg.md) documentation to get started.
## (Compatibility Break) Upgrading to Synapse v1.57 on setups using workers may require manual action
If you're running a worker setup for Synapse (`matrix_synapse_workers_enabled: true`), the [Synapse v1.57 upgrade notes](https://github.com/matrix-org/synapse/blob/v1.57.0rc1/docs/upgrade.md#changes-to-database-schema-for-application-services) say that you may need to take special care when upgrading:
> Synapse v1.57.0 includes a change to the way transaction IDs are managed for application services. If your deployment uses a dedicated worker for application service traffic, **it must be stopped** when the database is upgraded (which normally happens when the main process is upgraded), to ensure the change is made safely without any risk of reusing transaction IDs.
If you're not running an `appservice` worker (`matrix_synapse_workers_preset: little-federation-helper` or `matrix_synapse_workers_appservice_workers_count: 0`), you are probably safe to upgrade as per normal, without taking any special care.
If you are running a setup with an `appservice` worker, or otherwise want to be on the safe side, we recommend the following upgrade path:
0. Pull the latest playbook changes
1. Stop all services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
2. Re-run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all`)
3. Start Postgres (`systemctl start matrix-postgres` on the server)
4. Start the main Synapse process (`systemctl start matrix-synapse` on the server)
5. Wait a while so that Synapse can start and complete the database migrations. You can use `journalctl -fu matrix-synapse` on the server to get a clue. Waiting a few minutes should also be enough.
6. It should now be safe to start all other services. `ansible-playbook -i inventory/hosts setup.yml --tags=start` will do it for you
# 2022-04-14
## (Compatibility Break) Changes to `docker-src` permissions necessitating manual action

7
Makefile Normal file
View File

@ -0,0 +1,7 @@
.PHONY: lint
help: ## Show this help.
@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
lint: ## Runs ansible-lint against all roles in the playbook
ansible-lint

14
README.md
View File

@ -47,6 +47,8 @@ Using this playbook, you can get the following services configured on your serve
- (optional, advanced) the [Matrix Corporal](https://github.com/devture/matrix-corporal) reconciliator and gateway for a managed Matrix server
- (optional) the [mautrix-discord](https://github.com/mautrix/discord) bridge for bridging your Matrix server to [Discord](https://discord.com/) - see [docs/configuring-playbook-bridge-mautrix-discord.md](docs/configuring-playbook-bridge-mautrix-discord.md) for setup documentation
- (optional) the [mautrix-telegram](https://github.com/mautrix/telegram) bridge for bridging your Matrix server to [Telegram](https://telegram.org/)
- (optional) the [mautrix-whatsapp](https://github.com/mautrix/whatsapp) bridge for bridging your Matrix server to [WhatsApp](https://www.whatsapp.com/)
@ -79,7 +81,7 @@ Using this playbook, you can get the following services configured on your serve
- (optional) the [Heisenbridge](https://github.com/hifi/heisenbridge) for bridging your Matrix server to IRC bouncer-style - see [docs/configuring-playbook-bridge-heisenbridge.md](docs/configuring-playbook-bridge-heisenbridge.md) for setup documentation
- (optional) the [mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-mx-puppet-skype.md](docs/configuring-playbook-bridge-mx-puppet-skype.md) for setup documentation
- (optional) the [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-go-skype-bridge.md](docs/configuring-playbook-bridge-go-skype-bridge.md) for setup documentation
- (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation
@ -89,7 +91,7 @@ Using this playbook, you can get the following services configured on your serve
- (optional) the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge for [Discord](https://discordapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-discord.md](docs/configuring-playbook-bridge-mx-puppet-discord.md) for setup documentation
- (optional) the [mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) bridge for [GroupMe](https://groupme.com/) - see [docs/configuring-playbook-bridge-mx-puppet-groupme.md](docs/configuring-playbook-bridge-mx-puppet-groupme.md) for setup documentation
- (optional) the [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) bridge for [GroupMe](https://groupme.com/) - see [docs/configuring-playbook-bridge-mx-puppet-groupme.md](docs/configuring-playbook-bridge-mx-puppet-groupme.md) for setup documentation
- (optional) the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge for [Steam](https://steamapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-steam.md](docs/configuring-playbook-bridge-mx-puppet-steam.md) for setup documentation
@ -103,6 +105,10 @@ Using this playbook, you can get the following services configured on your serve
- (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms - see [docs/configuring-playbook-bot-matrix-reminder-bot.md](docs/configuring-playbook-bot-matrix-reminder-bot.md) for setup documentation
- (optional) [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for invitations by creating and managing registration tokens - see [docs/configuring-playbook-bot-matrix-registration-bot.md](docs/configuring-playbook-bot-matrix-registration-bot.md) for setup documentation
- (optional) [maubot](https://github.com/maubot/maubot) a plugin-based Matrix bot system - see [docs/configuring-playbook-bot-maubot.md](docs/configuring-playbook-bot-maubot.md) for setup documentation
- (optional) [honoroit](https://gitlab.com/etke.cc/honoroit) helpdesk bot - see [docs/configuring-playbook-bot-honoroit.md](docs/configuring-playbook-bot-honoroit.md) for setup documentation
- (optional) [Go-NEB](https://github.com/matrix-org/go-neb) multi functional bot written in Go - see [docs/configuring-playbook-bot-go-neb.md](docs/configuring-playbook-bot-go-neb.md) for setup documentation
@ -117,12 +123,16 @@ Using this playbook, you can get the following services configured on your serve
- (optional) the [Sygnal](https://github.com/matrix-org/sygnal) push gateway - see [Setting up the Sygnal push gateway](docs/configuring-playbook-sygnal.md) for setup documentation
- (optional) the [ntfy](https://ntfy.sh) push notifications server - see [docs/configuring-playbook-ntfy.md](docs/configuring-playbook-ntfy.md) for setup documentation
- (optional) the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client - see [docs/configuring-playbook-client-hydrogen.md](docs/configuring-playbook-client-hydrogen.md) for setup documentation
- (optional) the [Cinny](https://github.com/ajbura/cinny) web client - see [docs/configuring-playbook-client-cinny.md](docs/configuring-playbook-client-cinny.md) for setup documentation
- (optional) the [Borg](https://borgbackup.org) backup - see [docs/configuring-playbook-backup-borg.md](docs/configuring-playbook-backup-borg.md) for setup documentation
- (optional) the [Buscarron](https://gitlab.com/etke.cc/buscarron) bot - see [docs/configuring-playbook-bot-buscarron.md](docs/configuring-playbook-bot-buscarron.md) for setup documentation
Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
**Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need.

4
docs/alternative-architectures.md
View File

@ -2,7 +2,7 @@
As stated in the [Prerequisites](prerequisites.md), currently only `x86_64` is fully supported. However, it is possible to set the target architecture, and some tools can be built on the host or other measures can be used.
To that end add the following variable to your `vars.yaml` file:
To that end add the following variable to your `vars.yml` file (see [Configuring playbook](configuring-playbook.md)):
```yaml
matrix_architecture: <your-matrix-server-architecture>
@ -13,7 +13,7 @@ Currently supported architectures are the following:
- `arm64`
- `arm32`
so for the Raspberry Pi, the following should be in your `vars.yaml` file:
so for the Raspberry Pi, the following should be in your `vars.yml` file:
```yaml
matrix_architecture: "arm32"

53
docs/ansible.md
View File

@ -30,7 +30,7 @@ Depending on your distribution, you may be able to upgrade Ansible in a few diff
- by using an additional repository (PPA, etc.), which provides newer Ansible versions. See instructions for [CentOS](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-rhel-centos-or-fedora), [Debian](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-debian), or [Ubuntu](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-ubuntu) on the Ansible website.
- by removing the Ansible package (`yum remove ansible` or `apt-get remove ansible`) and installing via [pip](https://pip.pypa.io/en/stable/installing/) (`pip install ansible`).
- by removing the Ansible package (`yum remove ansible` or `apt-get remove ansible`) and installing via [pip](https://pip.pypa.io/en/stable/installation/) (`pip install ansible`).
If using the `pip` method, do note that the `ansible-playbook` binary may not be on the `$PATH` (https://linuxconfig.org/linux-path-environment-variable), but in some more special location like `/usr/local/bin/ansible-playbook`. You may need to invoke it using the full path.
@ -41,9 +41,50 @@ If you find yourself needing to resort to such hacks, please consider reporting
## Using Ansible via Docker
Alternatively, you can run Ansible on your computer from 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 [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
Here's a sample command to get you started (run this from the playbook's directory):
This ensures that you're using a very recent Ansible version, which is less likely to be incompatible with the playbook.
There are 2 ways to go about it:
- [Running Ansible in a container on the Matrix server itself](#running-ansible-in-a-container-on-the-matrix-server-itself)
- [Running Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server)
### Running Ansible in a container on the Matrix server itself
To run Ansible in a (Docker) container on the Matrix server itself, you need to have a working Docker installation.
Docker is normally installed by the playbook, so this may be a bit of a chicken and egg problem. To solve it:
- you **either** need to install Docker manually first. Follow [the upstream instructions](https://docs.docker.com/engine/install/) for your distribution and consider setting `matrix_docker_installation_enabled: false` in your `vars.yml` file, to prevent the playbook from installing Docker
- **or** you need to run the playbook in another way (e.g. [Running Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server)) at least the first time around
Once you have a working Docker installation on the server, **clone the playbook** somewhere on the server and configure it as per usual (`inventory/hosts`, `inventory/host_vars/..`, etc.), as described in [configuring the playbook](configuring-playbook.md).
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 ...`
Run this from the playbook's directory:
```bash
docker run -it --rm \
--privileged \
--pid=host \
-w /work \
-v `pwd`:/work \
--entrypoint=/bin/sh \
docker.io/devture/ansible:2.13.0-r0
```
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.
You can execute `ansible-playbook ...` (or `ansible-playbook --connection=community.docker.nsenter ...`) commands as per normal now.
### Running Ansible in a container on another computer (not the Matrix server)
Run this from the playbook's directory:
```bash
docker run -it --rm \
@ -51,7 +92,7 @@ docker run -it --rm \
-v `pwd`:/work \
-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
--entrypoint=/bin/sh \
docker.io/devture/ansible:2.11.6-r1
docker.io/devture/ansible:2.13.0-r0
```
The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`).
@ -60,9 +101,9 @@ If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that
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.
You can execute `ansible-playbook` commands as per normal now.
You can execute `ansible-playbook ...` commands as per normal now.
### If you don't use SSH keys for authentication
#### If you don't use SSH keys for authentication
If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`).
To authenticate at your server using a password, you need to add a package. So, when you are in the shell of the ansible docker container (the previously used `docker run -it ...` command), run:

BIN
docs/assets/obtain_admin_access_token_element.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 205 KiB

6
docs/configuring-dns.md
View File

@ -36,8 +36,10 @@ If you are using Cloudflare DNS, make sure to disable the proxy and set all reco
| CNAME | `stats` | - | - | - | `matrix.<your-domain>` |
| CNAME | `goneb` | - | - | - | `matrix.<your-domain>` |
| CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| CNAME | `ntfy` | - | - | - | `matrix.<your-domain>` |
| CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
| CNAME | `cinny` | - | - | - | `matrix.<your-domain>` |
| CNAME | `buscarron` | - | - | - | `matrix.<your-domain>` |
## Subdomains setup
@ -56,10 +58,14 @@ The `goneb.<your-domain>` subdomain may be necessary, because this playbook coul
The `sygnal.<your-domain>` subdomain may be necessary, because this playbook could install the [Sygnal](https://github.com/matrix-org/sygnal) push gateway. The installation of Sygnal is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Sygnal guide](configuring-playbook-sygnal.md). If you do not wish to set up Sygnal (you probably don't, unless you're also developing/building your own Matrix apps), feel free to skip the `sygnal.<your-domain>` DNS record.
The `ntfy.<your-domain>` subdomain may be necessary, because this playbook could install the [ntfy](https://ntfy.sh/) UnifiedPush-compatible push notifications server. The installation of ntfy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring ntfy guide](configuring-playbook-ntfy.md). If you do not wish to set up ntfy, feel free to skip the `ntfy.<your-domain>` DNS record.
The `hydrogen.<your-domain>` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client. The installation of Hydrogen is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Hydrogen guide](configuring-playbook-client-hydrogen.md). If you do not wish to set up Hydrogen, feel free to skip the `hydrogen.<your-domain>` DNS record.
The `cinny.<your-domain>` subdomain may be necessary, because this playbook could install the [Cinny](https://github.com/ajbura/cinny) web client. The installation of cinny is disabled by default, it is not a core required component. To learn how to install it, see our [configuring cinny guide](configuring-playbook-client-cinny.md). If you do not wish to set up cinny, feel free to skip the `cinny.<your-domain>` DNS record.
The `buscarron.<your-domain>` subdomain may be necessary, because this playbook could install the [buscarron](https://gitlab.com/etke.cc/buscarron) bot. The installation of buscarron is disabled by default, it is not a core required component. To learn how to install it, see our [configuring buscarron guide](configuring-playbook-bot-buscarron.md). If you do not wish to set up buscarron, feel free to skip the `buscarron.<your-domain>` DNS record.
## `_matrix-identity._tcp` SRV record setup
To make the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server (which this playbook may optionally install for you) enable its federation features, set up an SRV record that looks like this:

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

@ -8,6 +8,9 @@ You will need a remote server where borg will store the backups. There are hoste
The backup will run based on `matrix_backup_borg_schedule` var (systemd timer calendar), default: 4am every day.
By default, if you're using the integrated Postgres database server (as opposed to [an external Postgres server](configuring-playbook-external-postgres.md)), Borg backups will also include dumps of your Postgres database. An alternative solution for backing up the Postgres database is [postgres backup](configuring-playbook-postgres-backup.md). If you decide to go with another solution, you can disable Postgres-backup support for Borg using the `matrix_backup_borg_postgresql_enabled` variable.
## Prerequisites
1. Create a new SSH key:
@ -40,7 +43,13 @@ matrix_backup_borg_location_repositories:
- USER@HOST:REPO
matrix_backup_borg_storage_encryption_passphrase: "PASSPHRASE"
matrix_backup_borg_ssh_key_private: |
PRIVATE KEY
-----BEGIN OPENSSH PRIVATE KEY-----
TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZW
xpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRv
bG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3
RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXgg
ZWEgY29tbW9kbyBjb25zZXF1YXQuIA==
-----END OPENSSH PRIVATE KEY-----
```
where:
@ -49,7 +58,7 @@ where:
* HOST - SSH host of a provider/server
* REPO - borg repository name, it will be initialized on backup start, eg: `matrix`
* PASSPHRASE - passphrase used for encrypting backups, you may generate it with `pwgen -s 64 1` or use any password manager
* PRIVATE KEY - the content of the **private** part of the SSH key you created before
* PRIVATE KEY - the content of the **private** part of the SSH key you created before. The whole key (all of its belonging lines) under `matrix_backup_borg_ssh_key_private` needs to be indented with 2 spaces
To backup without encryption, add `matrix_backup_borg_encryption: 'none'` to your vars. This will also enable the `matrix_backup_borg_unknown_unencrypted_repo_access_is_ok` variable.

75
docs/configuring-playbook-bot-buscarron.md Normal file
View File

@ -0,0 +1,75 @@
# Setting up Buscarron (optional)
The playbook can install and configure [buscarron](https://gitlab.com/etke.cc/buscarron) for you.
It's a bot you can use to setup **your own helpdesk on matrix**
It's a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) matrix room
## Registering the bot user
By default, the playbook will set up the bot with a username like this: `@bot.buscarron:DOMAIN`.
(to use a different username, adjust the `matrix_bot_buscarron_login` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.buscarron password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_buscarron_enabled: true
# Adjust this to whatever password you chose when registering the bot user
matrix_bot_buscarron_password: PASSWORD_FOR_THE_BOT
# Adjust accepted forms
matrix_bot_buscarron_forms:
- name: contact # (mandatory) Your form name, will be used as endpoint, eg: buscarron.DOMAIN/contact
room: "!yourRoomID:DOMAIN" # (mandatory) Room ID where form submission will be posted
redirect: https://DOMAIN # (mandatory) To what page user will be redirected after the form submission
ratelimit: 1r/m # (optional) rate limit of the form, format: <max requests>r/<interval:s,m>, eg: 1r/s or 54r/m
extensions: [] # (optional) list of form extensions (not used yet)
matrix_bot_buscarron_spam_hosts: [] # (optional) list of email domains/hosts that should be rejected automatically
matrix_bot_buscarron_spam_emails: [] # (optional) list of email addresses that should be rejected automatically
```
You will also need to add a DNS record so that buscarron can be accessed.
By default buscarron will use https://buscarron.DOMAIN so you will need to create an CNAME record for `buscarron`.
See [Configuring DNS](configuring-dns.md).
If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):
```yaml
matrix_server_fqn_buscarron: "form.{{ matrix_domain }}"
```
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
To use the bot, invite the `@bot.buscarron:DOMAIN` to the room you specified in a config, after that any point your form to the form url, example for the `contact` form:
```html
<form method="POST" action="https://buscarron.DOMAIN/contact">
<!--your fields-->
</form>
```
You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/buscarron).

72
docs/configuring-playbook-bot-matrix-registration-bot.md Normal file
View File

@ -0,0 +1,72 @@
# Setting up matrix-registration-bot (optional)
The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
The bot allows you to easily **create and manage registration tokens**. It can be used for an invitation-based server,
where you invite someone by sending them a registration token. They can register as normal but have to provide a valid
registration token in a final step of the registration.
See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it
does and why it might be useful to you.
## Registering the bot user
By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:DOMAIN`.
(to use a different username, adjust the `matrix_bot_matrix_registration_bot_matrix_user_id_localpart` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-registration-bot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Obtaining an admin access token
In order to use the bot you need to add an admin user's access token token to the configuration. As you created an admin user for the
bot, it is recommended to obtain an access token by logging into Element/Schildichat with the bot account
(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
You can expand "Access token" to copy it.
![Obatining an admin access token with Element](assets/obtain_admin_access_token_element.png)
**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_matrix_registration_bot_enabled: true
# Token obtained via logging into the bot account (see above)
matrix_bot_matrix_registration_bot_bot_access_token: "syt_bW9hbm9z_XXXXXXXXXXXXXr_2kuzbE"
# Enables registration
matrix_synapse_enable_registration: true
# Restrict registration to users with a token
matrix_synapse_registration_requires_token: true
```
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
To use the bot, create a **non-encrypted** room and invite `@bot.matrix-registration-bot:DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
In this room send `help` and the bot will reply with all options.
You can also refer to the upstream [Usage documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands).
If you have any questions, or if you need help setting it up, read the [troublshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md)
or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).

63
docs/configuring-playbook-bot-maubot.md Normal file
View File

@ -0,0 +1,63 @@
# Setting up maubot (optional)
The playbook can install and configure [maubot](https://github.com/maubot/maubot) for you.
After setting up maubot, you can use the web management interface to make it do things.
The default location of the management interface is `matrix.<your-domain>/_matrix/maubot/`
See the project's [documentation](https://docs.mau.fi/maubot/usage/basic.html) to learn what it
does and why it might be useful to you.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_maubot_enabled: true
matrix_bot_maubot_admins:
- yourusername: securepassword
```
You can add multiple admins. The admin accounts are not connected to any matrix ID and are only used to access the
maubot administration interface.
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
You can visit `matrix.<your-domain>/_matrix/maubot/` to manage your available plugins, clients and instances.
You should start in the following order
1. **Create one or more clients:** A client is a matrix account which the bot will use to message.
2. **Upload some Plugins:** Plugins can be obtained from [here](https://github.com/maubot/maubot#plugins) or any other source.
3. **Create an instance:** An instance is the actual bot. You have to specify a client which the bot instance will use
and the plugin (how the bot will behave)
To add a client you first need to create an account and obtain a valid access token.
## Registering the bot user
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.maubot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Obtaining an admin access token
This can be done via `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)) or by logging into Element/Schildichat with the bot account
(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
You can expand "Access token" to copy it.
![Obatining an admin access token with Element](assets/obtain_admin_access_token_element.png)
**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.

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

@ -1,6 +1,8 @@
# Setting up Appservice Discord (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) bridge supported by the playbook.
**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.
- For using as a Bot we are recommend the Appservice Discord bridge (the one being discussed here), because it supports plumbing.
- For personal use 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.
The playbook can install and configure [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) for you.
@ -61,7 +63,7 @@ To get started with Portal Bridging:
1. To invite the bot to Discord, retrieve the invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).
2. Room addresses follow this syntax: `#_discord_<guildID>_<channelID>`. You can easily find the guild and channel IDs by logging into Discord in a browser and opening the desired channel. The URL will have this format: `discord.com/channels/<guildID>/<channelID>`.
3. Once you have figured out the appropriate room address, you can join by doing `/join #_discord_<guildID>_<channelID>` in your Matrix client.
3. Once you have figured out the appropriate room address, you can join by doing `/join #_discord_<guildID>_<channelID>` in your Matrix client.
## Getting Administrator access in a portal bridged room

68
docs/configuring-playbook-bridge-appservice-kakaotalk.md Normal file
View File

@ -0,0 +1,68 @@
# Setting up Appservice Kakaotalk (optional)
The playbook can install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) for you. `matrix-appservice-kakaotalk` is a bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code.
See the project's [documentation](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) to learn what it does and why it might be useful to you.
## Installing
To enable the bridge, add this to your `vars.yml` file:
```yaml
matrix_appservice_kakaotalk_enabled: true
```
You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
After adjusting your `vars.yml` file, re-run the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
To make use of the Kakaotalk bridge, see [Usage](#usage) below.
### Additional configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/matrix-bridge-appservice-kakaotalk/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/matrix-bridge-appservice-kakaotalk/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_kakaotalk_configuration_extension_yaml` variable
### Set up Double Puppeting
If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
#### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
#### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Appservice-Kakaotalk", "initial_device_display_name": "Appservice-Kakaotalk"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature
## Usage
Start a chat with `@kakaotalkbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
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.
After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.

23
docs/configuring-playbook-bridge-go-skype-bridge.md Normal file
View File

@ -0,0 +1,23 @@
# Setting up Go Skype Bridge (optional)
The playbook can install and configure
[go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you.
See the project page to learn what it does and why it might be useful to you.
To enable the [Skype](https://www.skype.com/) bridge just use the following
playbook configuration:
```yaml
matrix_go_skype_bridge_enabled: true
```
## Usage
Once the bot is enabled, you need to start a chat with `Skype bridge bot`
with the handle `@skypebridgebot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
domain, not the `matrix.` domain).
Send `help` to the bot to see the commands available.

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

@ -4,19 +4,19 @@ The playbook can install and configure [matrix-hookshot](https://github.com/matr
Hookshot can bridge [Webhooks](https://en.wikipedia.org/wiki/Webhook) from software project management services such as GitHub, GitLab, JIRA, and Figma, as well as generic webhooks.
See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/hookshot.html) to learn what it does in detail and why it might be useful to you.
See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html) to learn what it does in detail and why it might be useful to you.
Note: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however is soon to be archived by its author and to be replaced by hookshot.
## Setup Instructions
Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/setup.html) to learn what the individual options do.
Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) to learn what the individual options do.
1. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) as required.
2. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
3. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-matrix-aux-role) explained below.
3. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-matrix-aux-role) explained below.
4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
5. Refer to [Hookshot's official instructions](https://matrix-org.github.io/matrix-hookshot/usage.html) to start using the bridge. **Important:** Note that the different listeners are bound to certain paths which might differe from those assumed by the hookshot documentation, see [URLs for bridges setup](urls-for-bridges-setup) below.
5. Refer to [Hookshot's official instructions](https://matrix-org.github.io/matrix-hookshot/latest/usage.html) to start using the bridge. **Important:** Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](urls-for-bridges-setup) below.
Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
@ -26,14 +26,14 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
| listener | default path | variable | used as |
|---|---|---|---|
| webhooks | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | generics, GitHub "Webhook URL", etc. |
| webhooks | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | generics, GitHub "Webhook URL", GitLab "URL", etc. |
| github oauth | `/hookshot/webhooks/oauth` | `matrix_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | JIRA OAuth |
| figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |
| 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 | `/hookshot/metrics/` (on `stats.` subdomain) | `matrix_hookshot_metrics_endpoint` | Prometheus |
| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
| metrics | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and `matrix_hookshot_metrics_proxying_enabled`. Requires `/metrics/*` endpoints to also be enabled via `matrix_nginx_proxy_proxy_matrix_metrics_enabled` (see the `matrix-nginx-proxy` role). Read more in the [Metrics section](#metrics) below. | Prometheus |
See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/matrix-bridge-hookshot/tasks/init.yml).
@ -63,7 +63,14 @@ The provisioning API will be enabled automatically if you set `matrix_dimension_
### Metrics
If metrics are enabled, they will be automatically available in the builtin Prometheus and Grafana, but you need to set up your own Dashboard for now. If additionally metrics proxying for use with external Prometheus is enabled (`matrix_nginx_proxy_proxy_synapse_metrics`), hookshot metrics will also be available (at `matrix_hookshot_metrics_endpoint`, default `/hookshot/metrics`, on the stats subdomain) and with the same password. See also [the Prometheus and Grafana docs](../configuring-playbook-prometheus-grafana.md).
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 the `https://matrix.DOMAIN/metrics/*` endpoints on `matrix.DOMAIN` using `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true` (see the `matrix-nginx-role` or [the Prometheus and Grafana docs](configuring-playbook-prometheus-grafana.md) for enabling this feature)
- expose the Hookshot metrics under `https://matrix.DOMAIN/metrics/hookshot` by setting `matrix_hookshot_metrics_proxying_enabled: true`
### Collision with matrix-appservice-webhooks

87
docs/configuring-playbook-bridge-mautrix-discord.md Normal file
View File

@ -0,0 +1,87 @@
# Setting up Mautrix Discord (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridges supported by the playbook.
- For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing.
- For personal use with a discord account we recommend the `mautrix-discord` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
The `mautrix-discord` bridge (the one being discussed here) is the most fully-featured and stable of the 3 Discord bridges supported by the playbook, so it's the one we recommend.
The playbook can install and configure [mautrix-discord](https://github.com/mautrix/discord) for you.
See the project's [documentation](https://docs.mau.fi/bridges/go/discord/index.html) to learn what it does and why it might be useful to you.
## Prerequisites
For using this bridge, you would **need to authenticate by scanning a QR code with the Discord app on your phone**.
You can delete the Discord app after the authentication process.
If this is a dealbreaker for you, consider using one of the other Discord bridges supported by the playbook: [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) or [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md). These come with their own complexity and limitations, however, so we recommend that you proceed with this one if possible.
## Installing
To enable the bridge, add this to your `vars.yml` file:
```yaml
matrix_mautrix_discord_enabled: true
```
You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
After adjusting your `vars.yml` file, re-run the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
To make use of the bridge, see [Usage](#usage) below.
### Additional configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/matrix-bridge-mautrix-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/matrix-bridge-mautrix-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_discord_configuration_extension_yaml` variable
### Set up Double Puppeting
If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
#### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
#### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Discord", "initial_device_display_name": "Mautrix-Discord"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature
## Usage
1. Start a chat with `@discordbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
2. Send a `login` command
3. You'll see a QR code which you need to scan with the Discord app on your phone. You can scan it with the camera app too, which will open Discord, which will then instruct you to scan it a 2nd time in the Discord app.
4. After confirming (in the Discord app) that you'd like to allow this login, the bot should respond with "Succcessfully authenticated as ..."
5. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to
6. Some Direct Messages from Discord should start syncing automatically
7. If you'd like to bridge guilds:
- send `guilds status` to see the list of guilds
- for each guild that you'd like bridged, send `guilds bridge GUILD_ID --entire`
8. You may wish to uninstall the Discord app from your phone now. It's not needed for the bridge to function.

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

@ -24,10 +24,22 @@ If you would like to be able to administrate the bridge from your account it can
matrix_mautrix_facebook_configuration_extension_yaml: |
bridge:
permissions:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
'@YOUR_USERNAME:{{ matrix_domain }}': admin
```
You may wish to look at `roles/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` to find other things you would like to configure.
Using both would look like
```yaml
matrix_mautrix_facebook_configuration_extension_yaml: |
bridge:
permissions:
'@YOUR_USERNAME:{{ matrix_domain }}': admin
encryption:
allow: true
default: true
```
You may wish to look at `roles/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-facebook/defaults/main.yml` to find other things you would like to configure.
## Set up Double Puppeting
@ -91,3 +103,5 @@ Once connected, you should be able to verify that you're browsing the web throug
Then proceed to log in to [Facebook/Messenger](https://www.facebook.com/).
Once logged in, proceed to [set up bridging](#usage).
If that doesn't work, enable 2FA [Facebook help page on enabling 2FA](https://www.facebook.com/help/148233965247823) and try to login again with a new password, and entering the 2FA code when prompted, it may take more then one try, in between attempts, check facebook.com to see if they are requiring another password change

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

@ -7,6 +7,32 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/instagram/i
```yaml
matrix_mautrix_instagram_enabled: true
```
There are some additional things you may wish to configure about the bridge before you continue.
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
```yaml
matrix_mautrix_instagram_configuration_extension_yaml: |
bridge:
encryption:
allow: true
default: true
```
If you would like to be able to administrate the bridge from your account it can be configured like this:
```yaml
# The easy way. The specified Matrix user ID will be made an admin of all bridges
matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
# OR:
# The more verbose way. Applies to this bridge only. You may define multiple Matrix users as admins.
matrix_mautrix_instagram_configuration_extension_yaml: |
bridge:
permissions:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
```
You may wish to look at `roles/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure.
## Usage

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

@ -1,6 +1,8 @@
# Setting up MX Puppet Discord (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridge 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.
The playbook can install and configure
[mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) for you.

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

@ -1,7 +1,7 @@
# Setting up MX Puppet GroupMe (optional)
The playbook can install and configure
[mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) for you.
[mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) for you.
See the project page to learn what it does and why it might be useful to you.

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

@ -1,30 +1,5 @@
# Setting up MX Puppet Skype (optional)
The playbook can install and configure
[mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) for you.
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 unmaintaned for a long time.
See the project page to learn what it does and why it might be useful to you.
To enable the [Skype](https://www.skype.com/) bridge just use the following
playbook configuration:
```yaml
matrix_mx_puppet_skype_enabled: true
```
## Usage
Once the bot is enabled you need to start a chat with `Skype Puppet Bridge` with
the handle `@_skypepuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
domain, not the `matrix.` domain).
Send `link <username> <password>` to the bridge bot to link your skype account.
Once logged in, send `list` to the bot user to list the available rooms.
Clicking rooms in the list will result in you receiving an invitation to the
bridged room.
Also send `help` to the bot to see the commands available.
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.

2
docs/configuring-playbook-matrix-registration.md
View File

@ -2,6 +2,8 @@
The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you.
**WARNING**: this is a poorly maintained and buggy project. It's better to avoid using it.
> matrix-registration is a simple python application to have a token based matrix registration.
Use matrix-registration to **create unique registration links**, which people can use to register on your Matrix server. It allows you to **keep your server's registration closed (private)**, but still allow certain people (these having a special link) to register a user account.

111
docs/configuring-playbook-mautrix-bridges.md Normal file
View File

@ -0,0 +1,111 @@
# Setting up a Generic Mautrix Bridge (optional)
The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, facebook, instagram, signal, hangouts, googlechat, etc.), as well as many other (non-mautrix) bridges.
This is a common guide for configuring mautrix bridges.
You can see each bridge's features at in the `ROADMAP.md` file in its corresponding [mautrix](https://github.com/mautrix) repository.
To enable a bridge add:
```yaml
# Replace SERVICENAME with one of: twitter, facebook, instagram, ..
matrix_mautrix_SERVICENAME_enabled: true
```
to your `vars.yml`
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.
You can add
```yaml
matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
```
to `vars.yml` to **configure a user as an administrator for all bridges**.
**Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
permissions:
'@YOUR_USERNAME:{{ matrix_domain }}': admin
```
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
encryption:
allow: true
default: true
```
You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
permissions:
'@YOUR_USERNAME:{{ matrix_domain }}': admin
encryption:
allow: true
default: true
```
## Setting the bot's username
```yaml
matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
```
Can be used to set the username for the bridge.
## Discovering additional configuration options
You may wish to look at `roles/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` to find other things you would like to configure.
## Set up Double Puppeting
To set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html)
please do so automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook by adding
```yaml
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
```
You should generate a strong shared secret with a command like this: pwgen -s 64 1
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
## Controlling the logging level
```yaml
matrix_mautrix_SERVICENAME_logging_level: WARN
```
to `vars.yml` to control the logging level, where you may replace WARN with one of the following to control the verbosity of the logs generated: TRACE, DEBUG, INFO, WARN, ERROR, or FATAL.
If you have issues with a service, and are requesting support, the higher levels of logging will generally be more helpful.
## Usage
You then need to start a chat with `@SERVICENAMEbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Send `login ` to the bridge bot to get started You can learn more here about authentication from the bridge's official documentation on Authentication https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html .
If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
## Troubleshooting
For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge.
Reporting bridge bugs should happen upstream, in the corresponding mautrix repository, not to us.

93
docs/configuring-playbook-ntfy.md Normal file
View File

@ -0,0 +1,93 @@
# Setting up ntfy (optional)
The playbook can install and configure the [ntfy](https://ntfy.sh/) 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.
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.
**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.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
# Enabling it is the only required setting
matrix_ntfy_enabled: true
# Some other options
matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
matrix_ntfy_configuration_extension_yaml: |
log_level: DEBUG
```
For a more complete list of variables that you could override, see `roles/matrix-ntfy/defaults/main.yml`.
For a complete list of ntfy config options that you could put in `matrix_ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
## Installing
Don't forget to add `ntfy.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
To make use of your ntfy installation, on Android for example, you need two things:
* the `ntfy` app
* a UnifiedPush-compatible matrix app
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.
### Setting up the `ntfy` Android app
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.DOMAIN`.
3. In its Settings -> `Advanced: Connection protocol`, choose `WebSockets`.
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.
### Setting up a UnifiedPush-compatible matrix app
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:
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.)*
3. verify `Settings` -> `Notifications` -> `UnifiedPush: Notification targets` as described below in the "Troubleshooting" section.
* Element-android v1.4.26+:
- [not yet documented; should auto-detect and use it?]
If the matrix app 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.
## Troubleshooting
First check that the matrix client app you are using supports UnifiedPush. There may well be different variants of the app.
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`.
To check if UnifiedPush is correctly configured on the client device, look at "Settings -> Notifications -> Notification Targets" in Element-Android or SchildiChat, 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.
In the "Notification Targets" screen in Element-Android or SchildiChat, 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 (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.

8
docs/configuring-playbook-own-webserver.md
View File

@ -57,6 +57,14 @@ matrix_nginx_proxy_ssl_protocols: "TLSv1.2"
If you are experiencing issues, try updating to a newer version of Nginx. As a data point in May 2021 a user reported that Nginx 1.14.2 was not working for them. They were getting errors about socket leaks. Updating to Nginx 1.19 fixed their issue.
If you are not going to be running your webserver on the same docker network, or the same machine as matrix, these variables can be set to bind synapse to an exposed port. [Keep in mind that there are some security concerns if you simply proxy everything to it](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints)
```yaml
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8048" or "192.168.1.3:80"), or empty string to not expose.
matrix_synapse_container_client_api_host_bind_port: ''
matrix_synapse_container_federation_api_plain_host_bind_port: ''
```
### Using your own external Apache webserver

3
docs/configuring-playbook-postgres-backup.md
View File

@ -2,6 +2,9 @@
The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you.
For a more complete backup solution (one that includes not only Postgres, but also other configuration/data files), you may wish to look into [borg backup](configuring-playbook-backup-borg.md) instead.
## Adjusting the playbook configuration
Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable Postgres backup:

87
docs/configuring-playbook-prometheus-grafana.md
View File

@ -9,8 +9,12 @@ Remember to add `stats.<your-domain>` to DNS as described in [Configuring DNS](c
```yaml
matrix_prometheus_enabled: true
# You can remove this, if unnecessary.
matrix_prometheus_node_exporter_enabled: true
# You can remove this, if unnecessary.
matrix_prometheus_postgres_exporter_enabled: true
matrix_grafana_enabled: true
matrix_grafana_anonymous_access: false
@ -34,6 +38,7 @@ Name | Description
-----|----------
`matrix_prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
`matrix_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
`matrix_prometheus_postgres_exporter_enabled`|[Postgres Exporter](configuring-playbook-prometheus-postgres.md) is an addon of sorts to expose Postgres database metrics to Prometheus.
`matrix_grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
`matrix_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.
`matrix_grafana_default_admin_user`<br>`matrix_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
@ -48,28 +53,55 @@ Most of our docker containers run with limited system access, but the `prometheu
## Collecting metrics to an external Prometheus server
If you wish, you could expose homeserver metrics without enabling (installing) Prometheus and Grafana via the playbook. This may be useful for hooking Matrix services to an external Prometheus/Grafana installation.
**If the integrated Prometheus server is enabled** (`matrix_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".
To do this, you may be interested in the following variables:
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.DOMAIN/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/hookshot`, etc). To enable this `/metrics/*` feature, use `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_enabled` below.
The following variables may be of interest:
Name | Description
-----|----------
`matrix_nginx_proxy_proxy_matrix_metrics_enabled`|Set this to `true` to enable metrics exposure for various services on `https://matrix.DOMAIN/metrics/*`. Refer to the individual `matrix_SERVICE_metrics_proxying_enabled` variables below for exposing metrics for each individual service.
`matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.DOMAIN/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_nginx_proxy_proxy_matrix_metrics_basic_auth_username`|Set this to the Basic Authentication username you'd like to protect `/metrics/*` with. You also need to set `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password`. If one username/password pair is not enough, you can leave the `username` and `password` variables unset and use `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_raw_content` instead
`matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password`|Set this to the Basic Authentication password you'd like to protect `/metrics/*` with
`matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_raw_content`|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. If you only need one credential, use `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_username` and `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password` instead.
`matrix_synapse_metrics_enabled`|Set this to `true` to make Synapse expose metrics (locally, on the container network)
`matrix_nginx_proxy_proxy_synapse_metrics`|Set this to `true` to make matrix-nginx-proxy expose the Synapse metrics at `https://matrix.DOMAIN/_synapse/metrics`
`matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled`|Set this to `true` to password-protect (using HTTP Basic Auth) `https://matrix.DOMAIN/_synapse/metrics` (the username is always `prometheus`, the password is defined in `matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_key`)
`matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_key`|Set this to a password to use for HTTP Basic Auth for protecting `https://matrix.DOMAIN/_synapse/metrics` (the username is always `prometheus` - it's not configurable). Do not write the password in plain text. See `man 1 htpasswd` or use `htpasswd -c mypass.htpasswd prometheus` to generate the expected hash for nginx.
`matrix_server_fqn_grafana`|Use this variable to override the domain at which the Grafana web user-interface is at (defaults to `stats.DOMAIN`)
`matrix_synapse_metrics_proxying_enabled`|Set this to `true` to expose Synapse's metrics on `https://matrix.DOMAIN/metrics/synapse/main-process` and `https://matrix.DOMAIN/metrics/synapse/worker/TYPE-ID` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`). Read [below](#collecting-synapse-worker-metrics-to-an-external-prometheus-server) if you're running a Synapse worker setup (`matrix_synapse_workers_enabled: true`).
`matrix_prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network)
`matrix_prometheus_node_exporter_metrics_proxying_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.DOMAIN/metrics/node-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
`matrix_prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](configuring-playbook-prometheus-postgres.md) (locally, on the container network)
`matrix_prometheus_postgres_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
`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.DOMAIN/metrics/hookshot` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
`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. Only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`
`matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks`|Add nginx `location` blocks to this list if you'd like to expose additional exporters manually (see below)
### Collecting worker metrics to an external Prometheus server
Example for how to make use of `matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks` for exposing additional metrics locations:
```nginx
matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks:
- 'location /metrics/another-service {
resolver 127.0.0.11 valid=5s;
proxy_pass http://matrix-another-service:9100/metrics;
}'
```
If you are using workers (`matrix_synapse_workers_enabled`) and have enabled `matrix_nginx_proxy_proxy_synapse_metrics` as described above, the playbook will also automatically proxy the all worker threads's metrics to `https://matrix.DOMAIN/_synapse-worker-TYPE-ID/metrics`, where `TYPE` corresponds to the type and `ID` to the instanceId of a worker as exemplified in `matrix_synapse_workers_enabled_list`.
Using `matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks` only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true` (see above).
The playbook also generates an exemplary prometheus.yml config file (`matrix_base_data_path/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs, especially edit the specified `password_file` path and contents and path to your `synapse-v2.rules`.
Note : The playbook will hash the basic_auth password for you on setup. Thus, you need to give the plain-text version of the password as a variable.
### Collecting Synapse worker metrics to an external Prometheus server
If you are using workers (`matrix_synapse_workers_enabled: true`) and have enabled `matrix_synapse_metrics_proxying_enabled` as described above, the playbook will also automatically expose all Synapse worker threads' metrics to `https://matrix.DOMAIN/metrics/synapse/worker/TYPE-ID`, where `TYPE` corresponds to the type and `ID` to the instanceId of a worker as exemplified in `matrix_synapse_workers_enabled_list`.
The playbook also generates an exemplary config file (`/matrix/synapse/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs. Make sure to edit the specified `password_file` path and contents and path to your `synapse-v2.rules`.
It will look a bit like this:
```yaml
scrape_configs:
- job_name: 'synapse'
metrics_path: /_synapse/metrics
metrics_path: /metrics/synapse/main-process
scheme: https
basic_auth:
username: prometheus
@ -80,7 +112,7 @@ scrape_configs:
job: "master"
index: 1
- job_name: 'synapse-generic_worker-1'
metrics_path: /_synapse-worker-generic_worker-18111/metrics
metrics_path: /metrics/synapse/worker/generic_worker-18111
scheme: https
basic_auth:
username: prometheus
@ -92,38 +124,6 @@ scrape_configs:
index: 18111
```
### Collecting system and Postgres metrics to an external Prometheus server (advanced)
When you normally enable the Prometheus and Grafana via the playbook, it will also show general system (via node-exporter) and Postgres (via postgres-exporter) stats. If you are instead collecting your metrics to an external Prometheus server, you can follow this advanced configuration example to also export these stats.
It would be possible to use `matrix_prometheus_node_exporter_container_http_host_bind_port` etc., but that is not always the best choice, for example because your server is on a public network.
Use the following variables in addition to the ones mentioned above:
Name | Description
-----|----------
`matrix_nginx_proxy_proxy_grafana_enabled`|Set this to `true` to make the stats subdomain (`matrix_server_fqn_grafana`) available via the Nginx proxy
`matrix_ssl_additional_domains_to_obtain_certificates_for`|Add `"{{ matrix_server_fqn_grafana }}"` to this list to have letsencrypt fetch a certificate for the stats subdomain
`matrix_prometheus_node_exporter_enabled`|Set