finallycoffee/matrix-docker-ansible-deploy
finallycoffee/matrix-docker-ansible-deploy
5
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Compare commits

base: finallycoffee:master
Branches Tags
finallycoffee:master
finallycoffee:transcaffeine/patch-dumb-design-choices
finallycoffee:feat-mx-puppet-instagram
..
compare: finallycoffee:transcaffeine/patch-dumb-design-choices
Branches Tags
finallycoffee:master
finallycoffee:transcaffeine/patch-dumb-design-choices
finallycoffee:feat-mx-puppet-instagram

7 Commits
master ... transcaffe

Author SHA1 Message Date
Johanna Dorothea Reichmann
eb17814ddf
WIP: feat(synapse): sane defaults for compressing state without choking host CPU 2022-05-27 09:14:42 +02:00
Johanna Dorothea Reichmann
b784feb525
WIP: feat(postgres): actually use proper dump+restore procedure over psql misuse 2022-05-27 09:14:12 +02:00
Johanna Dorothea Reichmann
fe0668bb2f
fix: broken rhel/fedora tasks disabled 2022-05-19 08:42:03 +02:00
transcaffeine
f3bbb349d7
feat: add automatic creation of reverse-proxy routing 2022-05-19 08:42:02 +02:00
transcaffeine
21b5ff42a6
meta: move inventory structure to be more usable 2022-05-19 08:42:01 +02:00
jdreichmann
c38562abbf
meta: add own inventory, add vault-unlock with GPG 2022-05-19 08:42:00 +02:00
Johanna Dorothea Reichmann
7e4317b42a
feat(synapse): allow using multiple federation workers 2022-05-19 08:41:59 +02:00
1356 changed files with 28606 additions and 63062 deletions
Show Stats Expand all files Collapse all files

17
.config/ansible-lint.yml
View File

@ -1,17 +0,0 @@
---
use_default_rules: true
skip_list:
- unnamed-task
- no-handler
- no-jinja-nesting
- schema
- command-instead-of-shell
- role-name
- var-naming[no-role-prefix]
# We frequently load configuration from a template (into a variable), then merge that with another variable (configuration extension)
# before finally dumping it to a file.
- template-instead-of-copy
offline: true

8
.editorconfig
View File

@ -19,14 +19,6 @@ trim_trailing_whitespace = true
indent_style = space
indent_size = 2
[group_vars/matrix_servers]
indent_style = space
indent_size = 2
[justfile]
indent_style = space
indent_size = 4
# Markdown Files
#
# Two spaces at the end of a line in Markdown mean "new line",

1
.envrc
View File

@ -1 +0,0 @@
use flake

1
.gitattributes vendored
View File

@ -1 +0,0 @@
* text=auto eol=lf

23
.github/renovate.json vendored
View File

@ -1,23 +0,0 @@
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": [
"config:base"
],
"regexManagers": [
{
"fileMatch": ["defaults/main.yml$"],
"matchStrings": [
"# renovate: datasource=(?<datasource>[a-z-.]+?) depName=(?<depName>[^\\s]+?)(?: (?:lookupName|packageName)=(?<packageName>[^\\s]+?))?(?: versioning=(?<versioning>[a-z-0-9]+?))?\\s+[A-Za-z0-9_]+?(?:_version|_tag)\\s*:\\s*[\"']?(?<currentValue>.+?)[\"']?\\s"
]
}
],
"packageRules": [
{
"matchSourceUrlPrefixes": [
"https://github.com/devture/com.devture.ansible.role",
"https://github.com/mother-of-all-self-hosting"
],
"ignoreUnstable": false
}
]
}

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

@ -7,20 +7,10 @@ on: # yamllint disable-line rule:truthy
jobs:
yamllint:
name: yamllint
name: 🧹 yamllint
runs-on: ubuntu-latest
steps:
- name: Check out
uses: actions/checkout@v4
- name: Run yamllint
uses: frenck/action-yamllint@v1.5.0
ansible-lint:
name: ansible-lint
runs-on: ubuntu-latest
steps:
- name: Check out
uses: actions/checkout@v4
- name: Run ansible-lint
uses: ansible-community/ansible-lint-action@v6.17.0
with:
path: roles/custom
- name: ⤵️ Check out configuration from GitHub
uses: actions/checkout@v3
- name: 🚀 Run yamllint
uses: frenck/action-yamllint@v1.1.2

9
.gitignore vendored
View File

@ -1,10 +1,3 @@
/inventory
/roles/**/files/scratchpad
/roles/*/files/scratchpad
.DS_Store
.python-version
.idea/
.direnv/
# ignore roles pulled by ansible-galaxy
/roles/galaxy/*
!/roles/galaxy/.gitkeep

3
.yamllint
View File

@ -1,5 +1,8 @@
---
extends: default
ignore: |
roles/matrix-synapse/vars/workers.yml
rules:
line-length: disable

1772
CHANGELOG.md
View File

File diff suppressed because it is too large Load Diff

11
Makefile
View File

@ -1,11 +0,0 @@
.PHONY: roles lint
help: ## Show this help.
@grep -F -h "##" $(MAKEFILE_LIST) | grep -v grep | sed -e 's/\\$$//' | sed -e 's/##//'
roles: ## Pull roles
rm -rf roles/galaxy
ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force
lint: ## Runs ansible-lint against all roles in the playbook
ansible-lint roles/custom

273
README.md
View File

@ -13,168 +13,125 @@ We run all services in [Docker](https://www.docker.com/) containers (see [the co
[Installation](docs/README.md) (upgrades) and some maintenance tasks are automated using [Ansible](https://www.ansible.com/) (see [our Ansible guide](docs/ansible.md)).
## Self-hosting or Managed / SaaS
This Ansible playbook tries to make self-hosting and maintaining a Matrix server fairly easy. Still, running any service smoothly requires knowledge, time and effort.
If you like the [FOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) spirit of this Ansible playbook, but prefer to put the responsibility on someone else, you can also [get a managed Matrix server from etke.cc](https://etke.cc?utm_source=github&utm_medium=readme&utm_campaign=mdad) (both hosting and on-premises) - a service built on top of this Ansible playbook but with [additional components](https://etke.cc/help/extras/?utm_source=github&utm_medium=readme&utm_campaign=mdad) and [services](https://etke.cc/services/?utm_source=github&utm_medium=readme&utm_campaign=mdad) which all help you run a Matrix server with ease. Be advised that etke.cc operates on a subscription-based approach and there is no "just set up my server once and be done with it" option.
## Supported services
Using this playbook, you can get the following list of services configured on your server. Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
Using this playbook, you can get the following services configured on your server:
**Note**: the list below is exhaustive. It includes optional or even some advanced components that you will most likely not need.
- (optional, default) a [Synapse](https://github.com/matrix-org/synapse) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network
- (optional) a [Dendrite](https://github.com/matrix-org/dendrite) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse.
- (optional) [Amazon S3](https://aws.amazon.com/s3/) storage for Synapse's content repository (`media_store`) files using [Goofys](https://github.com/kahing/goofys)
- (optional, default) [PostgreSQL](https://www.postgresql.org/) database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible.
- (optional, default) a [coturn](https://github.com/coturn/coturn) STUN/TURN server for WebRTC audio/video calls
- (optional, default) free [Let's Encrypt](https://letsencrypt.org/) SSL certificate, which secures the connection to the Synapse server and the Element web UI
- (optional, default) an [Element](https://app.element.io/) ([formerly Riot](https://element.io/previously-riot)) web UI, which is configured to connect to your own Synapse server by default
- (optional) a [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server
- (optional, default) an [Exim](https://www.exim.org/) mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server)
- (optional, default) an [nginx](http://nginx.org/) web server, listening on ports 80 and 443 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md)
- (optional, advanced) the [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) REST authentication password provider module
- (optional, advanced) the [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) password provider module
- (optional, advanced) the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider module
- (optional, advanced) the [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) spam checker module
- (optional, advanced) the [Matrix Corporal](https://github.com/devture/matrix-corporal) reconciliator and gateway for a managed Matrix server
- (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/)
- (optional) the [mautrix-facebook](https://github.com/mautrix/facebook) bridge for bridging your Matrix server to [Facebook](https://facebook.com/)
- (optional) the [mautrix-twitter](https://github.com/mautrix/twitter) bridge for bridging your Matrix server to [Twitter](https://twitter.com/)
- (optional) the [mautrix-hangouts](https://github.com/mautrix/hangouts) bridge for bridging your Matrix server to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts)
- (optional) the [mautrix-googlechat](https://github.com/mautrix/googlechat) bridge for bridging your Matrix server to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat)
- (optional) the [mautrix-instagram](https://github.com/mautrix/instagram) bridge for bridging your Matrix server to [Instagram](https://instagram.com/)
- (optional) the [mautrix-signal](https://github.com/mautrix/signal) bridge for bridging your Matrix server to [Signal](https://www.signal.org/)
- (optional) the [beeper-linkedin](https://gitlab.com/beeper/linkedin) bridge for bridging your Matrix server to [LinkedIn](https://www.linkedin.com/)
- (optional) the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge for bridging your Matrix server to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat)
- (optional) the [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) bridge for bridging your Matrix server to [Discord](https://discordapp.com/)
- (optional) the [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) bridge for bridging your Matrix server to [Slack](https://slack.com/)
- (optional) the [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.)
- (optional) the [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) bridge for bridging Matrix to generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular
- (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS - see [docs/configuring-playbook-bridge-matrix-bridge-sms.md](docs/configuring-playbook-bridge-matrix-bridge-sms.md) for setup documentation
- (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 [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
- (optional) the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-instagram.md](docs/configuring-playbook-bridge-mx-puppet-instagram.md) for setup documentation
- (optional) the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge for Twitter-DMs ([Twitter](https://twitter.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-twitter.md](docs/configuring-playbook-bridge-mx-puppet-twitter.md) for setup documentation
- (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-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
- (optional) [Email2Matrix](https://github.com/devture/email2matrix) for relaying email messages to Matrix rooms - see [docs/configuring-playbook-email2matrix.md](docs/configuring-playbook-email2matrix.md) for setup documentation
- (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients - see [docs/configuring-playbook-dimension.md](docs/configuring-playbook-dimension.md) for setup documentation
- (optional) [Etherpad](https://etherpad.org), an open source collaborative text editor - see [docs/configuring-playbook-etherpad.md](docs/configuring-playbook-etherpad.md) for setup documentation
- (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform - see [docs/configuring-playbook-jitsi.md](docs/configuring-playbook-jitsi.md) for setup documentation
- (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) [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
- (optional) [Mjolnir](https://github.com/matrix-org/mjolnir), a moderation tool for Matrix - see [docs/configuring-playbook-bot-mjolnir.md](docs/configuring-playbook-bot-mjolnir.md) for setup documentation
- (optional) [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin), a web UI tool for administrating users and rooms on your Matrix server - see [docs/configuring-playbook-synapse-admin.md](docs/configuring-playbook-synapse-admin.md) for setup documentation
- (optional) [matrix-registration](https://github.com/ZerataX/matrix-registration), a simple python application to have a token based matrix registration - see [docs/configuring-playbook-matrix-registration.md](docs/configuring-playbook-matrix-registration.md) for setup documentation
- (optional) the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI - see [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) for setup documentation
- (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 [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.
Sticking with the defaults (which install a subset of the above components) is the best choice, especially for a new installation.
You can always re-run the playbook later to add or remove components.
### Homeserver
The homeserver is the backbone of your matrix system. Choose one from the following list.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [Synapse](https://github.com/element-hq/synapse) | ✓ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network | [Link](docs/configuring-playbook-synapse.md) |
| [Conduit](https://conduit.rs) | x | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Conduit is a lightweight open-source server implementation of the Matrix Specification with a focus on easy setup and low system requirements | [Link](docs/configuring-playbook-conduit.md) |
| [Dendrite](https://github.com/matrix-org/dendrite) | x | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse. | [Link](docs/configuring-playbook-dendrite.md) |
### Clients
Web clients for matrix that you can host on your own domains.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [Element](https://app.element.io/) | ✓ | Web UI, which is configured to connect to your own Synapse server by default | [Link](docs/configuring-playbook-client-element.md) |
| [Hydrogen](https://github.com/element-hq/hydrogen-web) | x | Lightweight matrix client with legacy and mobile browser support | [Link](docs/configuring-playbook-client-hydrogen.md) |
| [Cinny](https://github.com/ajbura/cinny) | x | Simple, elegant and secure web client | [Link](docs/configuring-playbook-client-cinny.md) |
| [SchildiChat](https://schildi.chat/) | x | Based on Element, with a more traditional instant messaging experience | [Link](docs/configuring-playbook-client-schildichat.md) |
### Server Components
Services that run on the server to make the various parts of your installation work.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [PostgreSQL](https://www.postgresql.org/)| ✓ | Database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible. | [Link](docs/configuring-playbook-external-postgres.md) |
| [Coturn](https://github.com/coturn/coturn) | ✓ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
| [Traefik](https://doc.traefik.io/traefik/) | ✓ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md) | [Link](docs/configuring-playbook-traefik.md) |
| [Let's Encrypt](https://letsencrypt.org/) | ✓ | Free SSL certificate, which secures the connection to all components | [Link](docs/configuring-playbook-ssl-certificates.md) |
| [ma1sd](https://github.com/ma1uta/ma1sd) | x | Matrix Identity Server | [Link](docs/configuring-playbook-ma1sd.md)
| [Exim](https://www.exim.org/) | ✓ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | [Link](docs/configuring-playbook-email.md) |
| [Dimension](https://github.com/turt2live/matrix-dimension) | x | An open source integrations manager for matrix clients | [Link](docs/configuring-playbook-dimension.md) |
| [Sygnal](https://github.com/matrix-org/sygnal) | x | Push gateway | [Link](docs/configuring-playbook-sygnal.md) |
| [ntfy](https://ntfy.sh) | x | Push notifications server | [Link](docs/configuring-playbook-ntfy.md) |
### Authentication
Extend and modify how users are authenticated on your homeserver.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) (advanced) | x | REST authentication password provider module | [Link](docs/configuring-playbook-rest-auth.md) |
|[matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) (advanced) | x | Password provider module | [Link](docs/configuring-playbook-shared-secret-auth.md) |
| [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) (advanced) | x | LDAP Auth password provider module | [Link](docs/configuring-playbook-ldap-auth.md) |
| [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) (advanced) | x | A proxy that handles Matrix registration requests and forwards them to LDAP. | [Link](docs/configuring-playbook-matrix-ldap-registration-proxy.md) |
| [matrix-registration](https://github.com/ZerataX/matrix-registration) | x | A simple python application to have a token based matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
### File Storage
Use alternative file storage to the default `media_store` folder.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [Goofys](https://github.com/kahing/goofys) | x | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3-goofys.md) |
| [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) | x | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3.md) |
| [matrix-media-repo](https://github.com/turt2live/matrix-media-repo) | x | matrix-media-repo is a highly customizable multi-domain media repository for Matrix. Intended for medium to large deployments, this media repo de-duplicates media while being fully compliant with the specification. | [Link](docs/configuring-playbook-matrix-media-repo.md) |
### Bridges
Bridges can be used to connect your matrix installation with third-party communication networks.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [mautrix-discord](https://github.com/mautrix/discord) | x | Bridge to [Discord](https://discord.com/) | [Link](docs/configuring-playbook-bridge-mautrix-discord.md) |
| [mautrix-slack](https://github.com/mautrix/slack) | x | Bridge to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-mautrix-slack.md) |
| [mautrix-telegram](https://github.com/mautrix/telegram) | x | Bridge to [Telegram](https://telegram.org/) | [Link](docs/configuring-playbook-bridge-mautrix-telegram.md) |
| [mautrix-gmessages](https://github.com/mautrix/gmessages) | x | Bridge to [Google Messages](https://messages.google.com/) | [Link](docs/configuring-playbook-bridge-mautrix-gmessages.md) |
| [mautrix-whatsapp](https://github.com/mautrix/whatsapp) | x | Bridge to [WhatsApp](https://www.whatsapp.com/) | [Link](docs/configuring-playbook-bridge-mautrix-whatsapp.md) |
| [mautrix-facebook](https://github.com/mautrix/facebook) | x | Bridge to [Facebook](https://facebook.com/) | [Link](docs/configuring-playbook-bridge-mautrix-facebook.md) |
| [mautrix-twitter](https://github.com/mautrix/twitter) | x | Bridge to [Twitter](https://twitter.com/) | [Link](docs/configuring-playbook-bridge-mautrix-twitter.md) |
| [mautrix-hangouts](https://github.com/mautrix/hangouts) | x | Bridge to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts) | [Link](docs/configuring-playbook-bridge-mautrix-hangouts.md) |
| [mautrix-googlechat](https://github.com/mautrix/googlechat) | x | Bridge to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat) | [Link](docs/configuring-playbook-bridge-mautrix-googlechat.md) |
| [mautrix-instagram](https://github.com/mautrix/instagram) | x | Bridge to [Instagram](https://instagram.com/) | [Link](docs/configuring-playbook-bridge-mautrix-instagram.md) |
| [mautrix-signal](https://github.com/mautrix/signal) | x | Bridge to [Signal](https://www.signal.org/) | [Link](docs/configuring-playbook-bridge-mautrix-signal.md) |
| [beeper-linkedin](https://github.com/beeper/linkedin) | x | Bridge to [LinkedIn](https://www.linkedin.com/) | [Link](docs/configuring-playbook-bridge-beeper-linkedin.md) |
| [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) | x | Bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-appservice-irc.md) |
| [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) | x | Bridge to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-appservice-discord.md) |
| [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) | x | Bridge to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-appservice-slack.md) |
| [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) | x | Bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.) | [Link](docs/configuring-playbook-bridge-appservice-webhooks.md) |
| [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) | x | Bridge for generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular | [Link](docs/configuring-playbook-bridge-hookshot.md) |
| [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) | x | Bridge to SMS | [Link](docs/configuring-playbook-bridge-matrix-bridge-sms.md) |
| [Heisenbridge](https://github.com/hifi/heisenbridge) | x | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-heisenbridge.md) |
| [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) | x | Bridge to [Skype](https://www.skype.com) | [Link](docs/configuring-playbook-bridge-go-skype-bridge.md) |
| [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) | x | Bridge to [Slack](https://slack.com) | [Link](docs/configuring-playbook-bridge-mx-puppet-slack.md) |
| [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) | x | Bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-instagram.md) |
| [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) | x | Bridge for Twitter-DMs ([Twitter](https://twitter.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-twitter.md) |
| [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) | x | Bridge to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-discord.md) |
| [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) | x | Bridge to [GroupMe](https://groupme.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-groupme.md) |
| [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) | x | Bridge to [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) |
| [Email2Matrix](https://github.com/devture/email2matrix) | x | Bridge for relaying emails to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) |
### Bots
Bots provide various additional functionality to your installation.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [baibot](https://github.com/etkecc/baibot) | x | A bot that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you | [Link](docs/configuring-playbook-bot-baibot.md) |
| [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) | x | Bot for scheduling one-off & recurring reminders and alarms | [Link](docs/configuring-playbook-bot-matrix-reminder-bot.md) |
| [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) | x | Bot for invitations by creating and managing registration tokens | [Link](docs/configuring-playbook-bot-matrix-registration-bot.md) |
| [maubot](https://github.com/maubot/maubot) | x | A plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) |
| [honoroit](https://github.com/etkecc/honoroit) | x | A helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) |
| [Postmoogle](https://github.com/etkecc/postmoogle) | x | Email to matrix bot | [Link](docs/configuring-playbook-bot-postmoogle.md) |
| [Go-NEB](https://github.com/matrix-org/go-neb) | x | A multi functional bot written in Go | [Link](docs/configuring-playbook-bot-go-neb.md) |
| [Mjolnir](https://github.com/matrix-org/mjolnir) | x | A moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) |
| [Draupnir](https://github.com/the-draupnir-project/Draupnir) | x | A moderation tool for Matrix (Fork of Mjolnir) | [Link](docs/configuring-playbook-bot-draupnir.md) |
| [Buscarron](https://github.com/etkecc/buscarron) | x | Web forms (HTTP POST) to matrix | [Link](docs/configuring-playbook-bot-buscarron.md) |
| [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) | x | ChatGPT from matrix | [Link](docs/configuring-playbook-bot-chatgpt.md) |
### Administration
Services that help you in administrating and monitoring your matrix installation.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) | x | A web UI tool for administrating users and rooms on your Matrix server | [Link](docs/configuring-playbook-synapse-admin.md) |
| Metrics and Graphs | x | Consists of the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI | [Link](docs/configuring-playbook-prometheus-grafana.md) |
| [Borg](https://borgbackup.org) | x | Backups | [Link](docs/configuring-playbook-backup-borg.md) |
| [Rageshake](https://github.com/matrix-org/rageshake) | x | Bug report server | [Link](docs/configuring-playbook-rageshake.md) |
| [synapse-usage-exporter](https://github.com/loelkes/synapse-usage-exporter) | x | Export the usage statistics of a Synapse homeserver to be scraped by Prometheus. | [Link](docs/configuring-playbook-synapse-usage-exporter.md) |
### Misc
Various services that don't fit any other category.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [sliding-sync](https://github.com/matrix-org/sliding-sync)| x | Sliding Sync support for clients which require it (e.g. Element X) | [Link](docs/configuring-playbook-sliding-sync-proxy.md) |
| [synapse_auto_accept_invite](https://github.com/matrix-org/synapse-auto-accept-invite) | x | A Synapse module to automatically accept invites. | [Link](docs/configuring-playbook-synapse-auto-accept-invite.md) |
| [synapse_auto_compressor](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) | x | A cli tool that automatically compresses `state_groups` database table in background. | [Link](docs/configuring-playbook-synapse-auto-compressor.md) |
| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | x | A spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
| [Matrix Corporal](https://github.com/devture/matrix-corporal) (advanced) | x | Reconciliator and gateway for a managed Matrix server | [Link](docs/configuring-playbook-matrix-corporal.md) |
| [Etherpad](https://etherpad.org) | x | An open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
| [Jitsi](https://jitsi.org/) | x | An open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
| [Cactus Comments](https://cactus.chat) | x | A federated comment system built on matrix | [Link](docs/configuring-playbook-cactus-comments.md) |
| [Pantalaimon](https://github.com/matrix-org/pantalaimon) | x | An E2EE aware proxy daemon | [Link](docs/configuring-playbook-pantalaimon.md) |
## Installation
To configure and install Matrix on your own server, follow the [README in the docs/ directory](docs/README.md).
@ -196,8 +153,6 @@ When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up w
- GitHub issues: [spantaleev/matrix-docker-ansible-deploy/issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues)
## Related
## Services by the community
You may also be interested in [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) - another Ansible playbook for self-hosting non-Matrix services (see its [List of supported services](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md)).
mash-playbook also makes use of [Traefik](./docs/configuring-playbook-traefik.md) as its reverse-proxy, so with minor [interoperability adjustments](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/interoperability.md), you can make matrix-docker-ansible-deploy and mash-playbook co-exist and host Matrix and non-Matrix services on the same server.
- [etke.cc](https://etke.cc) - matrix-docker-ansible-deploy and system stuff "as a service". That service will create your matrix homeserver on your domain and server (doesn't matter if it's cloud provider or on an old laptop in the corner of your room), (optional) maintains it (server's system updates, cleanup, security adjustments, tuning, etc.; matrix homeserver updates & maintenance) and (optional) provide full-featured email service for your domain

106
YEAR-IN-REVIEW.md
View File

@ -1,106 +0,0 @@
# 2023
2023 was a year filled with many changes for matrix-docker-ansible-deploy. In this post, we're looking backward at some of the major changes that happened this year, as well as taking a glimpse of what's ahead in 2024.
2023 is probably [the year of AI](https://journal.everypixel.com/2023-the-year-of-ai), with millions of people jumping aboard [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/chatgpt) train. matrix-docker-ansible-deploy is no stranger to this and 2023 began with a PR from [bertybuttface](https://github.com/bertybuttface) who added support for [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#chatgpt-support)). While OpenAI's chat GPT website was frequently overloaded in the past, their API was up which made using this bot both convenient and more reliable.
AI aside, with the playbook's focus being containers, we're **doubling down on being "container native"** and becoming more interoperable for people hosting other containers on the Matrix server. In [2022](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/YEAR-IN-REVIEW.md#2022), we've announced a few sibling Ansible playbooks, their use of [Traefik](https://doc.traefik.io/traefik/) and the possiblity of matrix-docker-ansible-deploy also switching to this reverse-proxy. This prediction materialized quickly. The **largest change** in the playbook in 2023 happened way back in February - matrix-docker-ansible-deploy [starting the switch from nginx to Traefik](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-reverse-proxy-configuration-changes-and-initial-traefik-support) and then quickly [making Treafik the default reverse-proxy](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#traefik-is-the-default-reverse-proxy-now). As noted in the changelog entries, we envisioned a quick and complete elimination of `matrix-nginx-proxy`, but at the end of 2023, it hasn't happened yet. The playbook is already using Traefik as the front-most reverse-proxy, but nginx (via `matrix-nginx-proxy`) is still around - it has taken a step back and is only used internally for new setups. Work got to a stall due to:
* complexity: untangling the overly large and messy `matrix-nginx-proxy` component is difficult
* the current setup became "good enough" because nginx has become an internal implementation detail for those who have migrated to Traefik. Traefik is already the default public reverse-proxy and gives better possibilities to people wishing to run other web-exposed containers on their Matrix server via [Docker Compose](https://docs.docker.com/compose/), other Ansible playbooks like [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) (more about this one, below) or any other way.
`matrix-nginx-proxy` is no longer in the way of us being interoperable, but its ugly internal details are still there. It is one more proxy in the long chain of reverse-proxies we have and we'd like to cut it out. This would both make things simpler and also boost performance.
The delay in eliminating `matrix-nginx-proxy` has probably been welcome by many existing users who decided to postpone the Traefik migration a bit longer. In 2024, work on eliminating `matrix-nginx-proxy` will continue with rapid pace. People who are still using `matrix-nginx-proxy` as their front-most reverse-proxy will need to rework their setup. About a year of putting it off has been long enough.
This large Traefik reverse-proxy change was also accompanied by another internal change which began in 2022, but continued in 2023 - **moving non-Matrix-related roles from being internal to the playbook to living their own life outside of it**. Various roles were made more decoupled and moved outside of the playbook, so that other projects (like the [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) Ansible playbook or other Ansible playbooks) could benefit from them. This led to the **death of a few sibling playbooks** ([gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy), [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy), [peertube-docker-ansible-deploy](https://github.com/spantaleev/peertube-docker-ansible-deploy), [vaultwarden-docker-ansible-deploy](https://github.com/spantaleev/vaultwarden-docker-ansible-deploy)), but brought life to something better, which supports all these services and more.
[mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) is a new Ansible playbook that a few of us (matrix-docker-ansible-deploy contributors) have launched in 2023. It has quickly grown to supports [60+ services](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md) and aims to do the same for [FOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) service hosting, as matrix-docker-ansible-deploy has done for Matrix - providing a clean and secure way to run a bunch of services in containers on a regular server (that is to say, without Kubernetes, etc.). Thanks to Traefik and Ansible role reuse, it's easy to host both mash-playbook services and matrix-docker-ansible-deploy services on the same server - see mash-playbook's [interoperability](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/interoperability.md) documentation page. If you've been looking for a holiday project or your New Year's Resolutions list contains "self-hosting more services", then you're welcome to give this new playbook a try and join its Matrix room ([#mash-playbook:devture.com](https://matrix.to/#/#mash-playbook:devture.com)).
Because many of the roles are now external to this playbook (defined in the [requirements.yml](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/da27655ef34999fa924bc0a5e641dbd9ba06f133/requirements.yml) file), running `make roles` (or better yet `just roles` via the [just tool](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#support-for-running-commands-via-just)) becomes a necessity each time one pulls playbook updates (`git pull`). Pulling external roles happens via the [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) command-line tool, but if available, the playbook would also use the much faster [agru](https://github.com/etkecc/agru) tool (developed by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/) this year).
With the internal (but important) details out of the way, we can now talk more about **new features that landed in matrix-docker-ansible-deploy in 2023**.
The following **new** **bridges** were added to the playbook in 2023:
* (2023-01-11) [mautrix-slack](https://mau.dev/mautrix/slack), thanks to a PR by [Cody Neiman](https://github.com/xangelix) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#mautrix-slack-support))
* (2023-07-21) [mautrix-gmessages](https://github.com/mautrix/gmessages), thanks to a PR by [Shreyas Ajjarapu](https://github.com/shreyasajj) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#mautrix-gmessages-support))
* (2023-08-23) [mautrix-wsproxy](https://github.com/mautrix/wsproxy) for Apple iMessage bridging (when combined with the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android phone), thanks to a PR by [Johan Swetzén](https://github.com/jswetzen)
This brings the total number of **[bridges that the playbook supports](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/docs/configuring-playbook.md#bridging-other-networks) up to 30**. There are alternative bridge implementations for various networks and protocols, so the number of "unique bridged networks" is surely much smaller.
A few other **major components and changes** landed in 2023:
* (2023-02-10) The [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation tool (successor to [Mjolnir](https://github.com/matrix-org/mjolnir)), thanks to a PR by [FSG-Cat](https://github.com/FSG-Cat) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#draupnir-moderation-tool-bot-support))
* (2023-02-10) [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) to add Matrix Authentication Support to our Jitsi setup, thanks to a PR by [Jakob S.](https://github.com/jakicoll) from [zakk gGmbH](https://github.com/zakk-it) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#matrix-authentication-support-for-jitsi))
* (2023-02-25) The [Rageshake](https://github.com/matrix-org/rageshake) bug report server, thanks to a PR by [Benjamin Kampmann](https://github.com/gnunicorn) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#rageshake-support))
* (2023-03-07) [Sliding Sync Proxy](https://github.com/matrix-org/sliding-sync) (currently a necessary component for [Element X](https://element.io/labs/element-x) to work), thanks to: [Benjamin Kampmann](https://github.com/gnunicorn) and [FSG-Cat](https://github.com/FSG-Cat) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#sliding-sync-proxy-element-x-support))
* (2023-03-12) synapse-auto-compressor to periodically and automatically run [rust-synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state), thanks to a PR by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#synapse-auto-compressor-support))
* (2023-07-17) [matrix-media-repo](https://github.com/turt2live/matrix-media-repo),  thanks to a PR by [Michael Hollister](https://github.com/Michael-Hollister) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#matrix-media-repo-support))
* (2023-08-31) [SchildiChat](https://github.com/SchildiChat/schildichat-desktop) client app (fork of [element-web)](https://github.com/element-hq/element-web), thanks to a PR by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#schildichat-support))
* (2023-10-18) Postgres parameters auto-tuning, thanks to a PR by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#postgres-parameters-are-automatically-tuned-now))
* (2023-10-23) Enabling federation of the room directory for Synapse (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#enabling-allow_public_rooms_over_federation-by-default-for-synapse))
The most recent change in the list above (Enabling federation of the room directory for Synapse) has been somewhat **controversial** as it goes against upstream defaults for Synapse. Nevertheless, we believe it **promotes the well-being of the Matrix Federation by improving room discovery**.
**Matrix Federation Stats** (containing the percentage of servers publishing their room directory publicly) are posted to [TWIM](https://matrix.org/category/this-week-in-matrix/) each week by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/). The number of servers which [currently published their room directory publicly](https://matrix.org/blog/2023/12/2/this-week-in-matrix-2023-12-22/#matrix-federation-stats) stands at `26.6%`, which is:
- **2.4% more** than when it was when [first published to TWIM](https://matrix.org/blog/2023/11/03/this-week-in-matrix-2023-11-03/#matrix-federation-stats) (1 month earlier, in November)
- likely about **15+% more** than from before we flipped the switch (in October)
Hopefully, Synapse defaults would also change the same way and we'd see the number of servers publicly listing their room directory grow faster.
With this configuration change in place, projects like [MatrixRooms.info](https://matrixrooms.info/) (made by [etke.cc](https://etke.cc/)) and potentially others in the future, can discover, index the metadata (room address, title, topic, number of users, etc.) and make public rooms browsable & searchable across the whole Matrix Federation. It'd be great if users joining Matrix could more easily find interesting communities that match their interests!
On the **media side of things**, besides Jitsi getting better Matrix integration (via the aforementioned Matrix User Verification Service), we've also had some [Coturn security tightening](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues) as well as [performance optimizations](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#coturn-can-now-use-host-networking) for configurations exposing lots of network ports.
[Element Call](https://github.com/element-hq/element-call) seems to have become a nice and polished product lately (as proclaimed in [The Matrix Holiday Update 2023](https://matrix.org/blog/2023/12/25/the-matrix-holiday-update-2023/)), so 2024 is likely the year we'll see support for it in the playbook. Element Call depends on the [LiveKit](https://livekit.io/) streaming server (which is also useful to developers even by itself), so the first step is likely to see LiveKit support in mash-playbook via a reusable Ansible role. Such a LiveKit Ansible role could later easily land in matrix-docker-ansible-deploy and an Element Call static website could be hooked to it.
Besides these highlights, there were many other relatively large changes announced in our [CHANGELOG](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md) and hundreds of other more minor (but still important) playbook changes that didn't get a mention.
We have **hundreds of contributors to thank for their hard work** on making Matrix self-hosting better for all of us! It should be noted that **support comes in many shapes**, not only in raw code commits and financial help (via [donations](https://liberapay.com/s.pantaleev) or using the [etke.cc managed Matrix hosting service](https://etke.cc/) which is based on matrix-docker-ansible-deploy). It also comes in the shape of code reviews, helping others with [issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues), reporting new issues, participating in our support room on Matrix ([#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com)), etc. To everyone who has been there to make matrix-docker-ansible-deploy better in 2023, thank you! 🙇‍♂️
# 2022
For [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy/), 2022 started with **breaking the** [**Synapse**](https://github.com/element-hq/synapse) **monopoly** by [adding support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#dendrite-support) for the [Dendrite](https://github.com/matrix-org/dendrite) Matrix homeserver in early January. This required various internal changes so that the [Ansible](https://www.ansible.com/) playbook would not be Synapse-centric anymore. This groundwork paved the way for continuing in this direction and we [added support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#conduit-support) for [Conduit](https://conduit.rs/) in August.
When it comes to the `matrix-docker-ansible-deploy` Ansible playbook, 2022 was the year of the non-Synapse homeserver implementation. In practice, none of these homeserver implementations seem ready for prime-time yet and there is no migration path when coming from Synapse. Having done our job of adding support for these alternative homeserver implementations, we can say that we're not getting in the way of future progress. It's time for the Dendrite developers to push harder (development-wise) and for the Synapse developers to take a well-deserved long (infinite) break, and we may get to see more people migrating away from Synapse in the next year(s).
Support for the following new **bridges** was added:
* [Postmoogle](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#postmoogle-email-bridge-support) for bi-directional email bridging, which supersedes my old and simplistic [email2matrix](https://github.com/devture/email2matrix) one-way bridge-bot
* [mautrix-discord](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#mautrix-discord-support)
* [go-skype-bridge](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#go-skype-bridge-bridging-support)
* [matrix-appservice-kakaotalk](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix-appservice-kakaotalk-support)
Support for the following new **bots** was added:
* [buscarron bot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#buscarron-bot-support)
* [Honoroit bot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#honoroit-bot-support)
* [matrix-registration-bot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix-registration-bot-support)
* [matrix-hookshot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix-hookshot-bridging-support)
* [maubot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#maubot-support)
Support for the following new **components and services** was added:
* [Borg backup](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#borg-backup-support)
* [Cactus Comments](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#cactus-comments-support)
* [Cinny](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#cinny-support) client support
* [ntfy](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#ntfy-push-notifications-support) notifications
* [matrix-ldap-registration-proxy](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix-ldap-registration-proxy-support)
* [matrix\_encryption\_disabler support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix_encryption_disabler-support)
* [synapse-s3-storage-provider](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#synapse-s3-storage-provider-support) to stop the Synapse media store from being a scalability problem. This brought along [another feature](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#synapse-container-image-customization-support) - an easier way to customize the Synapse container image without having to fork and self-build all of it from scratch
Besides these major user-visible changes, a lot of work also happened **under the hood**:
* we made [major improvements to Synapse workers](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#potential-backward-compatibility-break-major-improvements-to-synapse-workers) - adding support for stream writers and for running multiple workers of various kinds (federation senders, pushers, background task processing workers, etc.)
* we [improved the compatibility of (Synapse + workers) with the rest of the playbook](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#backward-compatibility-break-changing-how-reverse-proxying-to-synapse-works---now-via-a-matrix-synapse-reverse-proxy-companion-service) by introducing a new `matrix-synapse-reverse-proxy-companion-service` service
* we started [splitting various Ansible roles out of the Matrix playbook and into independent roles](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#the-playbook-now-uses-external-roles-for-some-things) (e.g. `matrix-postgres` -> [com.devture.ansible.role.postgres](https://github.com/devture/com.devture.ansible.role.postgres)), which could be included in other Ansible playbooks. In fact, these roles already power a few **interesting other sibling playbooks**:
* [gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy), for deploying a [Gitea](https://gitea.io/) (self-hosted [Git](https://git-scm.com/) service) server
* [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy), for deploying a [Nextcloud](https://nextcloud.com/) groupware server
* [vaultwarden-docker-ansible-deploy](https://github.com/spantaleev/vaultwarden-docker-ansible-deploy), for deploying a [Vaultwarden](https://github.com/dani-garcia/vaultwarden) password manager server (unofficial [Bitwarden](https://bitwarden.com/) compatible server)
These sibling playbooks co-exist nicely with one another due to using [Traefik](https://traefik.io/) for reverse-proxying, instead of trying to overtake the whole server by running their own [nginx](https://nginx.org/) reverse-proxy. Hopefully soon, the Matrix playbook will follow suit and be powered by Traefik by default.
Last, but not least, to optimize our [etke.cc managed Matrix hosting service](https://etke.cc/)'s performance (but also individual Ansible playbook runs for people self-hosting by themselves using the playbook), we've [improved playbook runtime 2-5x](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) by employing various Ansible tricks.

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

@ -1,32 +0,0 @@
#!/usr/bin/env bash
#
# Run the playbook on multiple hosts with different credentials with this script
# It defaults to ansible tags "setup-all,start". You can pass alternative tags
# to this script as arguments, e.g.
#
# ./bin/ansible-all-hosts.sh self-check
#
# set playbook root path
root=$(dirname "$(readlink -f "$0")")/..
# set default tags or get from first argument if any
tags="${1:-setup-all,start}"
# init password array
declare -A pws
# capture passwords for all hosts
for host in "$root"/inventory/*.yml; do
read -rp "sudo password for $(basename "$host"): " -s pw
pws[$host]="$pw"
echo
done
# run ansible on all captured passwords/hosts
for host in "${!pws[@]}"; do
ansible-playbook "$root"/setup.yml \
--inventory-file "$host" \
--extra-vars "ansible_become_pass=${pws[$host]}" \
--tags="$tags"
done

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

@ -1,39 +0,0 @@
#!/bin/bash
set -euxo pipefail
# This script rebuilds the mautrix-meta-instagram Ansible role, using the mautrix-meta-messenger role as a source.
if [ $# -eq 0 ]; then
echo "Error: No argument supplied. Please provide the path to the roles/custom directory."
exit 1
fi
roles_path=$1
messenger_role_path=$roles_path/matrix-bridge-mautrix-meta-messenger
instagram_role_path=$roles_path/matrix-bridge-mautrix-meta-instagram
if [ ! -d $messenger_role_path ]; then
echo "Cannot find: $messenger_role_path"
exit 1
fi
if [ -d $instagram_role_path ]; then
rm -rf $instagram_role_path
fi
cp -ar $messenger_role_path $instagram_role_path
find "$instagram_role_path" -type f | while read -r file; do
sed --in-place 's/matrix_mautrix_meta_messenger_/matrix_mautrix_meta_instagram_/g' "$file"
sed --in-place 's/mautrix-meta-messenger/mautrix-meta-instagram/g' "$file"
done
sed --in-place 's/matrix_mautrix_meta_instagram_meta_mode: \(.*\)/matrix_mautrix_meta_instagram_meta_mode: instagram/g' $instagram_role_path/defaults/main.yml
sed --in-place 's/matrix_mautrix_meta_instagram_identifier: \(.*\)/matrix_mautrix_meta_instagram_identifier: matrix-mautrix-meta-instagram/g' $instagram_role_path/defaults/main.yml
echo "# matrix-mautrix-meta-instagram" > $instagram_role_path/README.md
echo "" >> $instagram_role_path/README.md
echo "This bridge role is derived from the matrix-mautrix-meta-messenger Ansible role via automatic changes (see \`just rebuild-mautrix-meta-instagram\` or \`bin/rebuild-mautrix-meta-instagram.sh\`)." >> $instagram_role_path/README.md
echo "" >> $instagram_role_path/README.md
echo "If you'd like to make a change to this role, consider making it to the \`matrix-mautrix-meta-messenger\` role instead." >> $instagram_role_path/README.md

20
docs/alternative-architectures.md
View File

@ -1,18 +1,26 @@
# Alternative architectures
As stated in the [Prerequisites](prerequisites.md), currently only `amd64` (`x86_64`) is fully supported.
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.
The playbook automatically determines the target server's architecture (the `matrix_architecture` variable) to be one of the following:
To that end add the following variable to your `vars.yml` file (see [Configuring playbook](configuring-playbook.md)):
- `amd64` (`x86_64`)
- `arm32`
```yaml
matrix_architecture: <your-matrix-server-architecture>
```
Currently supported architectures are the following:
- `amd64` (the default)
- `arm64`
- `arm32`
Some tools and container images can be built on the host or other measures can be used to install on that architecture.
so for the Raspberry Pi, the following should be in your `vars.yml` file:
```yaml
matrix_architecture: "arm32"
```
## Implementation details
For `amd64`, prebuilt container images (see the [container images we use](container-images.md)) are used for all components (except [Hydrogen](configuring-playbook-client-hydrogen.md), which goes through self-building).
For other architecture (`arm64`, `arm32`), components which have a prebuilt image make use of it. If the component is not available for the specific architecture, [self-building](self-building.md) will be used. Not all components support self-building though, so your mileage may vary.
For other architectures, components which have a prebuilt image make use of it. If the component is not available for the specific architecture, [self-building](self-building.md) will be used. Not all components support self-building though, so your mileage may vary.

82
docs/ansible.md
View File

@ -9,14 +9,19 @@ If your local computer cannot run Ansible, you can also run Ansible on some serv
## Supported Ansible versions
Ansible 2.7.1 or newer is required ([last discussion about Ansible versions](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/743)).
Note: Ubuntu 20.04 ships with Ansible 2.9.6 which is a buggy version (see this [bug](https://bugs.launchpad.net/ubuntu/+source/ansible/+bug/1880359)), which can't be used in combination with a host running new systemd (more details in [#517](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/517), [#669](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/669)). If this problem affects you, you can: avoid running Ubuntu 20.04 on your host; run Ansible from another machine targeting your host; or try to upgrade to a newer Ansible version (see below).
## Checking your Ansible version
In most cases, you won't need to worry about the Ansible version.
The playbook will try to detect it and tell you if you're on an unsupported version.
To manually check which version of Ansible you're on, run: `ansible --version`.
For the **best experience**, we recommend getting the **latest version of Ansible available**.
We're not sure what's the minimum version of Ansible that can run this playbook successfully.
The lowest version that we've confirmed (on 2022-11-26) to be working fine is: `ansible-core` (`2.11.7`) combined with `ansible` (`4.10.0`).
If your distro ships with an Ansible version older than this, you may run into issues. Consider [Upgrading Ansible](#upgrading-ansible) or [using Ansible via Docker](#using-ansible-via-docker).
If you're on an old version of Ansible, you should [upgrade Ansible to a newer version](#upgrading-ansible) or [use Ansible via Docker](#using-ansible-via-docker).
## Upgrading Ansible
@ -25,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/installation/) (`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/installing/) (`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.
@ -36,49 +41,9 @@ If you find yourself needing to resort to such hacks, please consider reporting
## Using Ansible via Docker
Alternatively, you can run Ansible inside a Docker container (powered by the [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
Alternatively, you can run Ansible on your computer from inside a Docker container (powered by the [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
This ensures that you're using a very recent Ansible version, which is less likely to be incompatible with the playbook.
You can either [run Ansible in a container on the Matrix server itself](#running-ansible-in-a-container-on-the-matrix-server-itself) or [run Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server).
### 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_playbook_docker_installation_enabled: false` in your `vars.yml` file, to prevent the playbook from installing Docker
- **or** you need to run the playbook in another way (e.g. [Running Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server)) at least the first time around
Once you have a working Docker installation on the server, **clone the playbook** somewhere on the server and configure it as per usual (`inventory/hosts`, `inventory/host_vars/..`, etc.), as described in [configuring the playbook](configuring-playbook.md).
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.17.0-r0-1
```
Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container.
The `/work` directory contains the playbook's code.
First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
Finally, you can execute `ansible-playbook ...` (or `ansible-playbook --connection=community.docker.nsenter ...`) commands as per normal now.
### Running Ansible in a container on another computer (not the Matrix server)
Run this from the playbook's directory:
Here's a sample command to get you started (run this from the playbook's directory):
```bash
docker run -it --rm \
@ -86,7 +51,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.17.0-r0-1
docker.io/devture/ansible:2.11.6-r1
```
The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`).
@ -95,12 +60,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.
First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
You can execute `ansible-playbook` commands as per normal now.
Finally, you execute `ansible-playbook ...` commands as per normal now.
#### If you don't use SSH keys for authentication
### If you don't use SSH keys for authentication
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:
@ -109,13 +71,3 @@ apk add sshpass
```
Then, to be asked for the password whenever running an `ansible-playbook` command add `--ask-pass` to the arguments of the command.
#### Resolve directory ownership issues
Because you're `root` in the container running Ansible and this likely differs fom the owner (your regular user account) of the playbook directory outside of the container, certain playbook features which use `git` locally may report warnings such as:
> fatal: unsafe repository ('/work' is owned by someone else)
> To add an exception for this directory, call:
> git config --global --add safe.directory /work
These errors can be resolved by making `git` trust the playbook directory by running `git config --global --add safe.directory /work`

37
docs/configuring-captcha.md
View File

@ -1,12 +1,10 @@
(Adapted from the [upstream project](https://github.com/element-hq/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
(Adapted from the [upstream project](https://github.com/matrix-org/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
# Overview
Captcha can be enabled for this home server. This file explains how to do that.
The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead.
The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google.
## ReCaptcha
### Getting keys
## Getting keys
Requires a site/secret key pair from:
@ -14,39 +12,12 @@ Requires a site/secret key pair from:
Must be a reCAPTCHA **v2** key using the "I'm not a robot" Checkbox option
### Setting ReCaptcha keys
## Setting ReCaptcha Keys
Once registered as above, set the following values:
```yaml
# for Synapse
matrix_synapse_enable_registration_captcha: true
matrix_synapse_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_synapse_recaptcha_private_key: 'YOUR_SECRET_KEY'
# for Dendrite
matrix_dendrite_client_api_enable_registration_captcha: true
matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
```
## hCaptcha
### Getting keys
Requires a site/secret key pair from:
<https://dashboard.hcaptcha.com/sites/new>
### Setting hCaptcha keys
```yaml
matrix_dendrite_client_api_enable_registration_captcha: true
matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
matrix_dendrite_client_api_recaptcha_siteverify_api: 'https://hcaptcha.com/siteverify'
matrix_dendrite_client_api_recaptcha_api_js_url: 'https://js.hcaptcha.com/1/api.js'
matrix_dendrite_client_api_recaptcha_form_field: 'h-captcha-response'
matrix_dendrite_client_api_recaptcha_sitekey_class: 'h-captcha'
```

51
docs/configuring-dns.md
View File

@ -26,37 +26,25 @@ Be mindful as to how long it will take for the DNS records to propagate.
If you are using Cloudflare DNS, make sure to disable the proxy and set all records to `DNS only`. Otherwise, fetching certificates will fail.
When you're done configuring DNS, proceed to [Configuring the playbook](configuring-playbook.md).
## DNS settings for optional services/features
| Used by component | Type | Host | Priority | Weight | Port | Target |
| ----------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | -------- | ------ | ---- | --------------------------- |
| [ma1sd](configuring-playbook-ma1sd.md) identity server | SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.<your-domain>` |
| [Dimension](configuring-playbook-dimension.md) integration server | CNAME | `dimension` | - | - | - | `matrix.<your-domain>` |
| [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform | CNAME | `jitsi` | - | - | - | `matrix.<your-domain>` |
| [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system | CNAME | `stats` | - | - | - | `matrix.<your-domain>` |
| [Go-NEB](configuring-playbook-bot-go-neb.md) bot | CNAME | `goneb` | - | - | - | `matrix.<your-domain>` |
| [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.<your-domain>` |
| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.<your-domain>` |
| [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
| [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.<your-domain>` |
| [SchildiChat](configuring-playbook-client-schildichat.md) web client | CNAME | `schildichat` | - | - | - | `matrix.<your-domain>` |
| [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge | CNAME | `wsproxy` | - | - | - | `matrix.<your-domain>` |
| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.<your-domain>` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX | `matrix` | 10 | 0 | - | `matrix.<your-domain>` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `matrix` | - | - | - | `v=spf1 ip4:<your-ip> -all` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `postmoogle._domainkey.matrix` | - | - | - | get it from `!pm dkim` |
When setting up a SRV record, if you are asked for a service and protocol instead of a hostname split the host value from the table where the period is. For example use service as `_matrix-identity` and protocol as `_tcp`.
| Type | Host | Priority | Weight | Port | Target |
| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
| SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.<your-domain>` |
| CNAME | `dimension` | - | - | - | `matrix.<your-domain>` |
| CNAME | `jitsi` | - | - | - | `matrix.<your-domain>` |
| CNAME | `stats` | - | - | - | `matrix.<your-domain>` |
| CNAME | `goneb` | - | - | - | `matrix.<your-domain>` |
| CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
| CNAME | `cinny` | - | - | - | `matrix.<your-domain>` |
| CNAME | `buscarron` | - | - | - | `matrix.<your-domain>` |
## Subdomains setup
As the table above illustrates, you need to create 2 subdomains (`matrix.<your-domain>` and `element.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` record is fine).
The `element.<your-domain>` subdomain may be necessary, because this playbook installs the [Element](https://github.com/element-hq/element-web) web client for you.
The `element.<your-domain>` subdomain may be necessary, because this playbook installs the [Element](https://github.com/vector-im/element-web) web client for you.
If you'd rather instruct the playbook not to install Element (`matrix_client_element_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `element.<your-domain>` DNS record.
The `dimension.<your-domain>` subdomain may be necessary, because this playbook could install the [Dimension integrations manager](http://dimension.t2bot.io/) for you. Dimension installation is disabled by default, because it's only possible to install it after the other Matrix services are working (see [Setting up Dimension](configuring-playbook-dimension.md) later). If you do not wish to set up Dimension, feel free to skip the `dimension.<your-domain>` DNS record.
@ -69,17 +57,11 @@ 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 `etherpad.<your-domain>` subdomain may be necessary, because this playbook could install the [Etherpad](https://etherpad.org/) a highly customizable open source online editor providing collaborative editing in really real-time. The installation of etherpad is disabled by default, it is not a core required component. To learn how to install it, see our [configuring etherpad guide](configuring-playbook-etherpad.md). If you do not wish to set up etherpad, feel free to skip the `etherpad.<your-domain>` DNS record.
The `hydrogen.<your-domain>` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/element-hq/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 `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 `wsproxy.<your-domain>` subdomain may be necessary, because this playbook could install the [wsproxy](https://github.com/mautrix/wsproxy) web client. The installation of wsproxy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring wsproxy guide](configuring-playbook-bridge-mautrix-wsproxy.md). If you do not wish to set up wsproxy, feel free to skip the `wsproxy.<your-domain>` DNS record.
The `buscarron.<your-domain>` subdomain may be necessary, because this playbook could install the [buscarron](https://github.com/etkecc/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.
The `buscarron.<your-domain>` subdomain may be necessary, because this playbook could install the [buscarron](https://github.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
@ -92,8 +74,3 @@ This is an optional feature for the optionally-installed [ma1sd service](configu
Note: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
When you're done with the DNS configuration and ready to proceed, continue with [Getting the playbook](getting-the-playbook.md).
## `_dmarc`, `postmoogle._domainkey` TXT and `matrix` MX records setup
To make the [postmoogle](configuring-playbook-bot-postmoogle.md) email bridge enable its email sending features, you need to configure
SPF (TXT), DMARC (TXT), DKIM (TXT) and MX records

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

@ -1,93 +0,0 @@
# Setting up matrix-alertmanager-receiver (optional)
The playbook can install and configure the [matrix-alertmanager-receiver](https://github.com/metio/matrix-alertmanager-receiver) service for you. It's a [client](https://prometheus.io/docs/alerting/latest/clients/) for Prometheus' [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/), allowing you to deliver alerts to Matrix rooms.
See the project's [documentation](https://github.com/metio/matrix-alertmanager-receiver) to learn more about what this component does and why it might be useful to you.
At the moment, **setting up this service's bot requires some manual actions** as described below in [Account and room preparation](#account-and-room-preparation).
This service is meant to be used with an external [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) instance. It's **not** meant to be integrated with the [Prometheus & Grafana stack](./configuring-playbook-prometheus-grafana.md) installed by this playbook, because the Alertmanager component is not installed by it.
## Configuration
```yml
matrix_alertmanager_receiver_enabled: true
# This exposes matrix-alertmanager-receiver on the `matrix.` domain.
# Adjust, if necessary.
matrix_alertmanager_receiver_hostname: "{{ matrix_server_fqn_matrix }}"
# This exposes matrix-alertmanager-receiver under a path prefix containing a random (secret) value.
# Adjust the `RANDOM_VALUE_HERE` part with a long and secure value.
matrix_alertmanager_receiver_path_prefix: /matrix-alertmanager-receiver-RANDOM_VALUE_HERE
# If you'd like to change the username for this bot, uncomment and adjust. Otherwise, remove.
# matrix_alertmanager_receiver_config_matrix_user_id_localpart: "bot.alertmanager.receiver"
# Specify the bot user's access token here.
# See the "Account and room preparation" section below.
matrix_alertmanager_receiver_config_matrix_access_token: ''
# Optionally, configure some mappings (URL-friendly room name -> actual Matrix room ID).
#
# If you don't configure mappings, you can still deliver alerts using URLs like this:
# https://matrix.DOMAIN/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!some-room-id:example.com
#
# If a mapping like the one below is configured, you can deliver alerts using friendlier URLs like this:
# https://matrix.DOMAIN/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name
matrix_alertmanager_receiver_config_matrix_room_mapping:
some-room-name: "!some-room-id:{{ matrix_domain }}"
```
See `roles/custom/matrix-alertmanager-receiver/defaults/main.yml` for additional configuration variables.
## Account and room preparation
The playbook can automatically create users, but it cannot automatically obtain access tokens, nor perform any of the other manual actions below.
`matrix-alertmanager-receiver` uses a bot (with a username specified in `matrix_alertmanager_receiver_config_matrix_user_id_localpart` - see above) for delivering messages. You need to **manually register this bot acccount and obtain an access token for it**.
1. [Register a new user](registering-users.md): `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.alertmanager.receiver password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user`
2. [Obtain an access token](obtaining-access-tokens.md) for the bot's user account
3. Invite the bot to a room where you'd like to alerts to be delivered
4. Log in as the bot using any Matrix client of your choosing, accept the room invitation from the bot's account and log out
5. (Optionally) Adjust `matrix_alertmanager_receiver_config_matrix_room_mapping` to create a mapping between the new room and its id
Steps 1 and 2 above only need to be done once, while preparing your [configuration](#configuration).
Steps 3 and 4 need to be done for each new room you'd like the bot to deliver alerts to. Step 5 is optional and provides cleaner `/alert/` URLs.
## Installation
Now that you've [prepared the bot account and room](#account-and-room-preparation) and have [configured the playbook](#configuration), you can re-run the [installation](./installing.md) process (`just install-all`).
Then, you can proceed to [Usage](#usage).
## Usage
Configure your Prometheus Alertmanager with configuration like this:
```yml
receivers:
- name: matrix
webhook_configs:
- send_resolved: true
url: URL_HERE
route:
group_by:
- namespace
group_interval: 5m
group_wait: 30s
receiver: "matrix"
repeat_interval: 12h
routes:
- receiver: matrix
```
.. where `URL_HERE` looks like `https://matrix.DOMAIN/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name` or `https://matrix.DOMAIN/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!some-room-id:DOMAIN`.
This bot does **not** accept room invitations automatically (like many other bots do). To deliver messages to rooms, **the bot must be joined to all rooms manually** - see Step 5 of the [Account and room preparation](#account-and-room-preparation) section.

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

@ -1,15 +0,0 @@
# Setting up Appservice Double Puppet (optional)
Appservice Double Puppet is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
This is useful for performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) via the [appservice method](https://docs.mau.fi/bridges/general/double-puppeting.html#appservice-method-new). The Appservice Double Puppet service is an implementation of this approach.
Previously, bridges supported performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method.
To enable the Appservice Double Puppet service, adjust your `vars.yml` configuration like this and [re-run the playbook](./installing.md) (`just install-all`):
```yml
matrix_appservice_double_puppet_enabled: true
```
When enabled, double puppeting will automatically be enabled for all bridges that support double puppeting via the appservice method.

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

@ -1,100 +0,0 @@
# Setting up Draupnir for All/D4A (optional)
The playbook can install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation tool for you in appservice mode.
Appservice mode can be used together with the regular [Draupnir bot](configuring-playbook-bot-draupnir.md) or independently. Details about the differences between the 2 modes are described below.
## Draupnir Appservice mode compared to Draupnir bot mode
The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode except in the case of avatar customisation as described later on in this document.
Draupnir for all is the way to go if you need more than 1 Draupnir instance, but you don't need access to Synapse Admin features as they are not accessible through Draupnir for All (Even though the commands do show up in help).
Draupnir for all in the playbook is rate-limit-exempt automatically as its appservice configuration file does not specify any rate limits.
Normal Draupnir does come with the benefit of access to Synapse Admin features. You are also able to more easily customise your normal Draupnir than D4A as D4A even on the branch with the Avatar command (To be Upstreamed to Mainline Draupnir) that command is clunky as it requires the use of things like Element devtools. In normal draupnir this is a quick operation where you login to Draupnir with a normal client and set Avatar and Display name normally.
Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
## Installation
### 1. Create a main management room.
The playbook does not create a management room for your Main Draupnir. This task you have to do on your own.
The management room has to be given an alias and be public when you are setting up the bot for the first time as the bot does not differentiate between invites
and invites to the management room.
This management room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element calls this powerlevel.
As noted in the Draupnir install instructions the control room is sensitive. The following is said about the control room in the Draupnir install instructions.
>Anyone in this room can control the bot so it is important that you only invite trusted users to this room. The room must be unencrypted since the playbook does not support installing Pantalaimon yet.
### 2. Give your main management room an alias.
Give the room from step 1 an alias. This alias can be anything you want and its recommended for increased security during the setup phase of the bot that you make this alias be a random string. You can give your room a secondary human readable alias when it has been locked down after setup phase.
### 3. Adjusting the playbook configuration.
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
You must replace `ALIAS_FROM_STEP_2_GOES_HERE` with the alias you created in step 2.
```yaml
matrix_appservice_draupnir_for_all_enabled: true
matrix_appservice_draupnir_for_all_master_control_room_alias: "ALIAS_FROM_STEP_2_GOES_HERE"
```
### 4. Installing
After configuring the playbook, run the [installation](installing.md) command:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:matrix-homeserver-domain` you have succesfully installed Draupnir for All and can now start using it.
The installation of Draupnir for all in this playbook is very much Alpha quality. Usage-wise, Draupnir for allis almost identical to Draupnir bot mode.
### 1. Granting Users the ability to use D4A
Draupnir for all includes several security measures like that it only allows users that are on its allow list to ask for a bot. To add a user to this list we have 2 primary options. Using the chat to tell Draupnir to do this for us or if you want to automatically do it by sending `m.policy.rule.user` events that target the subject you want to allow provisioning for with the `org.matrix.mjolnir.allow` recomendation. Using the chat is recomended.
The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297))
To allow users or whole homeservers you type /plain @draupnir-main:matrix-homeserver-domain allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
### 2. How to provision a D4A once you are allowed to.
Open a DM with @draupnir-main:matrix-homeserver-domain and if using Element send a message into this DM to finalise creating it. The bot will reject this invite and you will shortly get invited to the Draupnir control room for your newly provisioned Draupnir. From here its just a normal Draupnir experience.
Congratulations if you made it all the way here because you now have a fully working Draupnir for all deployment.
### Configuration of D4A
You can refer to the upstream [documentation](https://github.com/the-draupnir-project/Draupnir) for more configuration documentation. Please note that the playbook ships a full copy of the example config that does transfer to provisioned draupnirs in the production-bots.yaml.j2 file in the template directory of the role.
Please note that Config extension does not affect the appservices config as this config is not extensible in current Draupnir anyways. Config extension instead touches the config passed to the Draupnirs that your Appservice creates. So for example below makes all provisioned Draupnirs protect all joined rooms.
You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file.
For example to change draupnir's `protectAllJoinedRooms` option to `true` you would add the following to your `vars.yml` file.
```yaml
matrix_appservice_draupnir_for_all_extension_yaml: |
# Your custom YAML configuration goes here.
# This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_yaml`).
#
# You can override individual variables from the default configuration, or introduce new ones.
#
# If you need something more special, you can take full control by
# completely redefining `matrix_appservice_draupnir_for_all_yaml`.
protectAllJoinedRooms: true
```

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

@ -6,9 +6,9 @@ That means your daily incremental backups can be stored in a fraction of the spa
You will need a remote server where borg will store the backups. There are hosted, borg compatible solutions available, such as [BorgBase](https://www.borgbase.com).
The backup will run based on `backup_borg_schedule` var (systemd timer calendar), default: 4am every day.
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 `backup_borg_postgresql_enabled` variable.
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
@ -38,33 +38,27 @@ cat PUBKEY | ssh USER@HOST 'dd of=.ssh/authorized_keys oflag=append conv=notrunc
Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable borg backup:
```yaml
backup_borg_enabled: true
backup_borg_location_repositories:
- ssh://USER@HOST/./REPO
backup_borg_storage_encryption_passphrase: "PASSPHRASE"
backup_borg_ssh_key_private: |
-----BEGIN OPENSSH PRIVATE KEY-----
TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZW
xpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRv
bG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3
RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXgg
ZWEgY29tbW9kbyBjb25zZXF1YXQuIA==
-----END OPENSSH PRIVATE KEY-----
matrix_backup_borg_enabled: true
matrix_backup_borg_location_repositories:
- USER@HOST:REPO
matrix_backup_borg_storage_encryption_passphrase: "PASSPHRASE"
matrix_backup_borg_ssh_key_private: |
PRIVATE KEY
```
where:
* USER - SSH user of a provider/server
* HOST - SSH host of a provider/server
* REPO - borg repository name, it will be initialized on backup start, eg: `matrix`, regarding Syntax see [Remote repositories](https://borgbackup.readthedocs.io/en/stable/usage/general.html#repository-urls)
* 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. The whole key (all of its belonging lines) under `backup_borg_ssh_key_private` needs to be indented with 2 spaces
* PRIVATE KEY - the content of the **private** part of the SSH key you created before
To backup without encryption, add `backup_borg_encryption: 'none'` to your vars. This will also enable the `backup_borg_unknown_unencrypted_repo_access_is_ok` variable.
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.
`backup_borg_location_source_directories` defines the list of directories to back up: it's set to `{{ matrix_base_data_path }}` by default, which is the base directory for every service's data, such as Synapse, Postgres and the bridges. You might want to exclude certain directories or file patterns from the backup using the `backup_borg_location_exclude_patterns` variable.
`matrix_backup_borg_location_source_directories` defines the list of directories to back up: it's set to `{{ matrix_base_data_path }}` by default, which is the base directory for every service's data, such as Synapse, Postgres and the bridges. You might want to exclude certain directories or file patterns from the backup using the `matrix_backup_borg_location_exclude_patterns` variable.
Check the [backup_borg role](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg)'s [defaults/main.yml](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg/-/blob/main/defaults/main.yml) file for the full list of available options.
Check the `roles/matrix-backup-borg/defaults/main.yml` file for the full list of available options.
## Installing
@ -73,9 +67,3 @@ After configuring the playbook, run the [installation](installing.md) command ag
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Manually start a backup
For testing your setup it can be helpful to not wait until 4am. If you want to run the backup immediately, log onto the server
and run `systemctl start matrix-backup-borg`. This will not return until the backup is done, so possibly a long time.
Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.

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

@ -10,14 +10,14 @@ Usually, there are 2 options:
- either get a separate server for the base domain, just for serving the files necessary for [Server Delegation via a well-known file](howto-server-delegation.md#server-delegation-via-a-well-known-file)
- or, arrange for the Matrix server to serve the base domain. This either involves you [using your own webserver](configuring-playbook-own-webserver.md) or making the integrated webserver serve the base domain for you.
- or, arrange for the Matrix server to serve the base domain. This either involves you [using your own webserver](configuring-playbook-own-webserver.md) or making the integrated webserver (`matrix-nginx-proxy`) serve the base domain for you.
This documentation page tells you how to do the latter. With some easy changes, we make it possible to serve the base domain from the Matrix server via the integrated webserver.
This documentation page tells you how to do the latter. With some easy changes, we make it possible to serve the base domain from the Matrix server via the integrated webserver (`matrix-nginx-proxy`).
Just **adjust your DNS records**, so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then use the following configuration**:
```yaml
matrix_static_files_container_labels_base_domain_enabled: true
matrix_nginx_proxy_base_domain_serving_enabled: true
```
Doing this, the playbook will:
@ -26,50 +26,27 @@ Doing this, the playbook will:
- serve the `/.well-known/matrix/*` files which are necessary for [Federation Server Discovery](configuring-well-known.md#introduction-to-client-server-discovery) (also see [Server Delegation](howto-server-delegation.md)) and [Client-Server discovery](configuring-well-known.md#introduction-to-client-server-discovery)
- serve a simple homepage at `https://DOMAIN` with content `Hello from DOMAIN` (configurable via the `matrix_static_files_file_index_html_template` variable). You can also [serve a more complicated static website](#serving-a-static-website-at-the-base-domain).
- serve a simple homepage at `https://DOMAIN` with content `Hello from DOMAIN` (configurable via the `matrix_nginx_proxy_base_domain_homepage_template` variable). You can also [serve a more complicated static website](#serving-a-static-website-at-the-base-domain).
## Serving a static website at the base domain
By default, when "serving the base domain" is enabled, the playbook hosts a simple `index.html` webpage at `/matrix/static-files/public/index.html`.
The content of this page is taken from the `matrix_static_files_file_index_html_template` variable.
By default, when "serving the base domain" is enabled, the playbook hosts a simple `index.html` webpage in `/matrix/nginx-proxy/data/matrix-domain`.
The content of this page is taken from the `matrix_nginx_proxy_base_domain_homepage_template` variable.
If you'd like to host your own static website (more than a single `index.html` page) at the base domain, you can disable the creation of this default `index.html` page like this:
```yaml
# Enable base-domain serving
matrix_static_files_container_labels_base_domain_enabled: true
# Prevent the default index.html file from being installed
matrix_static_files_file_index_html_enabled: false
# Disable the automatic redirectin of `https://DOMAIN/` to `https://matrix.DOMAIN/`.
# This gets automatically enabled when you disable `matrix_static_files_file_index_html_enabled`, as we're doing above.
matrix_static_files_container_labels_base_domain_root_path_redirection_enabled: false
matrix_nginx_proxy_base_domain_homepage_enabled: false
```
With this configuration, Ansible will no longer mess around with the `/matrix/static-files/public/index.html` file.
With this configuration, Ansible will no longer mess around with the `/matrix/nginx-proxy/data/matrix-domain/index.html` file.
You are then free to upload any static website files to `/matrix/static-files/public` and they will get served at the base domain.
You can do so manually or by using the [ansible-role-aux](https://github.com/mother-of-all-self-hosting/ansible-role-aux) Ansible role, which is part of this playbook already.
You are then free to upload any static website files to `/matrix/nginx-proxy/data/matrix-domain` and they will get served at the base domain.
## Serving a more complicated website at the base domain
If you'd like to serve an even more complicated (dynamic) website from the Matrix server, relying on the playbook to serve the base domain is not the best choice.
You have 2 options.
**One way is to host your base domain elsewhere**. This involves:
- you stopping to serve it from the Matrix server: remove `matrix_static_files_container_labels_base_domain_enabled` from your configuration
- [configuring Matrix Delegation via well-known](./configuring-well-known.md)
**Another way is to serve the base domain from another (your own) container on the Matrix server**. This involves:
- telling the playbook to only serve `BASE_DOMAIN/.well-known/matrix` files by adjusting your `vars.yml` configuration like this:
- keep `matrix_static_files_container_labels_base_domain_enabled: true`
- add an extra: `matrix_static_files_container_labels_base_domain_traefik_path_prefix: /.well-known/matrix`
- building and running a new container on the Matrix server:
- it should be connected to the `traefik` network, so that Traefik can reverse-proxy to it
- it should have appropriate [container labels](https://docs.docker.com/config/labels-custom-metadata/), which instruct Traefik to reverse-proxy to it
How you'll be managing building and running this container is up-to-you. You may use of the primitives from [ansible-role-aux](https://github.com/mother-of-all-self-hosting/ansible-role-aux) Ansible role to organize it yourself, or you can set it up in another way.
Instead, we recommend that you switch to [using your own webserver](configuring-playbook-own-webserver.md) (preferrably nginx). You can then make that webserver host anything you wish, and still easily plug in Matrix services into it.

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

@ -1,429 +0,0 @@
# Setting up baibot (optional)
<p align="center">
<img src="https://github.com/etkecc/baibot/raw/main/etc/assets/baibot.svg" alt="baibot logo" width="150" />
<h1 align="center">baibot</h1>
</p>
🤖 [baibot](https://github.com/etkecc/baibot) (pronounced bye-bot) is a [Matrix](https://matrix.org/) bot developed by [etke.cc](https://etke.cc/) that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you. 🤖
It supports [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/chatgpt/) models, as many well as other [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md).
It's designed as a more private and [✨ featureful](https://github.com/etkecc/baibot/?tab=readme-ov-file#-features) alternative to [matrix-chatgpt-bot](./configuring-playbook-bot-chatgpt.md). See the [baibot](https://github.com/etkecc/baibot) project and its documentation for more information.
## Prerequisites
API access to one or more LLM [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md).
## Adjusting the playbook configuration
There are **a lot of configuration options** (some required, some possibly required, some optional), so they're **split into multiple sections below**:
<!-- no toc -->
- [Base configuration](#base-configuration)
- [👮‍♂️ Administrator configuration](#️-administrator-configuration)
- [👥 Initial users configuration](#-initial-users-configuration)
- [🤖 Configuring agents via Ansible](#-configuring-agents-via-ansible)
- [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers)
Depending on your current `vars.yml` file and desired configuration, **you may require more than just the [base configuration](#base-configuration)**.
### Base configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_baibot_enabled: true
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_baibot_config_user_mxid_localpart: baibot
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`.
# If you'd like to change this password subsequently, see the details below.
matrix_bot_baibot_config_user_password: 'PASSWORD_FOR_THE_BOT'
# An optional passphrase to use for backing up and recovering the bot's encryption keys.
# You can use any string here. Consider generating it with `pwgen -s 64 1`.
#
# If set to null, the recovery module will not be used and losing your session/database
# will mean you lose access to old messages in encrypted room.
# It's highly recommended that you configure this to avoid losing access to encrypted messages.
#
# Changing this subsequently will also cause you to lose access to old messages in encrypted rooms.
# For details about changing this subsequently or resetting, see `defaults/main.yml` in the baibot role.
matrix_bot_baibot_config_user_encryption_recovery_passphrase: 'ANY_LONG_AND_SECURE_PASSPHRASE_STRING_HERE'
# An optional secret for encrypting the bot's session data (see `matrix_bot_baibot_data_path`).
# This must be 32-bytes (64 characters when HEX-encoded).
# Generate it with: `openssl rand -hex 32`
# Set to null or empty to avoid using encryption.
# Changing this subsequently requires that you also throw away all data (see `matrix_bot_baibot_data_path`)
matrix_bot_baibot_config_persistence_session_encryption_key: 'A_HEX_STRING_OF_64_CHARACTERS_HERE'
# An optional secret for encrypting bot configuration stored in Matrix's account data.
# This must be 32-bytes (64 characters when HEX-encoded).
# Generate it with: `openssl rand -hex 32`
# Set to null or empty to avoid using encryption.
# Changing this subsequently will make you lose your configuration.
matrix_bot_baibot_config_persistence_config_encryption_key: 'A_HEX_STRING_OF_64_CHARACTERS_HERE'
```
As mentioned above, **this may not be enough**. Continue with the configuration sections below.
### 👮‍♂️ Administrator configuration
This is an addition to the [base configuration](#base-configuration).
To specify who is considered a bot [👮‍♂️ Administrator](https://github.com/etkecc/baibot/blob/main/docs/access.md#administrators), you either need to specify `matrix_bot_baibot_config_access_admin_patterns` or `matrix_admin`. The latter is a single variable which affects all bridges and bots.
If `matrix_admin` is already configured in your `vars.yml` configuration, you can skip this section.
**If necessary**, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yml
# Uncomment to add one or more admins to this bridge:
#
# matrix_bot_baibot_config_access_admin_patterns:
# - "@*:example.com"
# - "@admin:another.com"
#
# .. unless you've made yourself an admin of all bots/bridges like this:
#
# matrix_admin: '@yourAdminAccount:domain.com'
```
### 👥 Initial users configuration
By default, **all users on your homeserver are considered allowed users**. If that's OK, you can skip this section.
This is an addition to the [base configuration](#base-configuration).
To specify who is considered a bot [👥 User](https://github.com/etkecc/baibot/blob/main/docs/access.md#user), you may:
- define an **initial** value for `matrix_bot_baibot_config_initial_global_config_user_patterns` Ansible variable, as shown below
- configure the list at runtime via the bot's `!bai access set-users SPACE_SEPARATED_PATTERNS` command
Configuring `matrix_bot_baibot_config_initial_global_config_user_patterns` is optional, but it can be useful to pre-configure the bot with a list of users who should have access to the bot's features.
**Note**: Once initially configured, the allowed users list **cannot be managed via Ansible anymore**. It can only be managed subsequently via bot commands.
**If necessary**, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yml
# Uncomment and adjust the bot users if necessary:
#
# Subsequent changes to `matrix_bot_baibot_config_initial_global_config_user_patterns` do not affect the bot's behavior.
# Once initially configured, the allowed users list is managed via bot commands, not via Ansible.
#
# matrix_bot_baibot_config_initial_global_config_user_patterns:
# - "@*:{{ matrix_bot_baibot_config_homeserver_server_name }}"
```
### 🤖 Configuring agents via Ansible
You are **not required** to define agents [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration) via Ansible. **To get started quickly**, you can **skip this section and define agents at runtime via chat commands** (following the bot's guidance).
Privileged users (like the [👮‍♂️ Administrator](#️-administrator-configuration), but potentially others too - see the upstream [🔒 access](https://github.com/etkecc/baibot/blob/main/docs/access.md) documentation) can **define agents dynamically at any time** via chat commands.
The Ansible role includes preset variables for easily enabling some [🤖 agents](https://github.com/etkecc/baibot/blob/main/docs/agents.md) on various [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md) (e.g. OpenAI, etc).
Besides the presets, the Ansible role also includes support for configuring additional statically-defined agents via the `matrix_bot_baibot_config_agents_static_definitions_custom` Ansible variable.
Agents defined statically and those created dynamically (via chat) are named differently, so **conflict cannot arise**.
Depending on your propensity for [GitOps](https://en.wikipedia.org/wiki/DevOps#GitOps), you may prefer to define agents statically via Ansible, or you may wish to do it dynamically via chat.
Before proceeding, we recommend reading the upstream documentation on [How to choose a provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#how-to-choose-a-provider). In short, it's probably best to go with [OpenAI](#openai).
#### Anthropic
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [Anthropic provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#anthropic) with the help of the playbook's preset variables.
Here's an example **addition** to your `vars.yml` file:
```yml
matrix_bot_baibot_config_agents_static_definitions_anthropic_enabled: true
matrix_bot_baibot_config_agents_static_definitions_anthropic_config_api_key: "YOUR_API_KEY_HERE"
# If you'd like to use another text-generation agent, uncomment and adjust:
# matrix_bot_baibot_config_agents_static_definitions_anthropic_config_text_generation_model_id: claude-3-5-sonnet-20240620
# The playbook defines a default prompt for all statically-defined agents.
# You can adjust it in the `matrix_bot_baibot_config_agents_static_definitions_prompt` variable,
# or you can adjust it below only for the Anthropic agent.
# matrix_bot_baibot_config_agents_static_definitions_anthropic_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
# See `defaults/main.yml` in the baibot role for more configuration options.
```
If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
#### Groq
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [Groq provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#groq) with the help of the playbook's preset variables.
Here's an example **addition** to your `vars.yml` file:
```yml
matrix_bot_baibot_config_agents_static_definitions_groq_enabled: true
matrix_bot_baibot_config_agents_static_definitions_groq_config_api_key: "YOUR_API_KEY_HERE"
# Specify the text-generation agent you'd like to use
matrix_bot_baibot_config_agents_static_definitions_groq_config_text_generation_model_id: "llama3-70b-8192"
# The playbook defines a default prompt for all statically-defined agents.
# You can adjust it in the `matrix_bot_baibot_config_agents_static_definitions_prompt` variable,
# or you can adjust it below only for the Groq agent.
# matrix_bot_baibot_config_agents_static_definitions_groq_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
# Uncomment and adjust if you're not happy with these speech-to-text defaults:
#
# matrix_bot_baibot_config_agents_static_definitions_groq_config_speech_to_text_enabled: true
# matrix_bot_baibot_config_agents_static_definitions_groq_config_speech_to_text_model_id: whisper-large-v3
# See `defaults/main.yml` in the baibot role for more configuration options.
```
Because this is a [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration)-defined agent, it will be given a `static/` ID prefix and will be named `static/groq`.
If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
#### Mistral
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [🇫🇷 Mistral provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#mistral) with the help of the playbook's preset variables.
Here's an example **addition** to your `vars.yml` file:
```yml
matrix_bot_baibot_config_agents_static_definitions_mistral_enabled: true
matrix_bot_baibot_config_agents_static_definitions_mistral_config_api_key: "YOUR_API_KEY_HERE"
# The playbook defines a default prompt for all statically-defined agents.
# You can adjust it in the `matrix_bot_baibot_config_agents_static_definitions_prompt` variable,
# or you can adjust it below only for the Mistral agent.
# matrix_bot_baibot_config_agents_static_definitions_mistral_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
# Uncomment and adjust if you're not happy with these defaults:
# matrix_bot_baibot_config_agents_static_definitions_mistral_config_text_generation_model_id: mistral-large-latest
# See `defaults/main.yml` in the baibot role for more configuration options.
```
Because this is a [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration)-defined agent, it will be given a `static/` ID prefix and will be named `static/mistral`.
If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
#### OpenAI
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [OpenAI provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openai) with the help of the playbook's preset variables.
The OpenAI provider is **only meant to be used with OpenAI's official API** and compatibility with other services (which do not fully adhere to the OpenAI API spec completely) is limited. **If you're targeting an OpenAI-compatible service**, use the [OpenAI Compatible](#openai-compatible) provider instead.
Here's an example **addition** to your `vars.yml` file:
```yml
matrix_bot_baibot_config_agents_static_definitions_openai_enabled: true
matrix_bot_baibot_config_agents_static_definitions_openai_config_api_key: "YOUR_API_KEY_HERE"
# The playbook defines a default prompt for all statically-defined agents.
# You can adjust it in the `matrix_bot_baibot_config_agents_static_definitions_prompt` variable,
# or you can adjust it below only for the OpenAI agent.
# matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
# If you'd like to use another text-generation agent, uncomment and adjust:
# matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_model_id: gpt-4o-2024-08-06
# See `defaults/main.yml` in the baibot role for more configuration options.
```
Because this is a [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration)-defined agent, it will be given a `static/` ID prefix and will be named `static/openai`.
If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
#### OpenAI Compatible
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [OpenAI Compatible provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openai-compatible) with the help of the playbook's preset variables.
This provider allows you to use OpenAI-compatible API services like [OpenRouter](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openrouter), [Together AI](https://github.com/etkecc/baibot/blob/main/docs/providers.md#together-ai), etc.
Some of these popular services already have **shortcut** providers (see [supported providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md#supported-providers) leading to this one behind the scenes - this make it easier to get started.
As of this moment, the playbook does not include presets for any of these services, so you'll need to [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset).
#### Configuring additional agents (without a preset)
The Ansible role may be lacking preset variables for some [☁️ provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md), or you may wish to statically-define an agent on the same provider twice (or more) with different configuration.
It's possible to inject your own agent configuration using the `matrix_bot_baibot_config_agents_static_definitions_custom` Ansible variable.
You can also define providers at runtime, by chatting with the bot, so using Ansible is not a requirement.
Below is an an **example** demonstrating **statically-defining agents via Ansible without using presets**:
```yml
matrix_bot_baibot_config_agents_static_definitions_custom:
# This agent will use the GPT 3.5 model and will only support text-generation,
# even though the `openai` provider could support other features (e.g. image-generation).
- id: my-openai-gpt-3.5-turbo-agent
provider: openai
config:
base_url: https://api.openai.com/v1
api_key: "YOUR_API_KEY_HERE"
text_generation:
model_id: gpt-3.5-turbo-0125
prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
temperature: 1.0
max_response_tokens: 4096
max_context_tokens: 16385
speech_to_text: null
text_to_speech: null
image_generation: null
# This agent uses the `openai` provider, but adjusts the base URL, so that it points to some Ollama instance
# (which supports an OpenAI-compatible API).
- id: my-ollama-agent
provider: openai
config:
base_url: http://ollama-service:1234/v1
api_key: ""
text_generation:
model_id: "llama3.1:8b"
prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
temperature: 1.0
max_response_tokens: 4096
max_context_tokens: 128000
speech_to_text: null
text_to_speech: null
image_generation: null
```
Because these are [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration)-defined agents, they will be given a `static/` ID prefix and will be named `static/my-openai-gpt-3.5-turbo-agent` and `static/my-ollama-agent`, respectively.
💡 To figure out what to put in the `config` section, refer to the [☁️ provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md) page, which contains **sample configuration YAML for each provider**.
As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md), defining them means they exist. To actually make use of them, they need to be configured as handlers globally or in a specific room - see [Mixing & matching models](https://github.com/etkecc/baibot/blob/main/docs/features.md#mixing--matching-models).
💡 You may also wish to use these new agents for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
### 🤝 Configuring initial default handlers
This section is only useful if you're [🤖 Configuring agents via Ansible](#-configuring-agents-via-ansible), as it lets you put these agents to use as soon as the bot starts (by adjusting the bot's **initial global configuration**).
If you're not configuring agents via Ansible, you can skip this section.
This section is only useful the first time around. **Once initially configured the global configuration cannot be managed Ansible**, but only via bot commands.
baibot supports [various purposes](https://github.com/etkecc/baibot/blob/main/docs/features.md):
- [💬 text-generation](https://github.com/etkecc/baibot/blob/main/docs/features.md#-text-generation): communicating with you via text
- [🦻 speech-to-text](https://github.com/etkecc/baibot/blob/main/docs/features.md#-speech-to-text): turning your voice messages into text
- [🗣️ text-to-speech](https://github.com/etkecc/baibot/blob/main/docs/features.md#-text-to-speech): turning bot or users text messages into voice messages
- [🖌️ image-generation](https://github.com/etkecc/baibot/blob/main/docs/features.md#-image-generation): generating images based on instructions
- ❓ catch-all: special purposes, indicating use as a fallback (when no specific handler is configured)
[Mixing & matching models](https://github.com/etkecc/baibot/blob/main/docs/features.md#mixing--matching-models) is made possible by the bot's ability to have different [🤝 handlers](https://github.com/etkecc/baibot/blob/main/docs/configuration/handlers.md) configured for different purposes.
This configuration can be done as a global fallback, or per-room. Both of these [🛠️ configurations](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md) are managed at runtime (viat chat), but **the global configuration can have some initial defaults configured via Ansible**.
You can configure the **initial values** for these via Ansible, via the `matrix_bot_baibot_config_initial_global_config_handler_*` variables.
Example **additional** `vars.yml` configuration:
```yml
# NOTE: these are initial defaults for the bot's global configuration.
# As such, changing any of these values subsequently has no effect on the bot's behavior.
# Once initially configured, the global configuration is managed via bot commands, not via Ansible.
matrix_bot_baibot_config_initial_global_config_handler_catch_all: static/openai
# In this example, there's no need to define any of these below.
# Configuring the catch-all purpose handler is enough.
matrix_bot_baibot_config_initial_global_config_handler_text_generation: null
matrix_bot_baibot_config_initial_global_config_handler_text_to_speech: null
matrix_bot_baibot_config_initial_global_config_handler_speech_to_text: null
matrix_bot_baibot_config_initial_global_config_handler_image_generation: null
```
**Note**: these are initial defaults for the bot's global configuration. As such, changing any of these values subsequently has no effect on the bot's behavior. **Once initially configured the global configuration cannot be managed Ansible**, but only via bot commands.
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```sh
just run-tags install-all,ensure-matrix-users-created,start
```
**Notes**:
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
- if you change the bot password (`matrix_bot_baibot_config_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_baibot_config_user_password` to let the bot know its new password
## Usage
To use the bot, invite the `@baibot:DOMAIN` bot user into a room.
If you're an allowed bot [👥 user](https://github.com/etkecc/baibot/blob/main/docs/access.md#user) (see [👥 Initial users configuration](#-initial-users-configuration)), the bot will accept your invitation and join the room.
After joining, the bot will introduce itself and show information about the [✨ features](https://github.com/etkecc/baibot/blob/main/docs/features.md) that are enabled for it.
If you've [🤖 configured one or more agents via Ansible](#-configuring-agents-via-ansible) and have [🤝 configured initial default handlers](#configuring-initial-default-handlers), the bot will immediately be able to make use of these agents for this new room. Otherwise, you will need to configure agents and/or handlers via chat commands.
Send `!bai help` to the room at any time to see the bot's help menu for additional commands.
You can also refer to the upstream [baibot](https://github.com/etkecc/baibot) project's documentation.
## Debugging
As with all other services, you can find service logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by running something like `journalctl -fu matrix-bot-baibot`
The default logging level for this service is `info`, but you can increase it to `debug` (or even `trace`) with the following additional configuration:
```yaml
# Adjust the bot's own logging level.
matrix_bot_baibot_config_logging_level_baibot: debug
# Adjust the logging level for the mxlink bot library used by the bot.
matrix_bot_baibot_config_logging_level_mxlink: debug
# Adjust the logging level for other libraries used by the bot.
# Having this set to a value other than "warn" can be very noisy.
matrix_bot_baibot_config_logging_level_other_libs: debug
```
**Alternatively**, you can use a single variable to set the logging level for all of the above (bot + all libraries):
```yaml
matrix_bot_baibot_config_logging: debug
```

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

@ -1,31 +1,23 @@
# Setting up Buscarron (optional)
The playbook can install and configure [buscarron](https://github.com/etkecc/buscarron) for you.
The playbook can install and configure [buscarron](https://gitlab.com/etke.cc/buscarron) for you.
Buscarron is bot that receives HTTP POST submissions of web forms and forwards them to a Matrix room.
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
## Decide on a domain and path
By default, the playbook will set up the bot with a username like this: `@bot.buscarron:DOMAIN`.
By default, Buscarron is configured to use its own dedicated domain (`buscarron.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
(to use a different username, adjust the `matrix_bot_buscarron_login` variable).
You can override the domain and path like this:
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):
```yaml
# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
# so we won't need to add additional DNS records for Buscarron.
matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /buscarron subpath
matrix_bot_buscarron_path_prefix: /buscarron
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.buscarron password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
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
@ -35,10 +27,7 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
```yaml
matrix_bot_buscarron_enabled: true
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_buscarron_login: bot.buscarron
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
# Adjust this to whatever password you chose when registering the bot user
matrix_bot_buscarron_password: PASSWORD_FOR_THE_BOT
# Adjust accepted forms
@ -47,10 +36,20 @@ matrix_bot_buscarron_forms:
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
hasemail: 1 # (optional) form has "email" field that should be validated
extensions: [] # (optional) list of form extensions (not used yet)
matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (with wildcards support) that should be rejected automatically
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 }}"
```
@ -58,15 +57,9 @@ matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (wit
After configuring the playbook, run the [installation](installing.md) command again:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
**Notes**:
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
- if you change the bot password (`matrix_bot_buscarron_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_buscarron_password` to let the bot know its new password
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
@ -79,12 +72,4 @@ To use the bot, invite the `@bot.buscarron:DOMAIN` to the room you specified in
</form>
```
**NOTE**: to fight against spam, Buscarron is **very aggressive when it comes to banning** and will ban you if:
- if you hit the homepage (HTTP `GET` request to `/`)
- if you submit a form to the wrong URL (`POST` request to `/non-existing-form`)
- if `hasemail` is enabled for the form (like in the example above) and you don't submit an `email` field
If you get banned, you'd need to restart the process by running the playbook with `--tags=start` or running `systemctl restart matrix-bot-buscarron` on the server.
You can also refer to the upstream [documentation](https://github.com/etkecc/buscarron).
You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/buscarron).

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

@ -1,71 +0,0 @@
# Setting up ChatGPT (optional)
The playbook can install and configure [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) for you.
Talk to [ChatGPT](https://openai.com/blog/chatgpt/) via your favourite Matrix client!
**Note**: [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) is now an archived (**unmaintained**) project. Talking to ChatGPT (and many other LLM providers) can happen via the much more featureful [baibot](./configuring-playbook-bot-baibot.md) bot supported by the playbook.
## 1. Register the bot account
The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
You **need to register the bot user manually** before setting up the bot.
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.chatgpt password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
## 2. Get an access token and create encryption keys
Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
To make sure the bot can read encrypted messages, it will need an encryption key, just like any other new user. While obtaining the access token, follow the prompts to setup a backup key. More information can be found in the [element documentation](https://element.io/help#encryption6).
## 3. Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
matrix_bot_chatgpt_enabled: true
# Obtain a new API key from https://platform.openai.com/account/api-keys
matrix_bot_chatgpt_openai_api_key: ''
# This is the default username
# matrix_bot_chatgpt_matrix_bot_username_localpart: 'bot.chatgpt'
# Matrix access token (from bot user above)
# see: https://webapps.stackexchange.com/questions/131056/how-to-get-an-access-token-for-element-riot-matrix
matrix_bot_chatgpt_matrix_access_token: ''
# Configuring the system promt used, needed if the bot is used for special tasks.
# More information: https://github.com/mustvlad/ChatGPT-System-Prompts
matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a large language model trained by OpenAI.'
```
You will need to get tokens for ChatGPT.
## 4. Installing
After configuring the playbook, run the [installation](installing.md) command again:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
```
## Usage
To use the bot, invite the `@bot.chatgpt:DOMAIN` to the room you specified in a config, after that start speaking to it, use the prefix if you configured one or mention the bot.
You can also refer to the upstream [documentation](https://github.com/matrixgpt/matrix-chatgpt-bot).

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

@ -1,227 +0,0 @@
# Setting up draupnir (optional)
The playbook can install and configure the [draupnir](https://github.com/the-draupnir-project/Draupnir) moderation bot for you.
See the project's [documentation](https://github.com/the-draupnir-project/Draupnir) to learn what it does and why it might be useful to you.
This documentation page is about installing Draupnir in bot mode. As an alternative, you can run a multi-instance Draupnir deployment by installing [Draupnir in appservice mode](./configuring-playbook-appservice-draupnir-for-all.md) (called Draupnir-for-all) instead.
If your migrating from Mjolnir skip to step 5b.
## 1. Register the bot account
The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
You **need to register the bot user manually** before setting up the bot.
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
If you would like draupnir to be able to deactivate users, move aliases, shutdown rooms, show abuse reports ([see below](#abuse-reports)), etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
## 2. Get an access token
Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
## 3. Make sure the account is free from rate limiting
You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step draupnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
If your Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](/docs/configuring-playbook-synapse-admin.md) or running `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands.
The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@example:example.com/override_ratelimit` Replace `@example:example.com` with the MXID of your Draupnir and example.com with your homeserver domain. You can easily obtain an access token for a homeserver admin account the same way you can obtain an access token for Draupnir it self. If you made Draupnir Admin you can just use the Draupnir token.
## 4. Create a management room
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below).
Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element you can do this by going to the room's settings, clicking Advanced, and then coping the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:DOMAIN`.
Finally invite the `@bot.draupnir:DOMAIN` account you created earlier into the room.
## 5. Adjusting the playbook configuration
Decide whether you want Draupnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Draupnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
### 5a. Configuration with E2EE support
When using Pantalaimon, Draupnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
matrix_pantalaimon_enabled: true
# Enable Draupnir
matrix_bot_draupnir_enabled: true
# Tell Draupnir to use Pantalaimon
matrix_bot_draupnir_pantalaimon_use: true
# User name and password for the bot. Required when using Pantalaimon.
matrix_bot_draupnir_pantalaimon_username: "DRAUPNIR_USERNAME_FROM_STEP_1"
matrix_bot_draupnir_pantalaimon_password: ### you should create a secure password for the bot account
matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
```
The playbook's `group_vars` will configure other required settings. If using this role separately without the playbook, you also need to configure the two URLs that Draupnir uses to reach the homeserver, one through Pantalaimon and one "raw". This example is taken from the playbook's `group_vars`:
```yaml
# Endpoint URL that Draupnir uses to interact with the matrix homeserver (client-server API).
# Set this to the pantalaimon URL if you're using that.
matrix_bot_draupnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_draupnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
# Endpoint URL that Draupnir could use to fetch events related to reports (client-server API and /_synapse/),
# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
```
### 5b. Configuration without E2EE support
When NOT using Pantalaimon, Draupnir does not log in by itself and you must give it an access token for its bot account.
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with the your own values.
```yaml
matrix_bot_draupnir_enabled: true
matrix_bot_draupnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
```
### 5c. Migrating from Mjolnir (Only required if migrating.)
Replace your `matrix_bot_mjolnir` config with `matrix_bot_draupnir` config. Also disable mjolnir if you're doing migration.
That is all you need to do due to that Draupnir can complete migration on its own.
## 6. Installing
After configuring the playbook, run the [installation](installing.md) command:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
You can refer to the upstream [documentation](https://the-draupnir-project.github.io/draupnir-documentation/) for additional ways to use and configure Draupnir and for a more detailed usage guide.
Below is a **non-exhaustive quick-start guide** for the impatient.
### Making Draupnir join and protect a room
Draupnir can be told to self-join public rooms, but it's better to follow this flow which works well for all kinds of rooms:
1. Invite the bot to the room manually ([inviting Draupnir to rooms](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#inviting-draupnir-to-rooms)). Before joining, the bot *may* ask for confirmation in the Management Room
2. [Give the bot permissions to do its job](#giving-draupnir-permissions-to-do-its-job)
3. Tell it to protect the room (using the [rooms command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#using-the-draupnir-rooms-command)) by sending the following command to the Management Room: `!draupnir rooms add !ROOM_ID:DOMAIN`
To have Draupnir provide useful room protection, you need do to a bit more work (at least the first time around).
You may wish to [Subscribe to a public policy list](#subscribing-to-a-public-policy-list), [Create your own own policy and rules](#creating-your-own-policy-lists-and-rules) and [Enabling built-in protections](#enabling-built-in-protections).
### Giving Draupnir permissions to do its job
For Draupnir to do its job, you need to [give it permissions](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#giving-draupnir-permissions) in rooms it's protecting. This involves **giving it an Administrator power level**.
**We recommend setting this power level as soon as the bot joins your room** (and before you create new rules), so that it can apply rules as soon as they are available. If the bot is under-privileged, it may fail to apply protections and may not retry for a while (or until your restart it).
### Subscribing to a public policy list
We recommend **subscribing to a public [policy list](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists)** using the [watch command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-policy-lists#using-draupnirs-watch-command-to-subscribe-to-policy-rooms).
Polcy lists are maintained in Matrix rooms. A popular policy list is maintained in the public `#community-moderation-effort-bl:neko.dev` room.
You can tell Draupnir to subscribe to it by sending the following command to the Management Room: `!draupnir watch #community-moderation-effort-bl:neko.dev`
#### Creating your own policy lists and rules
We also recommend **creating your own policy lists** with the [list create](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-policy-lists#using-draupnirs-list-create-command-to-create-a-policy-room) command.
You can do so by sending the following command to the Management Room: `!draupnir list create my-bans my-bans-bl`. This will create a policy list having a name (shortcode) of `my-bans` and stored in a public `#my-bans-bl:DOMAIN` room on your server. As soon as you run this command, the bot will invite you to the policy list room.
A policy list does nothing by itself, so the next step is **adding some rules to your policy list**. Policies target a so-called `entity` (one of: `user`, `room` or `server`). These entities are mentioned on the [policy lists](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists) documentation page and in the Matrix Spec [here](https://spec.matrix.org/v1.11/client-server-api/#mban-recommendation).
The simplest and most useful entity to target is `user`. Below are a few examples using the [ban command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#the-ban-command) and targeting users.
To create rules, you run commands in the Management Room (**not** in the policy list room).
- (ban a single user on a given homeserver): `!draupnir ban @someone:example.com my-bans Rude to others`
- (ban all users on a given homeserver by using a [wildcard](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#wildcards)): `!draupnir ban @*:example.org my-bans Spam server - all users are fake`
As a result of running these commands, you may observe:
- Draupnir creating `m.policy.rule.user` state events in the `#my-bans-bl:DOMAIN` room on your server
- applying these rules against all rooms that Draupnir is an Administrator in
You can undo bans with the [unban command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#the-unban-command).
### Enabling built-in protections
You can also **turn on various built-in [protections](https://the-draupnir-project.github.io/draupnir-documentation/protections)** like `JoinWaveShortCircuit` ("If X amount of users join in Y time, set the room to invite-only").
To **see which protections are available and which are enabled**, send a `!draupnir protections` command to the Management Room.
To **see the configuration options for a given protection**, send a `!draupnir config get PROTECTION_NAME` (e.g. `!draupnir config get JoinWaveShortCircuit`).
To **set a specific option for a given protection**, send a command like this: `!draupnir config set PROTECTION_NAME.OPTION VALUE` (e.g. `!draupnir config set JoinWaveShortCircuit.timescaleMinutes 30`).
To **enable a given protection**, send a command like this: `!draupnir enable PROTECTION_NAME` (e.g. `!draupnir enable JoinWaveShortCircuit`).
To **disable a given protection**, send a command like this: `!draupnir disable PROTECTION_NAME` (e.g. `!draupnir disable JoinWaveShortCircuit`).
## Extending the configuration
You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file.
For example to change draupnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file.
```yaml
matrix_bot_draupnir_configuration_extension_yaml: |
# Your custom YAML configuration goes here.
# This configuration extends the default starting configuration (`matrix_bot_draupnir_configuration_yaml`).
#
# You can override individual variables from the default configuration, or introduce new ones.
#
# If you need something more special, you can take full control by
# completely redefining `matrix_bot_draupnir_configuration_yaml`.
recordIgnoredInvites: true
```
## Abuse Reports
Draupnir supports two methods to receive reports in the management room.
The first method intercepts the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver.
If you are using traefik, this playbook can set this up for you:
```yaml
matrix_bot_draupnir_abuse_reporting_enabled: true
```
The other method polls an synapse admin API endpoint and is hence only available when using synapse and when the Draupnir user is an admin user (see step 1).
To enable it, set `pollReports: true` in Draupnir's config:
```yaml
matrix_bot_draupnir_configuration_extension_yaml: |
pollReports: true
```

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

@ -21,30 +21,20 @@ You can use the playbook to [register a new user](registering-users.md):
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
## Getting an access token
## Decide on a domain and path
If you use curl, you can get an access token like this:
By default, Go-NEB is configured to use its own dedicated domain (`goneb.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
# so we won't need to add additional DNS records for Go-NEB.
matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /go-neb subpath
matrix_bot_go_neb_path_prefix: /go-neb
```
curl -X POST --header 'Content-Type: application/json' -d '{
"identifier": { "type": "m.id.user", "user": "bot.go-neb" },
"password": "a strong password",
"type": "m.login.password"
}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token), but doing so might lead to decryption problems. That warning comes from [here](https://github.com/matrix-org/go-neb#quick-start).
## Adjusting the playbook configuration
@ -60,7 +50,7 @@ matrix_bot_go_neb_clients:
- UserID: "@goneb:{{ matrix_domain }}"
AccessToken: "MDASDASJDIASDJASDAFGFRGER"
DeviceID: "DEVICE1"
HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
HomeserverURL: "{{ matrix_homeserver_container_url }}"
Sync: true
AutoJoinRooms: true
DisplayName: "Go-NEB!"
@ -69,7 +59,7 @@ matrix_bot_go_neb_clients:
- UserID: "@another_goneb:{{ matrix_domain }}"
AccessToken: "MDASDASJDIASDJASDAFGFRGER"
DeviceID: "DEVICE2"
HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
HomeserverURL: "{{ matrix_homeserver_container_url }}"
Sync: false
AutoJoinRooms: false
DisplayName: "Go-NEB!"
@ -176,13 +166,13 @@ matrix_bot_go_neb_services:
Rooms:
"!someroom:id":
Repos:
"element-hq/synapse":
"matrix-org/synapse":
Events: ["push", "issues"]
"matrix-org/dendron":
Events: ["pull_request"]
"!anotherroom:id":
Repos:
"element-hq/synapse":
"matrix-org/synapse":
Events: ["push", "issues"]
"matrix-org/dendron":
Events: ["pull_request"]
@ -216,7 +206,9 @@ matrix_bot_go_neb_services:
## Installing
After potentially [adjusting DNS records](#adjusting-dns-records) and configuring the playbook, run the [installation](installing.md) command again:
Don't forget to add `goneb.<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

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

@ -1,10 +1,25 @@
# Setting up Honoroit (optional)
The playbook can install and configure [Honoroit](https://github.com/etkecc/honoroit) for you.
The playbook can install and configure [Honoroit](https://gitlab.com/etke.cc/honoroit) for you.
It's a bot you can use to setup **your own helpdesk on matrix**
See the project's [documentation](https://github.com/etkecc/honoroit#how-it-looks-like) to learn what it does with screenshots and why it might be useful to you.
See the project's [documentation](https://gitlab.com/etke.cc/honoroit#how-it-looks-like) to learn what it does with screenshots and why it might be useful to you.
## Registering the bot user
By default, the playbook will set up the bot with a username like this: `@honoroit:DOMAIN`.
(to use a different username, adjust the `matrix_bot_honoroit_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=honoroit 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
@ -14,14 +29,7 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
```yaml
matrix_bot_honoroit_enabled: true
# Uncomment and adjust if you'd like to change the hostname or path
# matrix_bot_honoroit_hostname: "{{ matrix_server_fqn_matrix }}"
# matrix_bot_honoroit_path_prefix: /honoroit
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_honoroit_login: honoroit
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
# Adjust this to whatever password you chose when registering the bot user
matrix_bot_honoroit_password: PASSWORD_FOR_THE_BOT
# Adjust this to your room ID
@ -33,15 +41,9 @@ matrix_bot_honoroit_roomid: "!yourRoomID:DOMAIN"
After configuring the playbook, run the [installation](installing.md) command again:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
**Notes**:
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
- if you change the bot password (`matrix_bot_honoroit_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_honoroit_password` to let the bot know its new password
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
@ -50,4 +52,4 @@ To use the bot, invite the `@honoroit:DOMAIN` to the room you specified in confi
Send `!ho help` to the room to see the bot's help menu for additional commands.
You can also refer to the upstream [documentation](https://github.com/etkecc/honoroit#features).
You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/honoroit#features).

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

@ -2,26 +2,47 @@
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** aka. invitation codes.
It can be used for an invitation-based server, where you invite someone by sending them a registration token (tokens look like this: `rbalQ0zkaDSRQCOp`). They can register as per normal but have to provide a valid registration token in the final step of the registration process.
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.
## Configuration
## Registering the bot user
To enable the bot, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
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
# By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:DOMAIN`.
# To use a different username, uncomment & adjust the variable below:
# matrix_bot_matrix_registration_bot_matrix_user_id_localpart: bot.matrix-registration-bot
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
matrix_bot_matrix_registration_bot_bot_password: PASSWORD_FOR_THE_BOT
# 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
@ -30,24 +51,22 @@ matrix_synapse_enable_registration: true
matrix_synapse_registration_requires_token: true
```
The bot account will be created automatically.
## Installing
After configuring the playbook, re-run the [installation](installing.md) command again: `just install-all` or `just setup-all`
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, message `@bot.matrix-registration-bot:DOMAIN` (where `DOMAIN` is your base domain, not the `matrix.` domain).
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).
To clean the cache (session&encryption data) after you changed the bot's username, changed the login methon form access_token to password etc.. you can use
```bash
just run-tags bot-matrix-registration-bot-clean-cache
```

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

@ -7,6 +7,21 @@ It's a bot you can use to **schedule one-off & recurring reminders and alarms**.
See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage) to learn what it does and why it might be useful to you.
## Registering the bot user
By default, the playbook will set up the bot with a username like this: `@bot.matrix-reminder-bot:DOMAIN`.
(to use a different username, adjust the `matrix_bot_matrix_reminder_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-reminder-bot 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:
@ -14,10 +29,7 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
```yaml
matrix_bot_matrix_reminder_bot_enabled: true
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_matrix_reminder_bot_matrix_user_id_localpart: bot.matrix-reminder-bot
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
# Adjust this to whatever password you chose when registering the bot user
matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT
# Adjust this to your timezone
@ -29,15 +41,9 @@ matrix_bot_matrix_reminder_bot_reminders_timezone: Europe/London
After configuring the playbook, run the [installation](installing.md) command again:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
**Notes**:
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
- if you change the bot password (`matrix_bot_matrix_reminder_bot_matrix_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_matrix_reminder_bot_matrix_user_password` to let the bot know its new password
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage

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

@ -1,55 +0,0 @@
# 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
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_maubot_login: bot.maubot
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
matrix_bot_maubot_initial_password: PASSWORD_FOR_THE_BOT
matrix_bot_maubot_admins:
- yourusername: securepassword
```
You can add multiple admins. The admin accounts are only used to access the maubot administration interface.
## Installing
After configuring the playbook, run the [installation](installing.md) command again (`just install-all`):
**Notes**:
- if you change the bot password (`matrix_bot_maubot_initial_password` in your `vars.yml` file) subsequently,
the bot user's credentials on the homeserver won't be updated automatically.
If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it.
## 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. By default, the playbook creates a `bot.maubot` account (as per the configuration above). You only need to [obtain an access token](#obtaining-an-access-token) for it
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)
## Obtaining an access token
This can be done via `mbc login` then `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)). To run these commands, you'll first need to `exec` into the maubot container with `docker exec -it matrix-bot-maubot sh`.
Alternatively, you can follow our generic [obtain an access token](obtaining-access-tokens.md) documentation. Be aware that you'd better use the **Obtain an access token via curl** method (not **Obtain an access token via Element**) as the latter will give your bot issues in encrypted rooms. Read [more](https://docs.mau.fi/maubot/usage/basic.html#creating-clients).

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

@ -24,22 +24,50 @@ If you would like Mjolnir to be able to deactivate users, move aliases, shutdown
## 2. Get an access token
Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
If you use curl, you can get an access token like this:
```
curl -X POST --header 'Content-Type: application/json' -d '{
"identifier": { "type": "m.id.user", "user": "bot.mjolnir" },
"password": "PASSWORD_FOR_THE_BOT",
"type": "m.login.password"
}' 'https://matrix.DOMAIN/_matrix/client/r0/login'
```
Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token).
## 3. Make sure the account is free from rate limiting
You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. [Currently there is no Synapse config option for this](https://github.com/matrix-org/synapse/issues/6286) so you have to manually edit the Synapse database. Manually editing the Synapse database is rarely a good idea but in this case it is required. Please ask for help if you are uncomfortable with these steps.
If your Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](/docs/configuring-playbook-synapse-admin.md) or running `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands.
1. Copy the statement below into a text editor.
```
INSERT INTO ratelimit_override VALUES ('@bot.mjolnir:DOMAIN', 0, 0);
```
1. Change the username (`@bot.mjolnir:DOMAIN`) to the username you used when you registered the bot's account. You must change `DOMAIN` to your server's domain.
1. Get a database terminal by following these steps: [maintenance-postgres.md#getting-a-database-terminal](maintenance-postgres.md#getting-a-database-terminal)
1. Connect to Synapse's database by typing `\connect synapse` into the database terminal
1. Paste in the `INSERT INTO` command that you edited and press enter.
You can run `SELECT * FROM ratelimit_override;` to see if it worked. If the output looks like this:
```
user_id | messages_per_second | burst_count
-----------------------+---------------------+-------------
@bot.mjolnir:raim.ist | 0 | 0`
```
then you did it correctly.
The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@example:example.com/override_ratelimit` Replace `@example:example.com` with the MXID of your Mjolnir and example.com with your homeserver domain. You can easily obtain an access token for a homeserver admin account the same way you can obtain an access token for Mjolnir it self. If you made Mjolnir Admin you can just use the Mjolnir token.
## 4. Create a management room
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below).
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room. The room must be unencrypted since the playbook does not support installing Pantalaimon yet.
Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element you can do this by going to the room's settings, clicking Advanced, and then coping the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:DOMAIN`.
@ -48,47 +76,6 @@ Finally invite the `@bot.mjolnir:DOMAIN` account you created earlier into the ro
## 5. Adjusting the playbook configuration
Decide whether you want Mjolnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Mjolnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
### 5a. Configuration with E2EE support
When using Pantalaimon, Mjolnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
matrix_pantalaimon_enabled: true
# Enable Mjolnir
matrix_bot_mjolnir_enabled: true
# Tell Mjolnir to use Pantalaimon
matrix_bot_mjolnir_pantalaimon_use: true
# User name and password for the bot. Required when using Pantalaimon.
matrix_bot_mjolnir_pantalaimon_username: "MJOLNIR_USERNAME_FROM_STEP_1"
matrix_bot_mjolnir_pantalaimon_password: ### you should create a secure password for the bot account
matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
```
The playbook's `group_vars` will configure other required settings. If using this role separately without the playbook, you also need to configure the two URLs that Mjolnir uses to reach the homeserver, one through Pantalaimon and one "raw". This example is taken from the playbook's `group_vars`:
```yaml
# Endpoint URL that Mjolnir uses to interact with the matrix homeserver (client-server API).
# Set this to the pantalaimon URL if you're using that.
matrix_bot_mjolnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_mjolnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
# Endpoint URL that Mjolnir could use to fetch events related to reports (client-server API and /_synapse/),
# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
```
### 5b. Configuration without E2EE support
When NOT using Pantalaimon, Mjolnir does not log in by itself and you must give it an access token for its bot account.
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with the your own values.

88
docs/configuring-playbook-bot-postmoogle.md
View File

@ -1,88 +0,0 @@
# Setting up Postmoogle (optional)
**Note**: email bridging can also happen via the [email2matrix](configuring-playbook-email2matrix.md) bridge supported by the playbook.
The playbook can install and configure [Postmoogle](https://github.com/etkecc/postmoogle) for you.
It's a bot/bridge you can use to forward emails to Matrix rooms.
Postmoogle runs an SMTP email server and allows you to assign mailbox addresses to Matrix rooms.
See the project's [documentation](https://github.com/etkecc/postmoogle) to learn what it does and why it might be useful to you.
## Prerequisites
### Networking
Open the following ports on your server to be able to receive incoming emails:
- `25/tcp`: SMTP
- `587/tcp`: Submission (TLS-encrypted SMTP)
If you don't open these ports, you will still be able to send emails, but not receive any.
These port numbers are configurable via the `matrix_bot_postmoogle_smtp_host_bind_port` and `matrix_bot_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use.
### Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_postmoogle_enabled: true
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_postmoogle_login: postmoogle
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
matrix_bot_postmoogle_password: PASSWORD_FOR_THE_BOT
# Uncomment to add one or more admins to this bridge:
#
# matrix_bot_postmoogle_admins:
# - '@yourAdminAccount:domain.com'
#
# .. unless you've made yourself an admin of all bridges like this:
#
# matrix_admin: '@yourAdminAccount:domain.com'
```
### DNS
You will also need to add several DNS records so that Postmoogle can send emails.
See [Configuring DNS](configuring-dns.md).
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
**Notes**:
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
- if you change the bot password (`matrix_bot_postmoogle_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_postmoogle_password` to let the bot know its new password
## Usage
To use the bot, invite the `@postmoogle:DOMAIN` bot user into a room you want to use as a mailbox.
Then send `!pm mailbox NAME` to expose this Matrix room as an inbox with the email address `NAME@matrix.domain`. Emails sent to that email address will be forwarded to the room.
Send `!pm help` to the room to see the bot's help menu for additional commands.
You can also refer to the upstream [documentation](https://github.com/etkecc/postmoogle).
### Debug/Logs
As with all other services, you can find their logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by running something like `journalctl -fu matrix-bot-postmoogle`
The default logging level for this bridge is `INFO`, but you can increase it to `DEBUG` with the following additional configuration:
```yaml
matrix_bot_postmoogle_loglevel: 'DEBUG'
```

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

@ -1,8 +1,6 @@
# 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) 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.
**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.
The playbook can install and configure [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) for you.
@ -23,14 +21,8 @@ matrix_appservice_discord_enabled: true
matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
```
5. As of Synapse 1.90.0, you will need to add the following to `matrix_synapse_configuration_extension_yaml` to enable the [backwards compatibility](https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs:
```yaml
matrix_synapse_configuration_extension_yaml: |
use_appservice_legacy_authorization: true
```
*Note*: This deprecated method is considered insecure.
6. 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.
5. 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.
Other configuration options are available via the `matrix_appservice_discord_configuration_extension_yaml` variable.
@ -69,7 +61,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

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

@ -1,64 +0,0 @@
# 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.
**NOTE**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
See the project's [documentation](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) 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/custom/matrix-bridge-appservice-kakaotalk/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature
## 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.

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

@ -1,6 +1,6 @@
# Setting up Appservice Slack (optional)
**Note**: bridging to [Slack](https://slack.com) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges supported by the playbook.
**Note**: bridging to [Slack](https://slack.com) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) bridge supported by the playbook.
The playbook can install and configure [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) for you.
@ -20,24 +20,8 @@ matrix_appservice_slack_enabled: true
matrix_appservice_slack_control_room_id: "Your matrix admin room id"
```
3. Enable puppeting (optional, but recommended)
```yaml
matrix_appservice_slack_puppeting_enabled: true
matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
```
4. Enable Team Sync (optional)
```yaml
matrix_appservice_slack_team_sync_enabled: true
```
See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
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.
5. Invite the bridge bot user into the admin room:
3. 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.
4. Invite the bridge bot user into the admin room:
```
/invite @slackbot:MY.DOMAIN
@ -45,7 +29,7 @@ matrix_appservice_slack_team_sync_enabled: true
Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
6. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
5. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
Name the app "matrixbot" (or anything else you'll remember).
@ -53,7 +37,7 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
7. Click on Event Subscriptions and enable them and use the request url `https://matrix.DOMAIN/appservice-slack`. Then add the following events and save:
6. Click on Event Subscriptions and enable them and use the request url `https://matrix.DOMAIN/appservice-slack`. Then add the following events and save:
Bot User Events:
@ -63,7 +47,7 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
- reaction_added
- reaction_removed
8. Click on OAuth & Permissions and add the following scopes:
7. Click on OAuth & Permissions and add the following scopes:
- chat:write:bot
- users:read
@ -75,9 +59,9 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
Note: In order to make Slack files visible to matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
9. Click on Install App and Install App to Workspace. Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
8. Click on Install App and Install App to Workspace. Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
10. If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
9. For each channel you would like to bridge, perform the following steps:
* Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like !aBcDeF:example.com.
@ -102,7 +86,7 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
11. Unlinking
10. Unlinking
Channels can be unlinked again like this:
```

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

@ -26,29 +26,22 @@ you can adjust this in `inventory/host_vars/matrix.<domain-name>/vars.yml` as we
matrix_appservice_webhooks_log_level: '<log_level>'
```
3. As of Synapse 1.90.0, you will need to add the following to `matrix_synapse_configuration_extension_yaml` to enable the [backwards compatibility](https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs:
```yaml
matrix_synapse_configuration_extension_yaml: |
use_appservice_legacy_authorization: true
```
*Note*: This deprecated method is considered insecure.
3. 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.
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.
4. If you're using the [Dimension Integration Manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge by opening the Dimension integration manager -> Settings -> Bridges and selecting edit action for "Webhook Bridge". Press "Add self-hosted Bridge" button and populate "Provisioning URL" & "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.
5. If you're using the [Dimension Integration Manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge by opening the Dimension integration manager -> Settings -> Bridges and selecting edit action for "Webhook Bridge". Press "Add self-hosted Bridge" button and populate "Provisioning URL" & "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.
6. Invite the bridge bot user to your room:
5. Invite the bridge bot user to your room:
- either with `/invite @_webhook:<domain.name>` (*Note*: Make sure you have administration permissions in your room)
- or simply add the bridge bot to a private channel (personal channels imply you being an administrator)
7. Send a message to the bridge bot in order to receive a private message including the webhook link.
6. Send a message to the bridge bot in order to receive a private message including the webhook link.
```
!webhook
```
8. The JSON body for posting messages will have to look like this:
7. The JSON body for posting messages will have to look like this:
```json
{
"text": "Hello world!",

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

@ -1,8 +1,8 @@
# Setting up Beeper Linkedin (optional)
The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the other mautrix bridges
The playbook can install and configure [beeper-linkedin](https://gitlab.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the other mautrix bridges
See the project's [documentation](https://github.com/beeper/linkedin/blob/master/README.md) to learn what it does and why it might be useful to you.
See the project's [documentation](https://gitlab.com/beeper/linkedin/-/blob/master/README.md) to learn what it does and why it might be useful to you.
```yaml
matrix_beeper_linkedin_enabled: true
@ -27,16 +27,18 @@ matrix_beeper_linkedin_configuration_extension_yaml: |
'@YOUR_USERNAME:YOUR_DOMAIN': admin
```
You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
You may wish to look at `roles/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
## Set up Double Puppeting by enabling Appservice Double Puppet or Shared Secret Auth
## Set up Double Puppeting
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
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.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
### Method 1: automatically, by enabling Shared Secret Auth
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
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.
## Usage

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

@ -1,23 +0,0 @@
# 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.

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

@ -8,7 +8,7 @@ See the project's [README](https://github.com/hifi/heisenbridge/blob/master/READ
## Configuration
Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/custom/matrix-bridge-heisenbridge/defaults/main.yml).
Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/matrix-bridge-heisenbridge/defaults/main.yml).
At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.DOMAIN/vars.yml`):
@ -22,8 +22,6 @@ matrix_heisenbridge_owner: "@you:your-homeserver"
matrix_heisenbridge_identd_enabled: true
```
By default, Heisenbrdige would be exposed on the Matrix domain (`matrix.DOMAIN`, as specified in `matrix_server_fqn_matrix`) under the `/heisenbridge` path prefix. It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)).
That's it! A registration file is automatically generated during the setup phase.
Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` will be made the owner.

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

@ -4,45 +4,21 @@ 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/latest/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/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/latest/setup.html) to learn what the individual options do.
Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/setup.html) to learn what the individual options do.
1. Enable the bridge by adding `matrix_hookshot_enabled: true` to your `vars.yml` file
2. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) as required.
3. 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).
4. 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-aux-role) explained below.
5. 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`.
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.
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/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/custom/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
Finally, run the playbook (see [installing](installing.md)).
### End-to-bridge encryption
You can enable [experimental encryption](https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html) for Hookshot by adding `matrix_hookshot_experimental_encryption_enabled: true` to your configuration (`vars.yml`) and [executing the playbook](installing.md) again.
Should the crypto store be corrupted, you can reset it by executing this Ansible playbook with the tag `reset-hookshot-encryption` added, for example `ansible-playbook -i inventory/hosts setup.yml -K --tags=reset-hookshot-encryption`).
## Usage
Create a room and invite the Hookshot bot (`@hookshot:DOMAIN`) to it.
Make sure the bot is able to send state events (usually the Moderator power level in clients).
Send a `!hookshot help` message to see a list of help commands.
Refer to [Hookshot's documentation](https://matrix-org.github.io/matrix-hookshot/latest/usage.html) for more details about using the brige's various features.
**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.
## More setup documentation
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.
### URLs for bridges setup
@ -50,37 +26,36 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
| listener | default path | variable | used as |
|---|---|---|---|
| - | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | Webhook-prefix, which affects all webhook-related URLs below |
| generic | `/hookshot/webhooks/webhook` | `matrix_hookshot_generic_endpoint` | Generic webhooks |
| 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 | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and exposure enabled via `matrix_hookshot_metrics_proxying_enabled` or `matrix_metrics_exposure_enabled`. Read more in the [Metrics section](#metrics) below. | Prometheus |
| widgets | `/hookshot/widgetapi/` | `/matrix_hookshot_widgets_endpoint` | Widgets |
| metrics | `/hookshot/metrics/` (on `stats.` subdomain) | `matrix_hookshot_metrics_endpoint` | Prometheus |
Also see the various `matrix_hookshot_container_labels_*` variables in in [default/main.yml](/roles/custom/matrix-bridge-hookshot/default/main.yml), which expose URLs publicly.
See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/matrix-bridge-hookshot/tasks/init.yml).
The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
### Manage GitHub Private Key with aux role
### Manage GitHub Private Key with matrix-aux role
The GitHub bridge requires you to install a private key file. This can be done in multiple ways:
- copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml)).
- copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml)).
- somehow copy the file to the path `{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
- use the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) to copy the file from an arbitrary path on your ansible client to the correct path on the server.
- use the `matrix-aux` role to copy the file from an arbitrary path on your ansible client to the correct path on the server.
To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following additional configuration:
To use `matrix-aux`, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add to `matrix-aux` configuration like this:
```yaml
aux_file_definitions:
matrix_aux_file_definitions:
- dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
content: "{{ lookup('file', '/path/to/your-github-private-key.pem') }}"
mode: '0400'
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
```
For more information, see the documentation in the [default configuration of the aux role](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml).
For more info see the documentation in the [matrix-aux base configuration file](/roles/matrix-aux/defaults/main.yml).
### Provisioning API
@ -88,17 +63,8 @@ The provisioning API will be enabled automatically if you set `matrix_dimension_
### Metrics
Metrics are **only enabled by default** if the builtin [Prometheus](configuring-playbook-prometheus-grafana.md) is enabled (by default, Prometheus isn't enabled). If so, metrics will automatically be collected by Prometheus and made available in Grafana. You will, however, need to set up your own Dashboard for displaying them.
To explicitly enable metrics, use `matrix_hookshot_metrics_enabled: true`. This only exposes metrics over the container network, however.
**To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to enable metrics exposure on `https://matrix.DOMAIN/metrics/hookshot` by:
- either enabling metrics exposure for Hookshot via `matrix_hookshot_metrics_proxying_enabled: true`
- or enabling metrics exposure for all services via `matrix_metrics_exposure_enabled: true`
Whichever one you go with, by default metrics are exposed publicly **without** password-protection. See [the Prometheus and Grafana docs](configuring-playbook-prometheus-grafana.md) for details about password-protection for metrics.
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).
### Collision with matrix-appservice-webhooks
If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_userIdPrefix: '_webhooks_'`).
If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_user_id_prefix: '_webhooks_'`).

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

@ -1,93 +0,0 @@
# 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 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
There are 2 ways to login to discord using this bridge, either by [scanning a QR code](#method-1-login-using-qr-code-recommended) using the Discord mobile app **or** by using a [Discord token](#method-2-login-using-discord-token-not-recommended).
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/custom/matrix-bridge-mautrix-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-mautrix-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_discord_configuration_extension_yaml` variable
### 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 Appservice Double Puppet or Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
#### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature
## Usage
### Logging in
#### Method 1: Login using QR code (recommended)
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.
#### Method 2: Login using Discord token (not recommended)
To acquire the token, open Discord in a private browser window. Then open the developer settings (keyboard shortcut might be "ctrl+shift+i" or by pressing "F12"). Navigate to the "Network" tab then reload the page. In the URL filter or search bar type "/api" and find the response with the file name of "library". Under the request headers you should find a variable called "Authorization", this is the token to your Discord account. After copying the token, you can close the browser window.
### Bridging
1. Start a chat with `@discordbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
2. If you would like to login to Discord using a token, send `login-token` command, otherwise, send `login-qr` command.
3. You'll see a QR code which you need to scan with the Discord app on your phone. You can scan it with the camera app too, which will open Discord, which will then instruct you to scan it a 2nd time in the Discord app.
4. After confirming (in the Discord app) that you'd like to allow this login, the bot should respond with "Succcessfully authenticated as ..."
5. Now that you're logged in, you can send 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.

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

@ -1,7 +1,5 @@
# Setting up Mautrix Facebook (optional)
**Note**: bridging to Facebook [Messenger](https://messenger.com) via this bridge is being [superseded by a new bridge - mautrix-meta](https://github.com/mautrix/facebook/issues/332). For now, the mautrix-facebook bridge continues to work, but the new [mautrix-meta-messenger bridge](./configuring-playbook-bridge-mautrix-meta-messenger.md) is better and more supported. Consider using that bridge instead of this one.
The playbook can install and configure [mautrix-facebook](https://github.com/mautrix/facebook) for you.
See the project's [documentation](https://github.com/mautrix/facebook/blob/master/ROADMAP.md) to learn what it does and why it might be useful to you.
@ -26,22 +24,10 @@ 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:{{ matrix_domain }}': admin
'@YOUR_USERNAME:YOUR_DOMAIN': admin
```
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/custom/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-facebook/defaults/main.yml` to find other things you would like to configure.
You may wish to look at `roles/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` to find other things you would like to configure.
## Set up Double Puppeting
@ -60,7 +46,13 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- 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-Facebook", "initial_device_display_name": "Mautrix-Facebook"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
@ -99,5 +91,3 @@ 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

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

@ -1,38 +0,0 @@
# Setting up Mautrix gmessages (optional)
The playbook can install and configure [mautrix-gmessages](https://github.com/mautrix/gmessages) for you, for bridging to [Google Messages](https://messages.google.com/).
See the project's [documentation](https://docs.mau.fi/bridges/go/gmessages/index.html) to learn what it does and why it might be useful to you.
Use the following playbook configuration:
```yaml
matrix_mautrix_gmessages_enabled: true
```
## 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 Appservice Double Puppet
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
### 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-gmessages` device some time in the future, as that would break the Double Puppeting feature
## Usage
You then need to start a chat with `@gmessagesbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

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

@ -16,13 +16,11 @@ matrix_mautrix_googlechat_enabled: true
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 Appservice Double Puppet or Shared Secret Auth
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
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
@ -31,7 +29,13 @@ Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playb
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- 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-googlechat", "initial_device_display_name": "Mautrix-googlechat"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

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

@ -31,7 +31,13 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- 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-Hangouts", "initial_device_display_name": "Mautrix-Hangouts"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

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

@ -1,7 +1,5 @@
# Setting up Mautrix Instagram (optional)
**Note**: bridging to Facebook [Instagram](https://instagram.com) via this bridge is being [superseded by a new bridge - mautrix-meta](https://github.com/mautrix/facebook/issues/332). For now, the mautrix-instagram bridge continues to work, but the new [mautrix-meta-instagram bridge](./configuring-playbook-bridge-mautrix-meta-instagram.md) is better and more supported. Consider using that bridge instead of this one.
The playbook can install and configure [mautrix-instagram](https://github.com/mautrix/instagram) for you.
See the project's [documentation](https://docs.mau.fi/bridges/python/instagram/index.html) to learn what it does and why it might be useful to you.
@ -9,32 +7,6 @@ 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/custom/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure.
## Usage

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

@ -1,90 +0,0 @@
# Setting up Instagram bridging via Mautrix Meta (optional)
The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you.
Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
This documentation page only deals with the bridge's ability to bridge to Instagram. For bridging to Facebook/Messenger, see [Setting up Messenger bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-messenger.md).
## Migrating from the old mautrix-instagram bridge
If you've been using the [mautrix-instagram](./configuring-playbook-bridge-mautrix-instagram.md) bridge, **you'd better get rid of it first** or the 2 bridges will be in conflict:
- both trying to use `@instagrambot:YOUR_DOMAIN` as their username. This conflict may be resolved by adjusting `matrix_mautrix_instagram_appservice_bot_username` or `matrix_mautrix_meta_instagram_appservice_username`
- both trying to bridge the same DMs
To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@instagrambot:YOUR_DOMAIN`).
This would give you a list of portals and groups of portals you may purge. Proceed with sending commands like `clean recommended`, etc.
Then, consider disabling the old bridge in your configuration, so it won't recreate the portals when you receive new messages.
## Configuration
Most simply, you can enable the bridge with the following playbook configuration:
```yaml
matrix_mautrix_meta_instagram_enabled: true
```
Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
### Bridge permissions
By default, any user on your homeserver will be able to use the bridge.
Different levels of permission can be granted to users:
- `relay` - Allowed to be relayed through the bridge, no access to commands
- `user` - Use the bridge with puppeting
- `admin` - Use and administer the bridge
The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
The default permissions are set via `matrix_mautrix_meta_instagram_bridge_permissions_default` and are somewhat like this:
```yaml
matrix_mautrix_meta_instagram_bridge_permissions_default:
'*': relay
YOUR_DOMAIN: user
'{{ matrix_admin }}': admin
```
If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:YOUR_DOMAIN`), then there's no admin by default.
You may redefine `matrix_mautrix_meta_instagram_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_instagram_bridge_permissions_custom` like this:
```yaml
matrix_mautrix_meta_instagram_bridge_permissions_custom:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
## 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 Appservice Double Puppet
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
### 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
## Usage
You then need to start a chat with `@instagrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

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

@ -1,105 +0,0 @@
# Setting up Messenger bridging via Mautrix Meta (optional)
The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you.
Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
This documentation page only deals with the bridge's ability to bridge to Facebook Messenger. For bridging to Instagram, see [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md).
## Migrating from the old mautrix-facebook bridge
If you've been using the [mautrix-facebook](./configuring-playbook-bridge-mautrix-facebook.md) bridge, it's possible to migrate the database using [instructions from the bridge documentation](https://docs.mau.fi/bridges/go/meta/facebook-migration.html) (advanced).
Then you may wish to get rid of the Facebook bridge. To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@facebookbot:YOUR_DOMAIN`).
This would give you a list of portals and groups of portals you may purge. Proceed with sending commands like `clean recommended`, etc.
Then, consider disabling the old bridge in your configuration, so it won't recreate the portals when you receive new messages.
## Configuration
Most simply, you can enable the bridge with the following playbook configuration:
```yaml
matrix_mautrix_meta_messenger_enabled: true
```
Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
### Bridge mode
As mentioned above, the [mautrix-meta](https://github.com/mautrix/meta) bridge supports multiple modes of operation.
The bridge can pull your Messenger messages via 3 different methods:
- (`facebook`) Facebook via `facebook.com`
- (`facebook-tor`) Facebook via `facebookwkhpilnemxj7asaniu7vnjjbiltxjqhye3mhbshg7kx5tfyd.onion` ([Tor](https://www.torproject.org/)) - does not currently proxy media downloads
- (default) (`messenger`) Messenger via `messenger.com` - usable even without a Facebook account
You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variable. The playbook defaults to the `messenger` mode, because it's most universal (every Facebook user has a Messenger account, but the opposite is not true).
Note that switching the mode (especially between `facebook*` and `messenger`) will intentionally make the bridge use another database (`matrix_mautrix_meta_facebook` or `matrix_mautrix_meta_messenger`) to isolate the 2 instances. Switching between Tor and non-Tor may be possible without dataloss, but your mileage may vary. Before switching to a new mode, you may wish to de-configure the old one (send `help` to the bridge bot and unbridge your portals, etc.).
### Bridge permissions
By default, any user on your homeserver will be able to use the bridge.
Different levels of permission can be granted to users:
- `relay` - Allowed to be relayed through the bridge, no access to commands
- `user` - Use the bridge with puppeting
- `admin` - Use and administer the bridge
The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permissions_default` and are somewhat like this:
```yaml
matrix_mautrix_meta_messenger_bridge_permissions_default:
'*': relay
YOUR_DOMAIN: user
'{{ matrix_admin }}': admin
```
If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:YOUR_DOMAIN`), then there's no admin by default.
You may redefine `matrix_mautrix_meta_messenger_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_messenger_bridge_permissions_custom` like this:
```yaml
matrix_mautrix_meta_messenger_bridge_permissions_custom:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
## 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 Appservice Double Puppet
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
### 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
## Usage
You then need to start a chat with `@messengerbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to send a `login` command and follow the bridge bot's instructions.
Given that the bot is configured in `messenger` [bridge mode](#bridge-mode) by default, you will need to log in to [messenger.com](https://messenger.com/) (not `facebook.com`!) and obtain the cookies from there as per [the bridge's authentication instructions](https://docs.mau.fi/bridges/go/meta/authentication.html).

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

@ -6,8 +6,6 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/signal/inde
**Note/Prerequisite**: If you're running with the Postgres database server integrated by the playbook (which is the default), you don't need to do anything special and can easily proceed with installing. However, if you're [using an external Postgres server](configuring-playbook-external-postgres.md), you'd need to manually prepare a Postgres database for this bridge and adjust the variables related to that (`matrix_mautrix_signal_database_*`).
**Note**: This revamped version of the [mautrix-signal (legacy)](configuring-playbook-bridge-mautrix-signal.md) may increase the CPU usage of your homeserver.
Use the following playbook configuration:
```yaml
@ -16,7 +14,14 @@ matrix_mautrix_signal_enabled: true
There are some additional things you may wish to configure about the bridge before you continue.
The relay bot functionality is off by default. If you would like to enable the relay bot, add the following to your `vars.yml` file:
```yaml
matrix_mautrix_signal_relaybot_enabled: true
```
If you want to activate the relay bot in a room, use `!signal set-relay`.
Use `!signal unset-relay` to deactivate.
By default, any user on your homeserver will be able to use the bridge.
If you enable the relay bot functionality, it will relay every user's messages in a portal room - no matter which homeserver they're from.
Different levels of permission can be granted to users:
@ -41,24 +46,24 @@ matrix_mautrix_signal_configuration_extension_yaml: |
'@YOUR_USERNAME:YOUR_DOMAIN': admin
```
This will add the admin permission to the specific user, while keeping the default permissions.
This will add the admin permission to the specific user, while keepting the default permissions.
In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file:
```yaml
matrix_mautrix_signal_bridge_permissions:
matrix_mautrix_signal_bridge_permissions: |
'@ADMIN:YOUR_DOMAIN': admin
'@USER:YOUR_DOMAIN' : user
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
You may wish to look at `roles/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
## 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 Appservice Double Puppet
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
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.
@ -68,7 +73,13 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- 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-Signal", "initial_device_display_name": "Mautrix-Signal"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

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

@ -1,75 +0,0 @@
# Setting up Mautrix Slack (optional)
**Note**: bridging to [Slack](https://slack.com/) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) bridges supported by the playbook.
- For using as a Bot we recommend the [Appservice Slack](configuring-playbook-bridge-appservice-slack.md), because it supports plumbing.
- For personal use with a slack account we recommend the `mautrix-slack` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Slack bridges supported by the playbook.
The playbook can install and configure [mautrix-slack](https://github.com/mautrix/slack) for you.
See the project's [documentation](https://docs.mau.fi/bridges/go/slack/index.html) to learn what it does and why it might be useful to you.
See the [features and roadmap](https://github.com/mautrix/slack/blob/main/ROADMAP.md) for more information.
## Prerequisites
For using this bridge, you would need to authenticate by **providing your username and password** (legacy) or by using a **token login**. See more information in the [docs](https://docs.mau.fi/bridges/go/slack/authentication.html).
Note that neither of these methods are officially supported by Slack. [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) uses a Slack bot account which is the only officially supported method for bridging a Slack channel.
## Installing
To enable the bridge, add this to your `vars.yml` file:
```yaml
matrix_mautrix_slack_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 options you may wish to configure with the bridge.
Take a look at:
- `roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-mautrix-slack/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_slack_configuration_extension_yaml` variable
### 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 Appservice Double Puppet
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature
## Usage
1. Start a chat with `@slackbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
2. If you would like to login to Slack using a token, send the `login-token` command, otherwise, send the `login-password` command. Read [here](https://docs.mau.fi/bridges/go/slack/authentication.html) on how to retrieve your token and cookie token.
3. The bot should respond with "Successfully logged into <email> for team <workspace>"
4. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to.
5. Slack channels should automatically begin bridging if you authenticated using a token. Otherwise, you must wait to receive a message in the channel if you used password authentication.

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

@ -16,13 +16,11 @@ matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
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 Appservice Double Puppet or Shared Secret Auth
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
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
@ -30,7 +28,13 @@ Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playb
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- 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-Telegram", "initial_device_display_name": "Mautrix-Telegram"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send `login-matrix` to the bot and follow instructions about how to send the access token to it
@ -61,8 +65,3 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
More details about permissions in this example:
https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
If you like to exclude all groups from syncing and use the Telgeram-Bridge only for direct chats, you can add the following additional playbook configuration:
```yaml
matrix_mautrix_telegram_filter_mode: whitelist
```

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

@ -15,13 +15,11 @@ matrix_mautrix_twitter_enabled: true
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 Appservice Double Puppet or Shared Secret Auth
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
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

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

@ -8,33 +8,35 @@ Use the following playbook configuration:
```yaml
matrix_mautrix_whatsapp_enabled: true
```
```
Whatsapp multidevice beta is required, now it is enough if Whatsapp is connected to the Internet every 2 weeks.
The relay bot functionality is off by default. If you would like to enable the relay bot, add the following to your `vars.yml` file:
```yaml
matrix_mautrix_whatsapp_bridge_relay_enabled: true
```
## Enable backfilling history
This requires a server with MSC2716 support, which is currently an experimental feature in synapse.
Note that as of Synapse 1.46, there are still some bugs with the implementation, especially if using event persistence workers.
Use the following playbook configuration:
By default, only admins are allowed to set themselves as relay users. To allow anyone on your homeserver to set themselves as relay users add this to your `vars.yml` file:
```yaml
matrix_mautrix_whatsapp_bridge_relay_admin_only: false
matrix_synapse_configuration_extension_yaml: |
experimental_features:
msc2716_enabled: true
```
```yaml
matrix_mautrix_whatsapp_configuration_extension_yaml:
bridge:
history_sync:
backfill: true
```
If you want to activate the relay bot in a room, use `!wa set-relay`.
Use `!wa unset-relay` to deactivate.
## 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 Appservice Double Puppet or Shared Secret Auth
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
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
@ -42,7 +44,13 @@ Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playb
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- 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-Whatsapp", "initial_device_display_name": "Mautrix-Whatsapp"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

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

@ -1,33 +0,0 @@
# Setting up Mautrix wsproxy (optional)
The playbook can install and configure [mautrix-wsproxy](https://github.com/mautrix/wsproxy) for you.
See the project's [documentation](https://github.com/mautrix/wsproxy#readme) to learn what it does and why it might be useful to you.
## DNS
You need to create a `wsproxy.DOMAIN` DNS record pointing to your Matrix server (a `CNAME` pointing to `matrix.DOMAIN`) to use wsproxy.
The hostname is configurable via a `matrix_mautrix_wsproxy_hostname` variable.
## Configuration
Use the following playbook configuration:
```yaml
matrix_mautrix_wsproxy_enabled: true
matrix_mautrix_androidsms_appservice_token: 'secret token from bridge'
matrix_mautrix_androidsms_homeserver_token: 'secret token from bridge'
matrix_mautrix_imessage_appservice_token: 'secret token from bridge'
matrix_mautrix_imessage_homeserver_token: 'secret token from bridge'
matrix_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge'
```
Note that the tokens must match what is compiled into the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android device.
## Usage
Follow the [matrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).

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

@ -1,8 +1,6 @@
# 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)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.
**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.
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/xangelix-pub/matrix/mx-puppet-groupme) for you.
[mx-puppet-groupme](https://gitlab.com/robintown/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,5 +1,30 @@
# Setting up MX Puppet Skype (optional)
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.
The playbook can install and configure
[mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) for you.
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.
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.

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

@ -1,7 +1,8 @@
# Setting up MX Puppet Slack (optional)
**Note**: bridging to [Slack](https://slack.com) can also happen via the
[matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges supported by the playbook.
[matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md)
bridge supported by the playbook.
The playbook can install and configure [Beeper](https://www.beeper.com/)-maintained fork of
[mx-puppet-slack](https://gitlab.com/beeper/mx-puppet-monorepo) for you.

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

@ -1,17 +0,0 @@
# Setting up the WeChat Bridge (optional)
The playbook can install and configure the [matrix-wechat](https://github.com/duo/matrix-wechat) bridge for you (for bridging to the [WeChat](https://www.wechat.com/) network).
See the project page to learn what it does and why it might be useful to you.
To enable the bridge, use the following playbook configuration and re-run the playbook's [installation](./installing.md) procedure:
```yaml
matrix_wechat_enabled: true
```
## Usage
Once the bridge is installed, start a chat with `@wechatbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Send `help` to the bot to see the available commands.

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

@ -1,77 +0,0 @@
# Setting up Cactus Comments (optional)
The playbook can install and configure the [Cactus Comments](https://cactus.chat) system for you.
Cactus Comments is a **federated comment system** built on Matrix. It respects your privacy, and puts you in control.
See the project's [documentation](https://cactus.chat/docs/getting-started/introduction/) to learn what it
does and why it might be useful to you.
The playbook contains 2 roles for configuring different pieces of the Cactus Comments system:
- `matrix-cactus-comments` - the backend appservice integrating with the Matrix homeserver
- `matrix-cactus-comments-client` - a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`)
You can enable whichever component you need (typically both).
## Configuration
Add the following block to your `vars.yaml` and make sure to exchange the tokens to randomly generated values.
```yaml
#################
## Cactus Chat ##
#################
# This enables the backend (appservice)
matrix_cactus_comments_enabled: true
# To allow guest comments without users needing to log in, you need to have guest registration enabled.
# To do this you need to uncomment one of the following lines (depending if you are using Synapse or Dendrite as a homeserver)
# If you don't know which one you use: The default is Synapse ;)
# matrix_synapse_allow_guest_access: true
# matrix_dendrite_allow_guest_access: true
# This enables client assets static files serving on `https://matrix.DOMAIN/cactus-comments`.
# When the backend (appservice) is enabled, this is also enabled automatically,
# but we explicitly enable it here.
matrix_cactus_comments_client_enabled: true
# Uncomment and adjust if you'd like to host the client assets at a different location.
# These variables are only make used if (`matrix_cactus_comments_client_enabled: true`)
# matrix_cactus_comments_client_hostname: "{{ matrix_server_fqn_matrix }}"
# matrix_cactus_comments_client_path_prefix: /cactus-comments
```
## Installing
After configuring the playbook, run the [installation](installing.md) command again.
## Usage
Upon starting Cactus Comments, a `bot.cactusbot` user account is created automatically.
To get started, send a `help` message to the `@bot.cactusbot:your-homeserver.com` bot to confirm it's working.
Then, register a site by typing: `register <sitename>`. You will then be invited into a moderation room.
Now you are good to go and can include the comment section on your website!
**Careful:** To really make use of self-hosting you need change a few things in comparison to the official docs!
Insert the following snippet into you page and make sure to replace `example.com` with your base domain!
```html
<script type="text/javascript" src="https://matrix.example.com/cactus-comments/cactus.js"></script>
<link rel="stylesheet" href="https://matrix.example.com/cactus-comments/style.css" type="text/css">
<div id="comment-section"></div>
<script>
initComments({
node: document.getElementById("comment-section"),
defaultHomeserverUrl: "https://matrix.example.com:8448",
serverName: "example.com",
siteName: "YourSiteName",
commentSectionId: "1"
})
</script>
```

10
docs/configuring-playbook-client-element.md
View File

@ -1,6 +1,6 @@
# Configuring Element (optional)
By default, this playbook installs the [Element](https://github.com/element-hq/element-web) Matrix client web application.
By default, this playbook installs the [Element](https://github.com/vector-im/element-web) Matrix client web application.
If that's okay, you can skip this document.
@ -17,7 +17,7 @@ matrix_client_element_enabled: false
The playbook provides some customization variables you could use to change Element's settings.
Their defaults are defined in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-element/templates/config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2) template.
Their defaults are defined in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/matrix-client-element/templates/config.json.j2`](../roles/matrix-client-element/templates/config.json.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
@ -25,14 +25,14 @@ Alternatively, **if there is no pre-defined variable** for an Element setting yo
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Element's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2)) by making use of the `matrix_client_element_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/matrix-client-element/templates/config.json.j2)) by making use of the `matrix_client_element_configuration_extension_json_` variable. You can find information about this in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml).
## Themes
To change the look of Element, you can define your own themes manually by using the `matrix_client_element_setting_defaults_custom_themes` setting.
To change the look of Element, you can define your own themes manually by using the `matrix_client_element__settingDefaults_custom_themes` setting.
Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_element_themes_enabled: true`).

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

@ -1,6 +1,6 @@
# Configuring Hydrogen (optional)
This playbook can install the [Hydrogen](https://github.com/element-hq/hydrogen-web) Matrix web client for you.
This playbook can install the [Hydrogen](https://github.com/vector-im/hydrogen-web) Matrix web client for you.
Hydrogen is a lightweight web client that supports mobile and legacy web browsers.
Hydrogen can be installed alongside or instead of Element.

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

@ -1,42 +0,0 @@
# Configuring SchildiChat (optional)
By default, this playbook does not install the [SchildiChat](https://github.com/SchildiChat/schildichat-desktop) Matrix client web application.
**WARNING**: SchildiChat is based on Element-web, but its releases are lagging behind. As an example (from 2024-02-26), SchildiChat is 22 releases behind (it being based on element-web `v1.11.36`, while element-web is now on `v1.11.58`). Element-web frequently suffers from security issues, so running something based on an ancient Element-web release is **dangerous**. Use SchildiChat at your own risk!
## Enabling SchildiChat
If you'd like for the playbook to install SchildiChat, you can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_client_schildichat_enabled: true
```
## Configuring SchildiChat settings
The playbook provides some customization variables you could use to change schildichat's settings.
Their defaults are defined in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml) and they ultimately end up in the generated `/matrix/schildichat/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-schildichat/templates/config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for an schildichat setting you wish to change:
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of schildichat's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2)) by making use of the `matrix_client_schildichat_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_schildichat_configuration_default` (or `matrix_client_schildichat_configuration`). You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
## Themes
To change the look of schildichat, you can define your own themes manually by using the `matrix_client_schildichat_setting_defaults_custom_themes` setting.
Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_schildichat_themes_enabled: true`).
If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
Note that for a custom theme to work well, all schildichat instances that you use must have the same theme installed.

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

@ -1,57 +0,0 @@
# Configuring Conduit (optional)
By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Conduit](https://conduit.rs).
**NOTES**:
- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Conduit). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
- **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
## Installation
To use Conduit, you **generally** need the following additional `vars.yml` configuration:
```yaml
matrix_homeserver_implementation: conduit
```
However, since Conduit is difficult (see [famedly/conduit#276](https://gitlab.com/famedly/conduit/-/issues/276) and [famedly/conduit#354](https://gitlab.com/famedly/conduit/-/merge_requests/354)) when it comes to creating the first user account and does not support [registering users](registering-users.md) (via the command line or via the playbook) like Synapse and Dendrite do, we recommend the following flow:
1. Add `matrix_conduit_allow_registration: true` to your `vars.yml` the first time around, temporarily
2. Run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` - see [Installing](installing.md))
3. Create your first user via Element or any other client which supports creating users
4. Get rid of `matrix_conduit_allow_registration: true` from your `vars.yml`
5. Run the playbook again (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-conduit,start` would be enough this time)
6. You can now use your server safely. Additional users can be created by messaging the internal Conduit bot
## Configuring bridges / appservices
Automatic appservice setup is currently unsupported when using conduit. After setting up the service as usual you may notice that it is unable to start.
You will have to manually register appservices using the the [register-appservice](https://gitlab.com/famedly/conduit/-/blob/next/APPSERVICES.md) command.
Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`, then pass the content to conduit:
@conduit:your.server.name: register-appservice
```
as_token: <token>
de.sorunome.msc2409.push_ephemeral: true
hs_token: <token>
id: signal
namespaces:
aliases:
- exclusive: true
regex: ^#signal_.+:example\.org$
users:
- exclusive: true
regex: ^@signal_.+:example\.org$
- exclusive: true
regex: ^@signalbot:example\.org$
rate_limited: false
sender_localpart: _bot_signalbot
url: http://matrix-mautrix-signal:29328
```

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

@ -1,32 +0,0 @@
# Configuring Dendrite (optional)
By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Dendrite](https://github.com/matrix-org/dendrite).
**NOTES**:
- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Dendrite). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
- **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
The playbook provided settings for Dendrite are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for a Dendrite setting you wish to change:
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Dendrite's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2)) by making use of the `matrix_dendrite_configuration_extension_yaml` variable. You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_dendrite_configuration` (or `matrix_dendrite_configuration_yaml`). You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
## Installation
To use Dendrite, you **generally** need the following additional `vars.yml` configuration:
```yaml
matrix_homeserver_implementation: dendrite
```

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

@ -3,34 +3,17 @@
**[Dimension](https://dimension.t2bot.io) can only be installed after Matrix services are installed and running.**
If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) flow and come back here later.
**Note**: Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it.
**Note**: This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`. Enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
**Note**: This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_synapse_federation_enabled`. Enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
## Decide on a domain and path
## Prerequisites
By default, Dimension is configured to use its own dedicated domain (`dimension.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to another hostname compared to the default (`dimension.{{ matrix_domain }}`)
matrix_dimension_hostname: "integrations.{{ matrix_domain }}"
```
While there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible right now due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You must serve Dimension at a dedicated subdomain until this issue is solved.
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
The `dimension.<your-domain>` DNS record must be created. See [Configuring your DNS server](configuring-dns.md) on how to set up DNS record correctly.
## Enable
To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
[Dimension integrations manager](https://dimension.t2bot.io) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_dimension_enabled: true
@ -39,7 +22,7 @@ matrix_dimension_enabled: true
## Define admin users
These users can modify the integrations this Dimension supports.
These users can modify the integrations this Dimension supports.
Add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
@ -56,7 +39,27 @@ We recommend that you create a dedicated Matrix user for Dimension (`dimension`
Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
You are required to specify an access token (belonging to this new user) for Dimension to work.
To get an access token for the Dimension user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).
To get an access token for the Dimension user, you can follow one of two options:
*Through an interactive login*:
1. In a private browsing session (incognito window), open Element.
1. Log in with the `dimension` user and its password.
1. Set the display name and avatar, if required.
1. In the settings page choose "Help & About", scroll down to the bottom and expand the `Access Token` section.
1. Copy the access token to your configuration.
1. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
*With CURL*
```
curl -X POST --header 'Content-Type: application/json' -d '{
"identifier": { "type": "m.id.user", "user": "YourDimensionUsername" },
"password": "YourDimensionPassword",
"type": "m.login.password"
}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
```
*Change `YourDimensionUsername`, `YourDimensionPassword`, and `YOURDOMAIN` accordingly.*
**Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
@ -71,7 +74,7 @@ For more information on how to acquire an access token, visit [https://t2bot.io/
## Installation
After these variables have been set and you have potentially [adjusted your DNS records](#adjusting-dns-records), please run the following command to re-run setup and to restart Dimension:
After these variables have been set, please run the following command to re-run setup and to restart Dimension:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
@ -90,6 +93,6 @@ In the interim until the above limitation is resolved, an admin user needs to co
## Additional features
To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it.
To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-dimension/defaults/main.yml) of the Dimension component.
To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/matrix-dimension/defaults/main.yml) of the Dimension component.
You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).

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

@ -5,9 +5,9 @@ By default, this playbook sets up an [Exim](https://www.exim.org/) email server
The email server would attempt to deliver emails directly to their final destination.
This may or may not work, depending on your domain configuration (SPF settings, etc.)
By default, emails are sent from `matrix@<your-domain-name>` (as specified by the `exim_relay_sender_address` playbook variable).
By default, emails are sent from `matrix@<your-domain-name>` (as specified by the `matrix_mailer_sender_address` playbook variable).
**Note**: If you are using a Google Cloud instance, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so you need to relay email through another SMTP server as described below.
**Note**: If you are using a Google Cloud instance, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so you need to relay email through another SMTP server as described below.
## Firewall settings
@ -21,35 +21,35 @@ If you'd like to relay email through another SMTP server, feel free to redefine
Example:
```yaml
exim_relay_sender_address: "another.sender@example.com"
exim_relay_relay_use: true
exim_relay_relay_host_name: "mail.example.com"
exim_relay_relay_host_port: 587
exim_relay_relay_auth: true
exim_relay_relay_auth_username: "another.sender@example.com"
exim_relay_relay_auth_password: "some-password"
matrix_mailer_sender_address: "another.sender@example.com"
matrix_mailer_relay_use: true
matrix_mailer_relay_host_name: "mail.example.com"
matrix_mailer_relay_host_port: 587
matrix_mailer_relay_auth: true
matrix_mailer_relay_auth_username: "another.sender@example.com"
matrix_mailer_relay_auth_password: "some-password"
```
**Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.
### Configuations for sending emails using Sendgrid
An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `exim_relay_sender_address`.
An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `matrix_mailer_sender_address`.
The only other thing you need to change is the `exim_relay_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
The only other thing you need to change is the `matrix_mailer_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
Note that the `exim_relay_relay_auth_username` is literally the string `apikey`, it's always the same for Sendgrid.
Note that the `matrix_mailer_relay_auth_username` is literally the string `apikey`, it's always the same for Sendgrid.
```yaml
exim_relay_sender_address: "arbitrary@email.com"
exim_relay_relay_use: true
exim_relay_relay_host_name: "smtp.sendgrid.net"
exim_relay_relay_host_port: 587
exim_relay_relay_auth: true
exim_relay_relay_auth_username: "apikey"
exim_relay_relay_auth_password: "<your api key password>"
matrix_mailer_sender_address: "arbitrary@email.com"
matrix_mailer_relay_use: true
matrix_mailer_relay_host_name: "smtp.sendgrid.net"
matrix_mailer_relay_host_port: 587
matrix_mailer_relay_auth: true
matrix_mailer_relay_auth_username: "apikey"
matrix_mailer_relay_auth_password: "<your api key password>"
```
## Troubleshooting
If you're having trouble with email not being delivered, it may be useful to inspect the mailer logs: `journalctl -f -u matrix-exim-relay`.
If you're having trouble with email not being delivered, it may be useful to inspect the mailer logs: `journalctl -f -u matrix-mailer`.

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

@ -1,8 +1,5 @@
# Setting up Email2Matrix (optional)
**Note**: email bridging can also happen via the [Postmoogle](configuring-playbook-bot-postmoogle.md) bot supported by the playbook.
Postmoogle is much more powerful and easier to use, so we recommend that you use it, instead of Email2Matrix.
The playbook can install and configure [email2matrix](https://github.com/devture/email2matrix) for you.
See the project's [documentation](https://github.com/devture/email2matrix/blob/master/docs/README.md) to learn what it does and why it might be useful to you.
@ -10,10 +7,6 @@ See the project's [documentation](https://github.com/devture/email2matrix/blob/m
## Preparation
### DNS configuration
It's not strictly necessary, but you may increase the chances that incoming emails reach your server by adding an `MX` record for `matrix.DOMAIN`, as described in the [Configuring DNS](configuring-dns.md) documentation page.
### Port availability
Ensure that port 25 is available on your Matrix server and open in your firewall.
@ -41,7 +34,18 @@ You'll need the room id when doing [Configuration](#configuration) below.
### Obtaining an access token for the sender user
In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it.
To do this, you can execute a command like this:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "email2matrix" }, "password": "MATRIX_PASSWORD_FOR_THE_USER", "type": "m.login.password", "device_id": "Email2Matrix", "initial_device_display_name": "Email2Matrix"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
Take note of the `access_token` value. You'll need the access token when doing [Configuration](#configuration) below.
## Configuration
@ -70,6 +74,7 @@ matrix_email2matrix_matrix_mappings:
SkipMarkdown: true
```
You can also set `MatrixHomeserverUrl` to the container URL where your homeserver's Client-Server API lives by using the `{{ matrix_addons_homeserver_client_api_url }}` variable, instead of the public `https://matrix.DOMAIN` endpoint.
You can also set `MatrixHomeserverUrl` to `http://matrix-synapse:8008`, instead of the public `https://matrix.DOMAIN`.
However, that's more likely to break in the future if you switch to another server implementation than Synapse.
Re-run the playbook (`--tags=setup-email2matrix,start`) and try sending an email to `my-mailbox@matrix.DOMAIN`.

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

@ -1,81 +1,46 @@
# Setting up Etherpad (optional)
[Etherpad](https://etherpad.org) is an open source collaborative text editor that can be embedded in a Matrix chat room using the [Dimension integrations manager](https://dimension.t2bot.io) or used as standalone web app.
[Etherpad](https://etherpad.org) is is an open source collaborative text editor that can be embedded in a Matrix chat room using the [Dimension integrations manager](https://dimension.t2bot.io)
When enabled together with the Jitsi audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
## Prerequisites
## Decide on a domain and path
By default, Etherpad is configured to use its own dedicated domain (`etherpad.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
# so we won't need to add additional DNS records for Etherpad.
etherpad_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /etherpad subpath
etherpad_path_prefix: /etherpad
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
For the self-hosted Etherpad instance to be available to your users, you must first enable and configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md)
## Installing
[Etherpad](https://etherpad.org) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
etherpad_enabled: true
# Uncomment below to enable the admin web UI
# etherpad_admin_username: admin
# etherpad_admin_password: some-password
matrix_etherpad_enabled: true
```
Then, [run the installation process](installing.md) again (e.g. `just install-all`).
## Set Dimension default to the self-hosted Etherpad
The Dimension administrator users can configure the default URL template. The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab. Replace `scalar.vector.im` with your own Dimension domain.
## Usage
### Removing the integrated Etherpad chat
The Etherpad UI should be available at `https://etherpad.<your-domain>`, while the admin UI (if enabled) should then be available at `https://etherpad.<your-domain>/admin`.
If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
Example: `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false`
If you've [decided on another hostname or path-prefix](#decide-on-a-domain-and-path) (e.g. `https://matrix.DOMAIN/etherpad`), adjust these URLs accordingly before usage.
### Etherpad Admin access (optional)
Etherpad comes with a admin web-UI which is disabled by default. You can enable it by setting a username and password in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_etherpad_admin_username: admin
matrix_etherpad_admin_password: some-password
```
The admin web-UI should then be available on: `https://dimension.<your-domain>/etherpad/admin`
### Managing / Deleting old pads
If you want to manage and remove old unused pads from Etherpad, you will first need to able Admin access as described above.
Then from the plugin manager page (`https://etherpad.<your-domain>/admin/plugins`, install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
### How to use Etherpad widgets without an Integration Manager (like Dimension)
This is how it works in Element, it might work quite similar with other clients:
To integrate a standalone etherpad in a room, create your pad by visiting `https://etherpad.DOMAIN`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` section.
### Set Dimension default to the self-hosted Etherpad (optional)
If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside Etherpad, the Dimension administrator users can configure the default URL template.
The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab.
#### Removing the integrated Etherpad chat
If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
Example: `https://etherpad.<your-domain>/p/$roomId_$padName?showChat=false`
Then from the plugin manager page (`https://dimension.<your-domain>/etherpad/admin/plugins`), install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
## Known issues

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

@ -10,7 +10,7 @@ If you'd like to use an external PostgreSQL server that you manage, you can edit
If you'd like to use an external Postgres server, use a custom `vars.yml` configuration like this:
```yaml
postgres_enabled: false
matrix_postgres_enabled: false
# Rewire Synapse to use your external Postgres server
matrix_synapse_database_host: "your-postgres-server-hostname"
@ -20,7 +20,7 @@ matrix_synapse_database_database: "your-postgres-server-database-name"
# Rewire any other service (each `matrix-*` role) you may wish to use to use your external Postgres server.
# Each service expects to have its own dedicated database on the Postgres server
# and uses its own variable names (see `roles/custom/matrix-*/defaults/main.yml) for configuring Postgres connectivity.
# and uses its own variable names (see `roles/matrix-*/defaults/main.yml) for configuring Postgres connectivity.
```
The database (as specified in `matrix_synapse_database_database`) must exist and be accessible with the given credentials.

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

@ -33,7 +33,7 @@ matrix_synapse_allow_public_rooms_over_federation: true
To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_homeserver_federation_enabled: false
matrix_synapse_federation_enabled: false
```
With that, your server's users will only be able to talk among themselves, but not to anyone who is on another server.
@ -41,20 +41,17 @@ With that, your server's users will only be able to talk among themselves, but n
**Disabling federation does not necessarily disable the federation port** (`8448`). Services like [Dimension](configuring-playbook-dimension.md) and [ma1sd](configuring-playbook-ma1sd.md) normally rely on `openid` APIs exposed on that port. Even if you disable federation and only if necessary, we may still be exposing the federation port and serving the `openid` APIs there. To override this and completely disable Synapse's federation port use:
```yaml
matrix_homeserver_federation_enabled: false
# This stops the federation port on the Synapse side (normally `matrix-synapse:8048` on the container network).
matrix_synapse_federation_port_enabled: false
# This stops the federation port on the synapse-reverse-proxy-companion side (normally `matrix-synapse-reverse-proxy-companion:8048` on the container network).
matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
# This removes the `8448` virtual host from the matrix-nginx-proxy reverse-proxy server.
matrix_nginx_proxy_proxy_matrix_federation_api_enabled: false
```
## Changing the federation port from 8448 to a different port to use a CDN that only accepts 443/80 ports
Why? This change could be useful for people running small Synapse instances on small severs/VPSes to avoid being impacted by a simple DOS/DDOS when bandwidth, RAM, an CPU resources are limited and if your hosting provider does not provide a DOS/DDOS protection.
The following changes in the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other:
```

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

@ -9,12 +9,12 @@ The setup done by the playbook is very similar to [docker-jitsi-meet](https://gi
## Prerequisites
Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record (unless you've changed `jitsi_hostname`, as described below). See [Configuring DNS](configuring-dns.md) for details about DNS changes.
Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record. See [Configuring DNS](configuring-dns.md).
You may also need to open the following ports to your server:
- `4443/tcp` - RTP media fallback over TCP
- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`jitsi_jvb_stun_servers`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml)).
- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`matrix_jitsi_jvb_stun_servers`](../roles/matrix-jitsi/defaults/main.yml)).
## Installation
@ -22,86 +22,62 @@ You may also need to open the following ports to your server:
Add this to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
```yaml
jitsi_enabled: true
matrix_jitsi_enabled: true
# Uncomment and adjust if you need to use another hostname
# jitsi_hostname: "jitsi.{{ matrix_domain }}"
# Uncomment and possible adjust if you'd like to host under a subpath
# jitsi_path_prefix: /jitsi
# Run `bash inventory/scripts/jitsi-generate-passwords.sh` to generate these passwords,
# or define your own strong passwords manually.
matrix_jitsi_jicofo_auth_password: ""
matrix_jitsi_jvb_auth_password: ""
matrix_jitsi_jibri_recorder_password: ""
matrix_jitsi_jibri_xmpp_password: ""
```
## (Optional) Configure Jitsi authentication and guests mode
By default the Jitsi Meet instance does not require any kind of login and is open to use for anyone without registration.
If you're fine with such an open Jitsi instance, please skip to [Apply changes](#apply-changes).
If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow the following steps to enable Jitsi's authentication and optionally guests mode.
Currently, there are three supported authentication modes: 'internal' (default), 'matrix' and 'ldap'.
**Note:** Authentication is not tested via the playbook's self-checks.
We therefore recommend that you manually verify if authentication is required by jitsi.
For this, try to manually create a conference on jitsi.DOMAIN in your browser.
### Authenticate using Jitsi accounts (Auth-Type 'internal')
The default authentication mechanism is 'internal' auth, which requires jitsi-accounts to be setup and is the recommended setup, as it also works in federated rooms.
With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join.
If a registered host is not yet present, guests are put on hold in individual waiting rooms.
If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow this step to enable Jitsi's authentication and guests mode. With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join. If a registered host is not yet present, guests are put on hold in individual waiting rooms.
Add these lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
```yaml
jitsi_enable_auth: true
jitsi_enable_guests: true
jitsi_prosody_auth_internal_accounts:
matrix_jitsi_enable_auth: true
matrix_jitsi_enable_guests: true
matrix_jitsi_prosody_auth_internal_accounts:
- username: "jitsi-moderator"
password: "secret-password"
- username: "another-user"
password: "another-password"
```
**Caution:** Accounts added here and subsequently removed will not be automatically removed from the Prosody server until user account cleaning is integrated into the playbook.
**Caution:** Accounts added here and subsquently removed will not be automatically removed from the Prosody server until user account cleaning is integrated into the playbook.
**If you get an error** like this: "Error: Account creation/modification not supported.", it's likely that you had previously installed Jitsi without auth/guest support. In such a case, you should look into [Rebuilding your Jitsi installation](#rebuilding-your-jitsi-installation).
### Authenticate using Matrix OpenID (Auth-Type 'matrix')
**Attention: Probably breaks Jitsi in federated rooms and does not allow sharing conference links with guests.**
### (Optional) LDAP authentication
Using this authentication type require a [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service).
By default, this playbook creates and configures a user-verification-service to run locally, see [configuring-user-verification-service](configuring-playbook-user-verification-service.md).
To enable set this configuration at host level:
The default authentication mode of Jitsi is `internal`, however LDAP is also supported. An example LDAP configuration could be:
```yaml
jitsi_enable_auth: true
jitsi_auth_type: matrix
matrix_user_verification_service_enabled: true
```
For more information see also [https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification](https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification).
### Authenticate using LDAP (Auth-Type 'ldap')
An example LDAP configuration could be:
```yaml
jitsi_enable_auth: true
jitsi_auth_type: ldap
jitsi_ldap_url: "ldap://ldap.DOMAIN"
jitsi_ldap_base: "OU=People,DC=DOMAIN"
#jitsi_ldap_binddn: ""
#jitsi_ldap_bindpw: ""
jitsi_ldap_filter: "uid=%u"
jitsi_ldap_auth_method: "bind"
jitsi_ldap_version: "3"
jitsi_ldap_use_tls: true
jitsi_ldap_tls_ciphers: ""
jitsi_ldap_tls_check_peer: true
jitsi_ldap_tls_cacert_file: "/etc/ssl/certs/ca-certificates.crt"
jitsi_ldap_tls_cacert_dir: "/etc/ssl/certs"
jitsi_ldap_start_tls: false
matrix_jitsi_enable_auth: true
matrix_jitsi_auth_type: ldap
matrix_jitsi_ldap_url: "ldap://ldap.DOMAIN"
matrix_jitsi_ldap_base: "OU=People,DC=DOMAIN
#matrix_jitsi_ldap_binddn: ""
#matrix_jitsi_ldap_bindpw: ""
matrix_jitsi_ldap_filter: "uid=%u"
matrix_jitsi_ldap_auth_method: "bind"
matrix_jitsi_ldap_version: "3"
matrix_jitsi_ldap_use_tls: true
matrix_jitsi_ldap_tls_ciphers: ""
matrix_jitsi_ldap_tls_check_peer: true
matrix_jitsi_ldap_tls_cacert_file: "/etc/ssl/certs/ca-certificates.crt"
matrix_jitsi_ldap_tls_cacert_dir: "/etc/ssl/certs"
matrix_jitsi_ldap_start_tls: false
```
For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet#authentication-using-ldap) and the [saslauthd `LDAP_SASLAUTHD`](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD) documentation.
@ -111,15 +87,15 @@ For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/d
By default the Jitsi Meet instance does not work with a client in LAN (Local Area Network), even if others are connected from WAN. There are no video and audio. In the case of WAN to WAN everything is ok.
The reason is the Jitsi VideoBridge git to LAN client the IP address of the docker image instead of the host. The [documentation](https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker/#running-behind-nat-or-on-a-lan-environment) of Jitsi in docker suggest to add `JVB_ADVERTISE_IPS` in enviornment variable to make it work.
The reason is the Jitsi VideoBridge git to LAN client the IP address of the docker image instead of the host. The [documentation](https://github.com/jitsi/docker-jitsi-meet#running-behind-nat-or-on-a-lan-environment) of Jitsi in docker suggest to add `DOCKER_HOST_ADDRESS` in enviornment variable to make it work.
Here is how to do it in the playbook.
Add these two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
```yaml
jitsi_jvb_container_extra_arguments:
- '--env "JVB_ADVERTISE_IPS=<Local IP address of the host>"'
matrix_jitsi_jvb_container_extra_arguments:
- '--env "DOCKER_HOST_ADDRESS=<Local IP adress of the host>"'
```
## (Optional) Fine tune Jitsi
@ -127,7 +103,7 @@ jitsi_jvb_container_extra_arguments:
Sample **additional** `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration to save up resources (explained below):
```yaml
jitsi_web_custom_config_extension: |
matrix_jitsi_web_custom_config_extension: |
config.enableLayerSuspension = true;
config.disableAudioLevels = true;
@ -135,12 +111,13 @@ jitsi_web_custom_config_extension: |
// Limit the number of video feeds forwarded to each client
config.channelLastN = 4;
jitsi_web_config_resolution_width_ideal_and_max: 480
jitsi_web_config_resolution_height_ideal_and_max: 240
matrix_jitsi_web_config_resolution_width_ideal_and_max: 480
matrix_jitsi_web_config_resolution_height_ideal_and_max: 240
```
You may want to **suspend unused video layers** until they are requested again, to save up resources on both server and clients.
Read more on this feature [here](https://jitsi.org/blog/new-off-stage-layer-suppression-feature/)
For this add this line to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
You may wish to **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved.
@ -150,126 +127,6 @@ Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/master/
You may want to **limit the maximum video resolution**, to save up resources on both server and clients.
## (Optional) Specify a Max number of participants on a Jitsi conference
The playbook allows a user to set a max number of participants allowed to join a Jitsi conference. By default there is no limit.
In order to set the max number of participants use the following **additional** configuration:
```yaml
jitsi_prosody_max_participants: 4 # example value
```
## (Optional) Additional JVBs
By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-videobridge)) is deployed on the same host as the Matrix server. To allow more video-conferences to happen at the same time, you may need to provision additional JVB services on other hosts.
There is an ansible playbook that can be run with the following tag:
`ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
For this role to work you will need an additional section in the ansible hosts file with the details of the JVB hosts, for example:
```
[jitsi_jvb_servers]
<your jvb hosts> ansible_host=<ip address of the jvb host>
```
Each JVB will require a server id to be set so that it can be uniquely identified and this allows Jitsi to keep track of which conferences are on which JVB.
The server id is set with the variable `jitsi_jvb_server_id` which ends up as the JVB_WS_SERVER_ID environment variables in the JVB docker container.
This variable can be set via the host file, a parameter to the ansible command or in the `vars.yaml` for the host which will have the additional JVB. For example:
``` yaml
jitsi_jvb_server_id: 'jvb-2'
```
``` INI
[jitsi_jvb_servers]
jvb-2.example.com ansible_host=192.168.0.2 jitsi_jvb_server_id=jvb-2
jvb-3.example.com ansible_host=192.168.0.3 jitsi_jvb_server_id=jvb-2
```
Note that the server id `jvb-1` is reserved for the JVB instance running on the Matrix host and therefore should not be used as the id of an additional jvb host.
The additional JVB will also need to expose the colibri web socket port and this can be done with the following variable:
```yaml
jitsi_jvb_container_colibri_ws_host_bind_port: 9090
```
The JVB will also need to know where the prosody xmpp server is located, similar to the server id this can be set in the vars for the JVB by using the variable
`jitsi_xmpp_server`. The Jitsi prosody container is deployed on the matrix server by default so the value can be set to the matrix domain. For example:
```yaml
jitsi_xmpp_server: "{{ matrix_domain }}"
```
However, it can also be set the ip address of the matrix server. This can be useful if you wish to use a private ip. For example:
```yaml
jitsi_xmpp_server: "192.168.0.1"
```
For the JVB to be able to contact the XMPP server, the latter must expose the XMPP port (5222). By default, the Matrix server does not expose the
port; only the XMPP container exposes it internally inside the host, which means that the first JVB (which runs on the Matrix server) can reach it but
the additional JVB cannot. The port is exposed by setting `jitsi_prosody_container_jvb_host_bind_port` like this:
```yaml
jitsi_prosody_container_jvb_host_bind_port: 5222
```
(The default is empty; if it's set then docker forwards the port.)
Applied together this will allow you to provision extra JVB instances which will register themselves with the prosody service and be available for jicofo
to route conferences too.
To make Traefik reverse-proxy to these additional JVBs (living on other hosts), **you would need to add the following Traefik configuration extension**:
```yaml
# Traefik proxying for additional JVBs. These can't be configured using Docker
# labels, like the first JVB is, because they run on different hosts, so we add
# the necessary configuration to the file provider.
traefik_provider_configuration_extension_yaml: |
http:
routers:
{% for host in groups['jitsi_jvb_servers'] %}
additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-router:
entryPoints:
- "{{ traefik_entrypoint_primary }}"
rule: "Host(`{{ jitsi_hostname }}`) && PathPrefix(`/colibri-ws/{{ hostvars[host]['jitsi_jvb_server_id'] }}/`)"
service: additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-service
{% if traefik_entrypoint_primary != 'web' %}
tls:
certResolver: "{{ traefik_certResolver_primary }}"
{% endif %}
{% endfor %}
services:
{% for host in groups['jitsi_jvb_servers'] %}
additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-service:
loadBalancer:
servers:
- url: "http://{{ host }}:9090/"
{% endfor %}
```
## (Optional) Enable Gravatar
In the default Jisti Meet configuration, gravatar.com is enabled as an avatar service. This results in third party request leaking data to gravatar.
Since element already sends the url of configured Matrix avatars to Jitsi, we disabled gravatar.
To enable Gravatar set:
```yaml
jitsi_disable_gravatar: false
```
**Beware:** This leaks information to a third party, namely the Gravatar-Service (unless configured otherwise: gravatar.com).
Besides metadata, this includes the matrix user_id and possibly the room identifier (via `referrer` header).
## Apply changes
@ -286,14 +143,14 @@ You can use the self-hosted Jitsi server in multiple ways:
- **directly (without any Matrix integration)**. Just go to `https://jitsi.DOMAIN`
**Note**: Element apps on mobile devices currently [don't support joining meetings on a self-hosted Jitsi server](https://github.com/element-hq/riot-web/blob/601816862f7d84ac47547891bd53effa73d32957/docs/jitsi.md#mobile-app-support).
**Note**: Element apps on mobile devices currently [don't support joining meetings on a self-hosted Jitsi server](https://github.com/vector-im/riot-web/blob/601816862f7d84ac47547891bd53effa73d32957/docs/jitsi.md#mobile-app-support).
## Troubleshooting
### Rebuilding your Jitsi installation
**If you ever run into any trouble** or **if you change configuration (`jitsi_*` variables) too much**, we urge you to rebuild your Jitsi setup.
**If you ever run into any trouble** or **if you change configuration (`matrix_jitsi_*` variables) too much**, we urge you to rebuild your Jitsi setup.
We normally don't require such manual intervention for other services, but Jitsi services generate a lot of configuration files on their own.
@ -301,6 +158,7 @@ These files are not all managed by Ansible (at least not yet), so you may someti
To rebuild your Jitsi configuration:
- ask Ansible to stop all Jitsi services: `just run-tags stop-group --extra-vars=group=jitsi`
- SSH into the server and do this and remove all Jitsi configuration & data (`rm -rf /matrix/jitsi`)
- ask Ansible to set up Jitsi anew and restart services (`just install-service jitsi`)
- SSH into the server and do this:
- stop all Jitsi services (`systemctl stop matrix-jitsi-*`).
- remove all Jitsi configuration & data (`rm -rf /matrix/jitsi`)
- ask Ansible to set up Jitsi anew and restart services (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-jitsi,start`)

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

@ -8,9 +8,7 @@ If you decide that you'd like to let this playbook install it for you, you need
```yaml
matrix_synapse_ext_password_provider_ldap_enabled: true
matrix_synapse_ext_password_provider_ldap_uri:
- "ldap://ldap-01.mydomain.tld:389"
- "ldap://ldap-02.mydomain.tld:389"
matrix_synapse_ext_password_provider_ldap_uri: "ldap://ldap.mydomain.tld:389"
matrix_synapse_ext_password_provider_ldap_start_tls: true
matrix_synapse_ext_password_provider_ldap_base: "ou=users,dc=example,dc=com"
matrix_synapse_ext_password_provider_ldap_attributes_uid: "uid"
@ -30,12 +28,5 @@ If you wish for users to **authenticate only against configured password provide
matrix_synapse_password_config_localdb_enabled: false
```
## Using ma1sd Identity Server for authentication
If you wish to use the ma1sd Identity Server for LDAP authentication instead of [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) consult [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication).
## Handling user registration
If you wish for users to also be able to make new registrations against LDAP, you may **also** wish to [set up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md).

8
docs/configuring-playbook-ma1sd.md
View File

@ -33,7 +33,7 @@ matrix_ma1sd_matrixorg_forwarding_enabled: true
## Customizing email templates
If you'd like to change the default email templates used by ma1sd, take a look at the `matrix_ma1sd_threepid_medium_email_custom_` variables
(in the `roles/custom/matrix-ma1sd/defaults/main.yml` file.
(in the `roles/matrix-ma1sd/defaults/main.yml` file.
## ma1sd-controlled Registration
@ -44,9 +44,9 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu
- `matrix_synapse_enable_registration_captcha` - to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring_captcha.md) documentation.
- `matrix_synapse_registrations_require_3pid` - a list of 3pid types (among `'email'`, `'msisdn'`) required by the Synapse server for registering
- `matrix_synapse_registrations_require_3pid` - to control the types of 3pid (`'email'`, `'msisdn'`) required by the Synapse server for registering
- variables prefixed with `matrix_ma1sd_container_labels_` (e.g. `matrix_ma1sd_container_labels_matrix_client_3pid_registration_enabled`) - to configure the Traefik reverse-proxy to capture and send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality
- variables prefixed with `matrix_nginx_proxy_proxy_matrix_3pid_registration_` (e.g. `matrix_nginx_proxy_proxy_matrix_3pid_registration_enabled`) - to configure the integrated nginx webserver to send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality
- `matrix_ma1sd_configuration_extension_yaml` - to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`.
@ -86,7 +86,7 @@ You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more d
To use a more custom configuration, you can define a `matrix_ma1sd_configuration_extension_yaml` string variable
and put your configuration in it.
To learn more about how to do this, refer to the information about `matrix_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
To learn more about how to do this, refer to the information about `matrix_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
## Example: SMS verification

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

@ -91,7 +91,7 @@ matrix_corporal_policy_provider_config: |
}
# Modify the policy below as you see fit
aux_file_definitions:
matrix_aux_file_definitions:
- dest: "{{ matrix_corporal_config_dir_path }}/policy.json"
content: |
{

36
docs/configuring-playbook-matrix-ldap-registration-proxy.md
View File

@ -1,36 +0,0 @@
# Setting up matrix-ldap-registration-proxy (optional)
The playbook can install and configure [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) for you.
This proxy handles Matrix registration requests and forwards them to LDAP.
**Please note:** This does support the full Matrix specification for registrations. It only provide a very coarse
implementation of a basic password registration.
## Quickstart
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_ldap_registration_proxy_enabled: true
# LDAP credentials
matrix_ldap_registration_proxy_ldap_uri: <URI>
matrix_ldap_registration_proxy_ldap_base_dn: <DN>
matrix_ldap_registration_proxy_ldap_user: <USER>
matrix_ldap_registration_proxy_ldap_password: <password>
```
If you already use the [synapse external password provider via LDAP](configuring-playbook-ldap-auth.md) (that is, you have `matrix_synapse_ext_password_provider_ldap_enabled: true` and other options in your configuration)
you can use the following values as configuration:
```yaml
# Use the LDAP values specified for the synapse role to setup LDAP proxy
matrix_ldap_registration_proxy_ldap_uri: "{{ matrix_synapse_ext_password_provider_ldap_uri }}"
matrix_ldap_registration_proxy_ldap_base_dn: "{{ matrix_synapse_ext_password_provider_ldap_base }}"
matrix_ldap_registration_proxy_ldap_user: "{{ matrix_synapse_ext_password_provider_ldap_bind_dn }}"
matrix_ldap_registration_proxy_ldap_password: "{{ matrix_synapse_ext_password_provider_ldap_bind_password }}"
matrix_ldap_registration_proxy_systemd_wanted_services_list_custom:
- matrix-synapse.service
```

162
docs/configuring-playbook-matrix-media-repo.md
View File

@ -1,162 +0,0 @@
# Setting up matrix-media-repo (optional)
[matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/) (often abbreviated "MMR") is a highly customizable multi-domain media repository for Matrix. Intended for medium to large environments consisting of several homeservers, this media repo de-duplicates media (including remote media) while being fully compliant with the specification.
Smaller/individual homeservers can still make use of this project's features, though it may be difficult to set up or have higher than expected resource consumption. Please do your research before deploying this as this project may not be useful for your environment.
For a simpler alternative (which allows you to offload your media repository storage to S3, etc.), you can [configure S3 storage](configuring-playbook-s3.md) instead of setting up matrix-media-repo.
| **Table of Contents** |
| :------------------------------------------------------------------------------------------ |
| [Quickstart](#quickstart) |
| [Additional configuration options](#configuring-the-media-repo) |
| [Importing data from an existing media store](#importing-data-from-an-existing-media-store) |
## Quickstart
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file and [re-run the installation process](./installing.md) for the playbook:
```yaml
matrix_media_repo_enabled: true
# (optional) Turned off by default
# matrix_media_repo_metrics_enabled: true
```
The repo is pre-configured for integrating with the Postgres database, Traefik proxy and [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) (if metrics enabled) from this playbook for all the available homeserver roles. When the media repo is enabled, other media store roles should be disabled (if using Synapse with other media store roles).
By default, the media-repo will use the local filesystem for data storage. You can alternatively use a `s3` cloud backend as well. Access token caching is also enabled by default since the logout endpoints are proxied through the media repo.
## Configuring the media-repo
Additional common configuration options:
```yaml
# The postgres database pooling options
# The maximum number of connects to hold open. More of these allow for more concurrent
# processes to happen.
matrix_media_repo_database_max_connections: 25
# The maximum number of connects to leave idle. More of these reduces the time it takes
# to serve requests in low-traffic scenarios.
matrix_media_repo_database_max_idle_connections: 5
# These users have full access to the administrative functions of the media repository.
# See docs/admin.md for information on what these people can do. They must belong to one of the
# configured homeservers above.
# matrix_media_repo_admins: [
# "@your_username:example.org"
# ]
matrix_media_repo_admins: []
# Datastores can be split into many areas when handling uploads. Media is still de-duplicated
# across all datastores (local content which duplicates remote content will re-use the remote
# content's location). This option is useful if your datastore is becoming very large, or if
# you want faster storage for a particular kind of media.
#
# To disable this datastore, making it readonly, specify `forKinds: []`.
#
# The kinds available are:
# thumbnails - Used to store thumbnails of media (local and remote).
# remote_media - Original copies of remote media (servers not configured by this repo).
# local_media - Original uploads for local media.
# archives - Archives of content (GDPR and similar requests).
matrix_media_repo_datastore_file_for_kinds: ["thumbnails", "remote_media", "local_media", "archives"]
matrix_media_repo_datastore_s3_for_kinds: []
# The s3 uploader needs a temporary location to buffer files to reduce memory usage on
# small file uploads. If the file size is unknown, the file is written to this location
# before being uploaded to s3 (then the file is deleted). If you aren't concerned about
# memory usage, set this to an empty string.
matrix_media_repo_datastore_s3_opts_temp_path: ""
matrix_media_repo_datastore_s3_opts_endpoint: "sfo2.digitaloceanspaces.com"
matrix_media_repo_datastore_s3_opts_access_key_id: ""
matrix_media_repo_datastore_s3_opts_access_secret: ""
matrix_media_repo_datastore_s3_opts_ssl: true
matrix_media_repo_datastore_s3_opts_bucket_name: "your-media-bucket"
# An optional region for where this S3 endpoint is located. Typically not needed, though
# some providers will need this (like Scaleway). Uncomment to use.
# matrix_media_repo_datastore_s3_opts_region: "sfo2"
# An optional storage class for tuning how the media is stored at s3.
# See https://aws.amazon.com/s3/storage-classes/ for details; uncomment to use.
# matrix_media_repo_datastore_s3_opts_storage_class: "STANDARD"
```
Full list of configuration options with documentation can be found in [`roles/custom/matrix-media-repo/defaults/main.yml`](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/custom/matrix-media-repo/defaults/main.yml)
## Signing Keys
Authenticated media endpoints ([MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916)) requires MMR to have a configured signing key to authorize outbound federation requests. Additionally, the signing key must be merged with your homeserver's signing key file.
The playbook default is to generate a MMR signing key when invoking the setup role and merge it with your homeserver if you are using Synapse or Dendrite. This can be disabled if desired by setting the option in your inventory:
```yaml
matrix_media_repo_generate_signing_key: false
```
If you wish to manually generate the signing key and merge it with your homeserver's signing key file, see https://docs.t2bot.io/matrix-media-repo/v1.3.5/installation/signing-key/ for more details.
**Note that if you uninstall MMR from the playbook, it will not remove the old MMR signing key from your homeserver's signing key file. You will have to remove it manually.**
### Key backup and revoking
Since your homeserver signing key file is modified by the playbook, a backup will be created in `HOMESERVER_DIR/config/DOMAIN.signing.key.backup`. If you need to remove/revoke old keys, you can restore from this backup or remove the MMR key id from your `DOMAIN.signing.key` file.
Additionally, its recommended after revoking a signing key to update your homeserver config file (`old_signing_keys` field for Synapse and `old_private_keys` for Dendrite). See your homeserver config file for further documentation on how to populate the field.
## Importing data from an existing media store
If you want to add this repo to an existing homeserver managed by the playbook, you will need to import existing media into MMR's database or you will lose access to older media while it is active. MMR versions up to `v1.3.3` only support importing from Synapse, but newer versions (at time of writing: only `latest`) also support importing from Dendrite.
**Before importing**: ensure you have an initial matrix-media-repo deployment by following the [quickstart](#quickstart) guide above
Depending on the homeserver implementation yu're using (Synapse, Dendrite), you'll need to use a different import tool (part of matrix-media-repo) and point it to the homeserver's database.
### Importing data from the Synapse media store
To import the Synapse media store, you're supposed to invoke the `import_synapse` tool which is part of the matrix-media-repo container image. Your Synapse database is called `synapse` by default, unless you've changed it by modifying `matrix_synapse_database_database`.
This guide here is adapted from the [upstream documentation about the import_synapse script](https://github.com/turt2live/matrix-media-repo#importing-media-from-synapse).
Run the following command on the server (after replacing `postgres_connection_password` in it with the value found in your `vars.yml` file):
```sh
docker exec -it matrix-media-repo \
/usr/local/bin/import_synapse \
-dbName synapse \
-dbHost matrix-postgres \
-dbPort 5432 \
-dbUsername matrix \
-dbPassword postgres_connection_password
```
Enter `1` for the Machine ID when prompted (you are not doing any horizontal scaling) unless you know what you're doing.
This should output a `msg="Import completed"` when finished successfully!
### Importing data from the Dendrite media store
If you're using the [Dendrite](configuring-playbook-dendrite.md) homeserver instead of the default for this playbook (Synapse), follow this importing guide here.
To import the Dendrite media store, you're supposed to invoke the `import_dendrite` tool which is part of the matrix-media-repo container image. Your Dendrite database is called `dendrite_mediaapi` by default, unless you've changed it by modifying `matrix_dendrite_media_api_database`.
Run the following command on the server (after replacing `postgres_connection_password` in it with the value found in your `vars.yml` file):
```sh
docker exec -it matrix-media-repo \
/usr/local/bin/import_dendrite \
-dbName dendrite_mediaapi \
-dbHost matrix-postgres \
-dbPort 5432 \
-dbUsername matrix \
-dbPassword postgres_connection_password
```
Enter `1` for the Machine ID when prompted (you are not doing any horizontal scaling) unless you know what you're doing.
This should output a `msg="Import completed"` when finished successfully!

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

@ -2,10 +2,6 @@
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.
**WARNING**: this is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md)
> 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.

133
docs/configuring-playbook-mautrix-bridges.md
View File

@ -1,133 +0,0 @@
# 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
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
**for all bridges with encryption support**:
```yaml
matrix_bridges_encryption_enabled: true
matrix_bridges_encryption_default: true
```
**Alternatively**, for a specific bridge:
```yaml
matrix_mautrix_SERVICENAME_bridge_encryption_enabled: true
matrix_mautrix_SERVICENAME_bridge_encryption_default: true
```
## relay mode
Relay mode is off by default. If you would like to enable relay mode, add the following to your `vars.yml` file:
**for all bridges with relay mode support**:
```yaml
matrix_bridges_relay_enabled: true
```
**Alternatively**, for a specific bridge:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
relay:
enabled: true
```
You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
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/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` and `roles/custom/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) enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
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_appservice_double_puppet_enabled: true
```
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.

83
docs/configuring-playbook-nginx.md
View File

@ -1,3 +1,84 @@
# Configure Nginx (optional, advanced)
Since 2024-01, this playbook no longer uses nginx as its reverse-proxy.
By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
If that's alright, you can skip this.
## Using Nginx status
This will serve a statuspage to the hosting machine only. Useful for monitoring software like [longview](https://www.linode.com/docs/platform/longview/longview-app-for-nginx/)
```yaml
matrix_nginx_proxy_proxy_matrix_nginx_status_enabled: true
```
This will serve the status page under the following addresses:
- `http://matrix.DOMAIN/nginx_status` (using HTTP)
- `https://matrix.DOMAIN/nginx_status` (using HTTPS)
By default, if ```matrix_nginx_proxy_nginx_status_enabled``` is enabled, access to the status page would be allowed from the local IP address of the server. If you wish to allow access from other IP addresses, you can provide them as a list:
```yaml
matrix_nginx_proxy_proxy_matrix_nginx_status_allowed_addresses:
- 8.8.8.8
- 1.1.1.1
```
## Adjusting SSL in your server
You can adjust how the SSL is served by the nginx server using the `matrix_nginx_proxy_ssl_preset` variable. We support a few presets, based on the Mozilla Server Side TLS
Recommended configurations. These presets influence the TLS Protocol, the SSL Cipher Suites and the `ssl_prefer_server_ciphers` variable of nginx.
Possible values are:
- `"modern"` - For Modern clients that support TLS 1.3, with no need for backwards compatibility
- `"intermediate"` (**default**) - Recommended configuration for a general-purpose server
- `"old"` - Services accessed by very old clients or libraries, such as Internet Explorer 8 (Windows XP), Java 6, or OpenSSL 0.9.8
**Be really carefull when setting it to `"modern"`**. This could break comunication with other Matrix servers, limiting your federation posibilities.
Besides changing the preset (`matrix_nginx_proxy_ssl_preset`), you can also directly override these 3 variables:
- `matrix_nginx_proxy_ssl_protocols`: for specifying the supported TLS protocols.
- `matrix_nginx_proxy_ssl_prefer_server_ciphers`: for specifying if the server or the client choice when negotiating the cipher. It can set to `on` or `off`.
- `matrix_nginx_proxy_ssl_ciphers`: for specifying the SSL Cipher suites used by nginx.
For more information about these variables, check the `roles/matrix-nginx-proxy/defaults/main.yml` file.
## Synapse + OpenID Connect for Single-Sign-On
If you want to use OpenID Connect as an SSO provider (as per the [Synapse OpenID docs](https://github.com/matrix-org/synapse/blob/develop/docs/openid.md)), you need to use the following configuration (in your `vars.yml` file) to instruct nginx to forward `/_synapse/oidc` to Synapse:
```yaml
matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_oidc_api_enabled: true
```
## Disable Nginx access logs
This will disable the access logging for nginx.
```yaml
matrix_nginx_proxy_access_log_enabled: false
```
## Additional configuration
This playbook also allows for additional configuration to be applied to the nginx server.
If you want this playbook to obtain and renew certificates for other domains, then you can set the `matrix_ssl_additional_domains_to_obtain_certificates_for` variable (as mentioned in the [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) documentation as well). Make sure that you have set the DNS configuration for the domains you want to include to point at your server.
```yaml
matrix_ssl_additional_domains_to_obtain_certificates_for:
- domain.one.example
- domain.two.example
```
You can include additional nginx configuration by setting the `matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks` variable.
```yaml
matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks:
- |
# These lines will be included in the nginx configuration.
# This is at the top level of the file, so you will need to define all of the `server { ... }` blocks.
- |
# For advanced use, have a look at the template files in `roles/matrix-nginx-proxy/templates/nginx/conf.d`
```

106
docs/configuring-playbook-ntfy.md
View File

@ -1,106 +0,0 @@
# 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
ntfy_enabled: true
# This is the default hostname.
# Uncomment the line below and change it, if you'd like.
# matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
# Uncomment to enable the ntfy web app (disabled by default)
# ntfy_web_root: app # defaults to "disable"
# Uncomment and change to inject additional configuration options.
# ntfy_configuration_extension_yaml: |
# log_level: DEBUG
```
For a more complete list of variables that you could override, see the [`defaults/main.yml` file](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/-/blob/main/defaults/main.yml) of the ntfy Ansible role.
For a complete list of ntfy config options that you could put in `ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
## 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+:
1. choose `Settings` -> `Notifications` -> `Notification method` -> `ntfy`
2. verify `Settings` -> `Troubleshoot` -> `Troubleshoot notification settings`
If the matrix app asks, "Choose a distributor: FCM Fallback or ntfy", then choose "ntfy".
If the matrix app doesn't seem to pick it up, try restarting it and try the Troubleshooting section below.
### Web App
ntfy also has a web app to subscribe to and push to topics from the browser. This may be helpful to further troubleshoot UnifiedPush problems or to use ntfy for other purposes. The web app only runs in the browser locally (after downloading the JavaScript).
The web app is disabled in this playbook by default as the expectation is that most users won't use it. You can either use the [official hosted one](https://ntfy.sh/app) (it supports using other public reachable ntfy instances) or host it yourself by setting `ntfy_web_root: "app"` and re-running Ansible.
## 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.

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

@ -1,64 +1,194 @@
# Using your own webserver, instead of this playbook's Traefik reverse-proxy (optional, advanced)
By default, this playbook installs its own [Traefik](https://traefik.io/) reverse-proxy server (in a Docker container) which listens on ports 80 and 443.
# Using your own webserver, instead of this playbook's nginx proxy (optional, advanced)
By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
If that's alright, you can skip this.
## Traefik
If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that,
and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can.
[Traefik](https://traefik.io/) is the default reverse-proxy for the playbook since [2023-02-26](../CHANGELOG.md/#2023-02-26) and serves **2 purposes**:
There are **2 ways you can go about it**, if you'd like to use your own webserver:
- serving public traffic and providing SSL-termination with certificates obtained from [Let's Encrypt](https://letsencrypt.org/). See [Adjusting SSL certificate retrieval](./configuring-playbook-ssl-certificates.md).
- [Method 1: Disabling the integrated nginx reverse-proxy webserver](#method-1-disabling-the-integrated-nginx-reverse-proxy-webserver)
- assists internal communication between addon services (briges, bots, etc.) and the homeserver via an internal entrypoint (`matrix-internal-matrix-client-api`).
- [Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy](#method-2-fronting-the-integrated-nginx-reverse-proxy-webserver-with-another-reverse-proxy)
There are 2 ways to use Traefik with this playbook, as described below.
### Traefik managed by the playbook
## Method 1: Disabling the integrated nginx reverse-proxy webserver
To have the playbook install and use Traefik, use configuration like this (as seen in `examples/vars.yml`):
This method is about completely disabling the integrated nginx reverse-proxy webserver and replicating its behavior using another webserver.
For an alternative, make sure to check Method #2 as well.
### Preparation
No matter which external webserver you decide to go with, you'll need to:
1) Make sure your web server user (something like `http`, `apache`, `www-data`, `nginx`) is part of the `matrix` group. You should run something like this: `usermod -a -G matrix nginx`. This allows your webserver user to access files owned by the `matrix` group. When using an external nginx webserver, this allows it to read configuration files from `/matrix/nginx-proxy/conf.d`. When using another server, it would make other files, such as `/matrix/static-files/.well-known`, accessible to it.
2) Edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to disable the integrated nginx server:
```yaml
matrix_playbook_reverse_proxy_type: playbook-managed-traefik
traefik_config_certificatesResolvers_acme_email: YOUR_EMAIL_ADDRESS
matrix_nginx_proxy_enabled: false
```
Traefik will manage SSL certificates for all services seamlessly.
### Traefik managed by you
3) **If you'll manage SSL certificates by yourself**, edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to disable SSL certificate retrieval:
```yaml
matrix_playbook_reverse_proxy_type: other-traefik-container
# Uncomment and adjust if your Traefik container is on another network
# matrix_playbook_reverse_proxy_container_network: traefik
# Adjust to point to your Traefik container
matrix_playbook_reverse_proxy_hostname: name-of-your-traefik-container
traefik_certs_dumper_ssl_dir_path: "/path/to/your/traefiks/acme.json/directory"
# Uncomment and tweak the variable below if the name of your federation entrypoint is different
# than the default value (matrix-federation).
# matrix_federation_traefik_entrypoint_name: matrix-federation
matrix_ssl_retrieval_method: none
```
In this mode all roles will still have Traefik labels attached. You will, however, need to configure your Traefik instance and its entrypoints.
**Note**: During [installation](installing.md), unless you've disabled SSL certificate management (`matrix_ssl_retrieval_method: none`), the playbook would need 80 to be available, in order to retrieve SSL certificates. **Please manually stop your other webserver while installing**. You can start it back up afterwards.
By default, the playbook configured a `default` certificate resolver and multiple entrypoints.
You need to configure 4 entrypoints for your Traefik server:
### Using your own external nginx webserver
- `web` (TCP port `80`) - used for redirecting to HTTPS (`web-secure`)
- `web-secure` (TCP port `443`) - used for exposing the Matrix Client-Server API and all other services
- `matrix-federation` (TCP port `8448`) - used for exposing the Matrix Federation API
- `matrix-internal-matrix-client-api` (TCP port `8008`) - used internally for addon services (bridges, bots) to communicate with the homserver
Once you've followed the [Preparation](#preparation) guide above, it's time to set up your external nginx server.
Below is some configuration for running Traefik yourself, although we recommend using [Traefik managed by the playbook](#traefik-managed-by-the-playbook).
Even with `matrix_nginx_proxy_enabled: false`, the playbook still generates some helpful files for you in `/matrix/nginx-proxy/conf.d`.
Those configuration files are adapted for use with an external web server (one not running in the container network).
Note that this configuration on its own does **not** redirect traffic on port 80 (plain HTTP) to port 443 for HTTPS. If you are not already doing this in Traefik, it can be added to Traefik in a [file provider](https://docs.traefik.io/v2.0/providers/file/) as follows:
You can most likely directly use the config files installed by this playbook at: `/matrix/nginx-proxy/conf.d`. Just include them in your own `nginx.conf` like this: `include /matrix/nginx-proxy/conf.d/*.conf;`
Note that if your nginx version is old, it might not like our default choice of SSL protocols (particularly the fact that the brand new `TLSv1.3` protocol is enabled). You can override the protocol list by redefining the `matrix_nginx_proxy_ssl_protocols` variable. Example:
```yaml
# Custom protocol list (removing `TLSv1.3`) to suit your nginx version.
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.
### Using your own external Apache webserver
Once you've followed the [Preparation](#preparation) guide above, you can take a look at the [examples/apache](../examples/apache) directory for a sample configuration.
### Using your own external caddy webserver
After following the [Preparation](#preparation) guide above, you can take a look at the [examples/caddy](../examples/caddy) directory and [examples/caddy2](../examples/caddy2) directory for a sample configuration for Caddy v1 and v2, respectively.
### Using your own HAproxy reverse proxy
After following the [Preparation](#preparation) guide above, you can take a look at the [examples/haproxy](../examples/haproxy) directory for a sample configuration. In this case HAproxy is used as a reverse proxy and a simple Nginx container is used to serve statically `.well-known` files.
### Using another external webserver
Feel free to look at the [examples/apache](../examples/apache) directory, or the [template files in the matrix-nginx-proxy role](../roles/matrix-nginx-proxy/templates/nginx/conf.d/).
## Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy
This method is about leaving the integrated nginx reverse-proxy webserver be, but making it not get in the way (using up important ports, trying to retrieve SSL certificates, etc.).
If you wish to use another webserver, the integrated nginx reverse-proxy webserver usually gets in the way because it attempts to fetch SSL certificates and binds to ports 80, 443 and 8448 (if Matrix Federation is enabled).
You can disable such behavior and make the integrated nginx reverse-proxy webserver only serve traffic locally (or over a local network).
You would need some configuration like this:
```yaml
# Do not retrieve SSL certificates. This shall be managed by another webserver or other means.
matrix_ssl_retrieval_method: none
# Do not try to serve HTTPS, since we have no SSL certificates.
# Disabling this also means services will be served on the HTTP port
# (`matrix_nginx_proxy_container_http_host_bind_port`).
matrix_nginx_proxy_https_enabled: false
# Do not listen for HTTP on port 80 globally (default), listen on the loopback interface.
# If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
matrix_nginx_proxy_container_http_host_bind_port: '127.0.0.1:81'
# Likewise, expose the Matrix Federation port on the loopback interface.
# Since `matrix_nginx_proxy_https_enabled` is set to `false`, this federation port will serve HTTP traffic.
# If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
#
# You'd most likely need to expose it publicly on port 8448 (8449 was chosen for the local port to prevent overlap).
matrix_nginx_proxy_container_federation_host_bind_port: '127.0.0.1:8449'
# Coturn relies on SSL certificates that have already been obtained.
# Since we don't obtain any certificates (`matrix_ssl_retrieval_method: none` above), it won't work by default.
# An alternative is to tweak some of: `matrix_coturn_tls_enabled`, `matrix_coturn_tls_cert_path` and `matrix_coturn_tls_key_path`.
matrix_coturn_enabled: false
# Trust the reverse proxy to send the correct `X-Forwarded-Proto` header as it is handling the SSL connection.
matrix_nginx_proxy_trust_forwarded_proto: true
# Trust and use the other reverse proxy's `X-Forwarded-For` header.
matrix_nginx_proxy_x_forwarded_for: '$proxy_add_x_forwarded_for'
```
With this, nginx would still be in use, but it would not bother with anything SSL related or with taking up public ports.
All services would be served locally on `127.0.0.1:81` and `127.0.0.1:8449` (as per the example configuration above).
You can then set up another reverse-proxy server on ports 80/443/8448 for all of the expected domains and make traffic go to these local ports.
The expected domains vary depending on the services you have enabled (`matrix.DOMAIN` for sure; `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN` are optional).
### Sample configuration for running behind Traefik 2.0
Below is a sample configuration for using this playbook with a [Traefik](https://traefik.io/) 2.0 reverse proxy.
```yaml
# Disable generation and retrieval of SSL certs
matrix_ssl_retrieval_method: none
# Configure Nginx to only use plain HTTP
matrix_nginx_proxy_https_enabled: false
# Don't bind any HTTP or federation port to the host
# (Traefik will proxy directly into the containers)
matrix_nginx_proxy_container_http_host_bind_port: ''
matrix_nginx_proxy_container_federation_host_bind_port: ''
# Trust the reverse proxy to send the correct `X-Forwarded-Proto` header as it is handling the SSL connection.
matrix_nginx_proxy_trust_forwarded_proto: true
# Trust and use the other reverse proxy's `X-Forwarded-For` header.
matrix_nginx_proxy_x_forwarded_for: '$proxy_add_x_forwarded_for'
# Disable Coturn because it needs SSL certs
# (Clients can, though exposing IP address, use Matrix.org TURN)
matrix_coturn_enabled: false
# All containers need to be on the same Docker network as Traefik
# (This network should already exist and Traefik should be using this network)
matrix_docker_network: 'traefik'
matrix_nginx_proxy_container_extra_arguments:
# May be unnecessary depending on Traefik config, but can't hurt
- '--label "traefik.enable=true"'
# The Nginx proxy container will receive traffic from these subdomains
- '--label "traefik.http.routers.matrix-nginx-proxy.rule=Host(`{{ matrix_server_fqn_matrix }}`,`{{ matrix_server_fqn_element }}`,`{{ matrix_server_fqn_dimension }}`,`{{ matrix_server_fqn_jitsi }}`)"'
# (The 'web-secure' entrypoint must bind to port 443 in Traefik config)
- '--label "traefik.http.routers.matrix-nginx-proxy.entrypoints=web-secure"'
# (The 'default' certificate resolver must be defined in Traefik config)
- '--label "traefik.http.routers.matrix-nginx-proxy.tls.certResolver=default"'
# The Nginx proxy container uses port 8080 internally
- '--label "traefik.http.services.matrix-nginx-proxy.loadbalancer.server.port=8080"'
matrix_synapse_container_extra_arguments:
# May be unnecessary depending on Traefik config, but can't hurt
- '--label "traefik.enable=true"'
# The Synapse container will receive traffic from this subdomain
- '--label "traefik.http.routers.matrix-synapse.rule=Host(`{{ matrix_server_fqn_matrix }}`)"'
# (The 'synapse' entrypoint must bind to port 8448 in Traefik config)
- '--label "traefik.http.routers.matrix-synapse.entrypoints=synapse"'
# (The 'default' certificate resolver must be defined in Traefik config)
- '--label "traefik.http.routers.matrix-synapse.tls.certResolver=default"'
# The Synapse container uses port 8048 internally
- '--label "traefik.http.services.matrix-synapse.loadbalancer.server.port=8048"'
```
This method uses labels attached to the Nginx and Synapse containers to provide the Traefik Docker provider with the information it needs to proxy `matrix.DOMAIN`, `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN`. Some [static configuration](https://docs.traefik.io/v2.0/reference/static-configuration/file/) is required in Traefik; namely, having endpoints on ports 443 and 8448 and having a certificate resolver.
Note that this configuration on its own does **not** redirect traffic on port 80 (plain HTTP) to port 443 for HTTPS, which may cause some issues, since the built-in Nginx proxy usually does this. If you are not already doing this in Traefik, it can be added to Traefik in a [file provider](https://docs.traefik.io/v2.0/providers/file/) as follows:
```toml
[http]
@ -86,7 +216,7 @@ version: "3.3"
services:
traefik:
image: "docker.io/traefik:v2.9.6"
image: "traefik:v2.3"
restart: always
container_name: "traefik"
networks:
@ -97,8 +227,7 @@ services:
- "--providers.docker.network=traefik"
- "--providers.docker.exposedbydefault=false"
- "--entrypoints.web-secure.address=:443"
- "--entrypoints.matrix-federation.address=:8448"
- "--entrypoints.matrix-internal-matrix-client-api.address=:8008"
- "--entrypoints.synapse.address=:8448"
- "--certificatesresolvers.default.acme.tlschallenge=true"
- "--certificatesresolvers.default.acme.email=YOUR EMAIL"
- "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json"
@ -113,96 +242,3 @@ networks:
traefik:
external: true
```
## Another webserver
If you don't wish to use Traefik, you can also use your own webserver.
Doing this is possible, but requires manual work.
There are 2 ways to go about it:
- (recommended) [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) - using the playbook-managed reverse-proxy (Traefik), but disabling SSL termination for it, exposing this reverse-proxy on a few local ports (e.g. `127.0.0.1:81`, etc.) and forwarding traffic from your own webserver to those few ports
- (difficult) [Using no reverse-proxy on the Matrix side at all](#using-no-reverse-proxy-on-the-matrix-side-at-all) disabling the playbook-managed reverse-proxy (Traefik), exposing services one by one using `_host_bind_port` variables and forwarding traffic from your own webserver to those ports
### Fronting the integrated reverse-proxy webserver with another reverse-proxy
This method is about leaving the integrated reverse-proxy webserver be, but making it not get in the way (using up important ports, trying to retrieve SSL certificates, etc.).
If you wish to use another webserver, the integrated reverse-proxy webserver usually gets in the way because it attempts to fetch SSL certificates and binds to ports 80, 443 and 8448 (if Matrix Federation is enabled).
You can disable such behavior and make the integrated reverse-proxy webserver only serve traffic locally on the host itself (or over a local network).
This is the recommended way for using another reverse-proxy, because the integrated one would act as a black box and wire all Matrix services correctly. You would then only need to reverse-proxy a few individual domains and ports over to it.
To front Traefik with another reverse-proxy, you would need some configuration like this:
```yaml
matrix_playbook_reverse_proxy_type: playbook-managed-traefik
# Ensure that public urls use https
matrix_playbook_ssl_enabled: true
# Disable the web-secure (port 443) endpoint, which also disables SSL certificate retrieval.
# This has the side-effect of also automatically disabling TLS for the matrix-federation entrypoint
# (by toggling `matrix_federation_traefik_entrypoint_tls`).
traefik_config_entrypoint_web_secure_enabled: false
# If your reverse-proxy runs on another machine, consider using `0.0.0.0:81`, just `81` or `SOME_IP_ADDRESS_OF_THIS_MACHINE:81`
traefik_container_web_host_bind_port: '127.0.0.1:81'
# We bind to `127.0.0.1` by default (see above), so trusting `X-Forwarded-*` headers from
# a reverse-proxy running on the local machine is safe enough.
# If you're publishing the port (`traefik_container_web_host_bind_port` above) to a public network interface:
# - remove the `traefik_config_entrypoint_web_forwardedHeaders_insecure` variable definition below
# - uncomment and adjust the `traefik_config_entrypoint_web_forwardedHeaders_trustedIPs` line below
traefik_config_entrypoint_web_forwardedHeaders_insecure: true
# traefik_config_entrypoint_web_forwardedHeaders_trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY']
# Expose the federation entrypoint on a custom port (other than port 8448, which is normally used publicly).
#
# We bind to `127.0.0.1` by default (see above), so trusting `X-Forwarded-*` headers from
# a reverse-proxy running on the local machine is safe enough.
#
# If your reverse-proxy runs on another machine, consider:
# - using `0.0.0.0:8449`, just `8449` or `SOME_IP_ADDRESS_OF_THIS_MACHINE:8449` below
# - adjusting `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom` (below) - removing `insecure: true` and enabling/configuring `trustedIPs`
matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: '127.0.0.1:8449'
# Disable HTTP/3 for the federation entrypoint.
# If you'd like HTTP/3, consider configuring it for your other reverse-proxy.
#
# Disabling this also sets `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port_udp` to an empty value.
# If you'd like to keep HTTP/3 enabled here (for whatever reason), you may wish to explicitly
# set `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port_udp` to something like '127.0.0.1:8449'.
matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_http3_enabled: false
# Depending on the value of `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port` above,
# this may need to be reconfigured. See the comments above.
matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom:
forwardedHeaders:
insecure: true
# trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY']
```
Such a configuration would expose all services on a local port `81` and Matrix Federation on a local port `8449`.
Your reverse-proxy configuration needs to send traffic to these ports. The [`examples/reverse-proxies` directory](../examples/reverse-proxies/) contains sample configuration for various webservers (Apache2, Caddy, HAproxy, nginx, Nginx Proxy Manager).
It's important that these webservers proxy-pass requests to the correct place and also set the `Host` HTTP header appropriately.
If you don't pass the `Host` header correctly, you would get a 404 not found error from Traefik.
To put it another way, `curl http://127.0.0.1:81` would give you a 404, but `curl -H 'Host: matrix.DOMAIN' http://127.0.0.1:81` should work.
### Using no reverse-proxy on the Matrix side at all
Instead of [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy), you can also go another way -- completely disabling the playbook-managed Traefik reverse-proxy. You would then need to reverse-proxy from your own webserver directly to each individual Matrix service.
This is more difficult, as you would need to handle the configuration for each service manually. Enabling additional services would come with extra manual work you need to do.
Also, the Traefik reverse-proxy, besides fronting everything is also serving a 2nd purpose of allowing addons services to communicate with the Matrix homeserver thanks to its `matrix-internal-matrix-client-api` entrypoint (read more about it above). Disabling Traefik completely means the playbook would wire services to directly talk to the homeserver. This can work for basic setups, but not for more complex setups involving [matrix-media-repo](./configuring-playbook-matrix-media-repo.md), [matrix-corporal](./configuring-playbook-matrix-corporal.md) or other such services that need to "steal routes" from the homeserver.
If your webserver is on the same machine, ensure your web server user (something like `http`, `apache`, `www-data`, `nginx`) is part of the `matrix` group. You should run something like this: `usermod -a -G matrix nginx`. This allows your webserver user to access files owned by the `matrix` group, so that it can serve static files from `/matrix/static-files`.

21
docs/configuring-playbook-pantalaimon.md
View File

@ -1,21 +0,0 @@
# Setting up pantalaimon (optional)
The playbook can install and configure the [pantalaimon](https://github.com/matrix-org/pantalaimon) E2EE aware proxy daemon for you.
See the project's [documentation](https://github.com/matrix-org/pantalaimon) to learn what it does and why it might be useful to you.
This role exposes Pantalaimon's API only within the container network, so bots and clients installed on the same machine can use it. In particular the [Draupnir](configuring-playbook-bot-draupnir.md) and [Mjolnir](configuring-playbook-bot-mjolnir.md) roles (and possibly others) can use it.
## 1. Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
matrix_pantalaimon_enabled: true
```
The default configuration should suffice. For advanced configuration, you can override the variables documented in the role's [defaults](../roles/custom/matrix-pantalaimon/defaults/main.yml).
## 2. Installing
After configuring the playbook, run the [installation](installing.md) command.

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

@ -1,6 +1,6 @@
# Setting up postgres backup (optional)
The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you via the [com.devture.ansible.role.postgres_backup](https://github.com/devture/com.devture.ansible.role.postgres_backup) Ansible role.
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.
@ -10,7 +10,7 @@ For a more complete backup solution (one that includes not only Postgres, but al
Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable Postgres backup:
```yaml
postgres_backup_enabled: true
matrix_postgres_backup_enabled: true
```
Refer to the table below for additional configuration variables and their default values.
@ -18,13 +18,12 @@ Refer to the table below for additional configuration variables and their defaul
| Name | Default value | Description |
| :-------------------------------- | :--------------------------- | :--------------------------------------------------------------- |
|`postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
|`postgres_backup_schedule`| `'@daily'` |Cron-schedule specifying the interval between postgres backups.|
|`postgres_backup_keep_days`|`7`|Number of daily backups to keep|
|`postgres_backup_keep_weeks`|`4`|Number of weekly backups to keep|
|`postgres_backup_keep_months`|`12`|Number of monthly backups to keep|
|`postgres_backup_base_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Base path for postgres-backup. Also see `postgres_backup_data_path` |
|`postgres_backup_data_path` | `"{{ postgres_backup_base_path }}/data"` | Storage path for postgres-backup database backups |
|`matrix_postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
|`matrix_postgres_backup_schedule`| `'@daily'` |Cron-schedule specifying the interval between postgres backups.|
|`matrix_postgres_backup_keep_days`|`7`|Number of daily backups to keep|
|`matrix_postgres_backup_keep_weeks`|`4`|Number of weekly backups to keep|
|`matrix_postgres_backup_keep_months`|`12`|Number of monthly backups to keep|
|`matrix_postgres_backup_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Storagepath for the database backups|
## Installing

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

@ -7,27 +7,20 @@ You can enable this with the following settings in your configuration file (`inv
Remember to add `stats.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
```yaml
prometheus_enabled: true
matrix_prometheus_enabled: true
# You can remove this, if unnecessary.
prometheus_node_exporter_enabled: true
matrix_prometheus_node_exporter_enabled: true
# You can remove this, if unnecessary.
prometheus_postgres_exporter_enabled: true
matrix_grafana_enabled: true
# You can remove this, if unnecessary.
matrix_prometheus_nginxlog_exporter_enabled: true
grafana_enabled: true
grafana_anonymous_access: false
matrix_grafana_anonymous_access: false
# This has no relation to your Matrix user id. It can be any username you'd like.
# Changing the username subsequently won't work.
grafana_default_admin_user: "some_username_chosen_by_you"
matrix_grafana_default_admin_user: "some_username_chosen_by_you"
# Changing the password subsequently won't work.
grafana_default_admin_password: "some_strong_password_chosen_by_you"
matrix_grafana_default_admin_password: "some_strong_password_chosen_by_you"
```
By default, a [Grafana](https://grafana.com/) web user-interface will be available at `https://stats.<your-domain>`.
@ -39,63 +32,44 @@ The retention policy of Prometheus metrics is [15 days by default](https://prome
Name | Description
-----|----------
`prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
`prometheus_node_exporter_enabled`|[Node Exporter](https://prometheus.io/docs/guides/node-exporter/) is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
`prometheus_postgres_exporter_enabled`|[Postgres Exporter](configuring-playbook-prometheus-postgres.md) is an addon of sorts to expose Postgres database metrics to Prometheus.
`matrix_prometheus_nginxlog_exporter_enabled`|[NGINX Log Exporter](configuring-playbook-prometheus-nginxlog.md) is an addon of sorts to expose NGINX logs to Prometheus.
`grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
`grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
`grafana_default_admin_user`<br>`grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
`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_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
## Security and privacy
Metrics and resulting graphs can contain a lot of information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `matrix_prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
## Collecting metrics to an external Prometheus server
**If the integrated Prometheus server is enabled** (`prometheus_enabled: true`), metrics are collected by it from each service via communication that happens over the container network. Each service does not need to expose its metrics "publicly".
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.
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 expose all services on this `/metrics/*` feature, use `matrix_metrics_exposure_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` below.
When using `matrix_metrics_exposure_enabled`, you don't need to expose metrics for individual services one by one.
The following variables may be of interest:
To do this, you may be interested in the following variables:
Name | Description
-----|----------
`matrix_metrics_exposure_enabled`|Set this to `true` to **enable metrics exposure for all services** on `https://matrix.DOMAIN/metrics/*`. If you think this is too much, refer to the helpful (but nonexhaustive) list of individual `matrix_SERVICE_metrics_proxying_enabled` (or similar) variables below for exposing metrics on a per-service basis.
`matrix_metrics_exposure_http_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.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_metrics_exposure_http_basic_auth_users`|Set this to the Basic Authentication credentials (raw `htpasswd` file content) used to protect `/metrics/*`. This htpasswd-file needs to be generated with the `htpasswd` tool and can include multiple username/password pairs.
`matrix_synapse_metrics_enabled`|Set this to `true` to make Synapse expose metrics (locally, on the container network)
`matrix_synapse_metrics_proxying_enabled`|Set this to `true` to expose Synapse's metrics on `https://matrix.DOMAIN/metrics/synapse/main-process` and `https://matrix.DOMAIN/metrics/synapse/worker/TYPE-ID`. Read [below](#collecting-synapse-worker-metrics-to-an-external-prometheus-server) if you're running a Synapse worker setup (`matrix_synapse_workers_enabled: true`). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
`prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network)
`prometheus_node_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.DOMAIN/metrics/node-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
`prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](configuring-playbook-prometheus-postgres.md) (locally, on the container network)
`prometheus_postgres_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.DOMAIN/metrics/postgres-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
`matrix_prometheus_nginxlog_exporter_enabled`|Set this to `true` to enable the [NGINX Log exporter](configuring-playbook-prometheus-nginxlog.md) (locally, on the container network)
`matrix_sliding_sync_metrics_enabled`|Set this to `true` to make [Sliding Sync](configuring-playbook-sliding-sync-proxy.md) expose metrics (locally, on the container network)
`matrix_sliding_sync_metrics_proxying_enabled`|Set this to `true` to expose the [Sliding Sync](configuring-playbook-sliding-sync-proxy.md) metrics on `https://matrix.DOMAIN/metrics/sliding-sync`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
`matrix_bridge_hookshot_metrics_enabled`|Set this to `true` to make [Hookshot](configuring-playbook-bridge-hookshot.md) expose metrics (locally, on the container network)
`matrix_bridge_hookshot_metrics_proxying_enabled`|Set this to `true` to expose the [Hookshot](configuring-playbook-bridge-hookshot.md) metrics on `https://matrix.DOMAIN/metrics/hookshot`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
`matrix_SERVICE_metrics_proxying_enabled`|Various other services/roles may provide similar `_metrics_enabled` and `_metrics_proxying_enabled` variables for exposing their metrics. Refer to each role for details. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above or `matrix_SERVICE_container_labels_metrics_middleware_basic_auth_enabled`/`matrix_SERVICE_container_labels_metrics_middleware_basic_auth_users` variables provided by each role.
`matrix_media_repo_metrics_enabled`|Set this to `true` to make media-repo expose metrics (locally, on the container network)
`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`)
### Collecting Synapse worker metrics to an external Prometheus server
### Collecting 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/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`.
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`.
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`.
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`.
It will look a bit like this:
```yaml
scrape_configs:
- job_name: 'synapse'
metrics_path: /metrics/synapse/main-process
metrics_path: /_synapse/metrics
scheme: https
basic_auth:
username: prometheus
@ -105,8 +79,8 @@ scrape_configs:
labels:
job: "master"
index: 1
- job_name: 'matrix-synapse-synapse-worker-generic-worker-0'
metrics_path: /metrics/synapse/worker/generic-worker-0
- job_name: 'synapse-generic_worker-1'
metrics_path: /_synapse-worker-generic_worker-18111/metrics
scheme: https
basic_auth:
username: prometheus
@ -118,11 +92,43 @@ 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 this to `true` to enable the node (general system stats) exporter
`matrix_prometheus_postgres_exporter_enabled`|Set this to `true` to enable the Postgres exporter
`matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks`|Add locations to this list depending on which of the above exporters you enabled (see below)
```nginx
matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks:
- 'location /node-exporter/ {
resolver 127.0.0.11 valid=5s;
proxy_pass http://matrix-prometheus-node-exporter:9100/;
auth_basic "protected";
auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
}'
- 'location /postgres-exporter/ {
resolver 127.0.0.11 valid=5s;
proxy_pass http://matrix-prometheus-postgres-exporter:9187/;
auth_basic "protected";
auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
}'
```
You can customize the `location`s to your liking, just point your Prometheus to there later (e.g. `stats.DOMAIN/node-exporter/metrics`). Nginx is very picky about the `proxy_pass`syntax: take care to follow the example closely and note the trailing slash as well as absent use of variables. postgres-exporter uses the nonstandard port 9187.
## More information
- [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md)
- [Understanding Synapse Performance Issues Through Grafana Graphs](https://element-hq.github.io/synapse/latest/usage/administration/understanding_synapse_through_grafana_graphs.html) at the Synapse Github Wiki
- [The Prometheus scraping rules](https://github.com/element-hq/synapse/tree/master/contrib/prometheus) (we use v2)
- [The Synapse Grafana dashboard](https://github.com/element-hq/synapse/tree/master/contrib/grafana)
- [Understanding Synapse Performance Issues Through Grafana Graphs](https://github.com/matrix-org/synapse/wiki/Understanding-Synapse-Performance-Issues-Through-Grafana-Graphs) at the Synapse Github Wiki
- [The Prometheus scraping rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus) (we use v2)
- [The Synapse Grafana dashboard](https://github.com/matrix-org/synapse/tree/master/contrib/grafana)
- [The Node Exporter dashboard](https://github.com/rfrail3/grafana-dashboards) (for generic non-synapse performance graphs)

54
docs/configuring-playbook-prometheus-nginxlog.md
View File

@ -1,54 +0,0 @@
# Enabling metrics and graphs for NginX logs (optional)
It can be useful to have some (visual) insight into [nginx](https://nginx.org/) logs.
This adds [prometheus-nginxlog-exporter](https://github.com/martin-helmich/prometheus-nginxlog-exporter/) to your Matrix deployment.
It will collect access logs from various nginx reverse-proxies which may be used internally (e.g. `matrix-synapse-reverse-proxy-companion`, if Synapse workers are enabled) and will make them available at a Prometheus-compatible `/metrics` endpoint.
**NOTE**: nginx is only used internally by this Ansible playbook. With Traefik being our default reverse-proxy, collecting nginx metrics is less relevant.
To make use of this, you need to install [Prometheus](./configuring-playbook-prometheus-grafana.md) either via the playbook or externally. When using an external Prometheus, configuration adjustments are necessary - see [Save metrics on an external Prometheus server](#save-metrics-on-an-external-prometheus-server).
If your setup includes [Grafana](./configuring-playbook-prometheus-grafana.md), a dedicated `NGINX PROXY` Grafana dashboard will be created.
## Configuration
You can enable this role by adding the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_prometheus_nginxlog_exporter_enabled: true
```
Then, re-run the playbook. See [installation](./installing.md).
## Docker Image Compatibility
At the moment of writing only images for `amd64` and `arm64` architectures are available
The playbook currently does not support [self-building](./self-building.md) a container image on other architectures.
You can however use a custom-build image by setting:
```yaml
matrix_prometheus_nginxlog_exporter_docker_image_arch_check_enabled: false
matrix_prometheus_nginxlog_exporter_docker_image: path/to/docker/image:tag
```
## Security and privacy
Metrics and resulting graphs can contain a lot of information. NginX logs contain information like IP address, URLs, UserAgents and more. This information can reveal usage patterns and could be considered Personally Identifiable Information (PII). Think about this before enabling (anonymous) access.
Please make sure you change the default Grafana password.
## Save metrics on an external Prometheus server
The playbook will automatically integrate the metrics into the [Prometheus](./configuring-playbook-prometheus-grafana.md) server provided with this playbook (if enabled). In such cases, the metrics endpoint is not exposed publicly - it's only available on the container network.
When using an external Prometheus server, you'll need to expose metrics publicly. See [Collecting metrics to an external Prometheus server](./configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server).
You can either use `matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled: true` to expose just this one service, or `matrix_metrics_exposure_enabled: true` to expose all services.
Whichever way you go with, this service will expose its metrics endpoint **without password-protection** at `https://matrix.DOMAIN/metrics/nginxlog` by default.
For password-protection, use (`matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`) or (`matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_enabled` and `matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_users`).

14
docs/configuring-playbook-prometheus-postgres.md
View File

@ -6,17 +6,21 @@ You can enable this with the following settings in your configuration file (`inv
```yaml
prometheus_postgres_exporter_enabled: true
matrix_prometheus_postgres_exporter_enabled: true
# the role creates a postgres user as credential. You can configure these if required:
matrix_prometheus_postgres_exporter_database_username: 'matrix_prometheus_postgres_exporter'
matrix_prometheus_postgres_exporter_database_password: 'some-password'
```
## What does it do?
Name | Description
-----|----------
`prometheus_postgres_exporter_enabled`|Enable the postgres prometheus exporter. This sets up the docker container, connects it to the database and adds a 'job' to the prometheus config which tells prometheus about this new exporter. The default is 'false'
`prometheus_postgres_exporter_database_username`| The 'username' for the user that the exporter uses to connect to the database. The default is 'matrix_prometheus_postgres_exporter'
`prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook
`prometheus_postgres_exporter_container_labels_traefik_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` on that other documentation page.
`matrix_prometheus_postgres_exporter_enabled`|Enable the postgres prometheus exporter. This sets up the docker container, connects it to the database and adds a 'job' to the prometheus config which tells prometheus about this new exporter. The default is 'false'
`matrix_prometheus_postgres_exporter_database_username`| The 'username' for the user that the exporter uses to connect to the database. The default is 'matrix_prometheus_postgres_exporter'
`matrix_prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database.
## More information

63
docs/configuring-playbook-rageshake.md
View File

@ -1,63 +0,0 @@
# Setting up Rageshake (optional)
The playbook can install and configure the [rageshake](https://github.com/matrix-org/rageshake) bug report server for you.
This is useful if you're developing your own applications and would like to collect bug reports for them.
## Decide on a domain and path
By default, Rageshake is configured to use its own dedicated domain (`rageshake.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
# so we won't need to add additional DNS records for Rageshake.
matrix_rageshake_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /rageshake subpath
matrix_rageshake_path_prefix: /rageshake
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Rageshake domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Enabling the Rageshake service
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
matrix_rageshake_enabled: true
```
Rageshake has various options which don't have dedicated Ansible variables. You can see the full list of options in the [`rageshake.sample.yaml` file](https://github.com/matrix-org/rageshake/blob/master/rageshake.sample.yaml).
To set these, you can make use of the `matrix_rageshake_configuration_extension_yaml` variable like this:
```yaml
matrix_rageshake_configuration_extension_yaml: |
github_token: secrettoken
github_project_mappings:
my-app: octocat/HelloWorld
```
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
Refer to the [rageshake documentation](https://github.com/matrix-org/rageshake) for available APIs, etc.

11
docs/configuring-playbook-riot-web.md
View File

@ -1,6 +1,6 @@
# Configuring Riot-web (optional)
By default, this playbook **used to install** the [Riot-web](https://github.com/element-hq/riot-web) Matrix client web application.
By default, this playbook **used to install** the [Riot-web](https://github.com/vector-im/riot-web) Matrix client web application.
Riot has since been [renamed to Element](https://element.io/blog/welcome-to-element/).
@ -25,10 +25,15 @@ There are a few options for handling this:
- (**avoiding changes** - using the old `riot.DOMAIN` domain and avoiding DNS changes) -- to keep using `riot.DOMAIN` instead of `element.DOMAIN`, override the domain at which the playbook serves Element: `matrix_server_fqn_element: "riot.{{ matrix_domain }}"`
- (**embracing changes** - using only `element.DOMAIN`) - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.DOMAIN` in this case.
- (**embracing changes** - using only `element.DOMAIN`) - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.DOMAIN` in this case. If so, you may also wish to remove old SSL certificates (`rm -rf /matrix/ssl/config/live/riot.DOMAIN`) and renewal configuration (`rm -f /matrix/ssl/config/renewal/riot.DOMAIN.conf`), so that `certbot` would stop trying to renew them.
- (**embracing changes and transitioning smoothly** - using both `element.DOMAIN` and `riot.DOMAIN`) - to serve Element at the new domain (`element.DOMAIN`) and to also have `riot.DOMAIN` redirect there - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)) and enable Riot to Element redirection (`matrix_nginx_proxy_proxy_riot_compat_redirect_enabled: true`).
### Re-running the playbook
As always, after making the necessary DNS and configuration adjustments, [re-run the playbook](./installing.md) to apply the changes.
As always, after making the necessary DNS and configuration adjustments, re-run the playbook to apply the changes:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```

137
docs/configuring-playbook-s3-goofys.md
View File

@ -1,137 +0,0 @@
# Storing Matrix media files on Amazon S3 with Goofys (optional)
If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
Another (and better performing) way to use S3 storage with Synapse is [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md).
Using a Goofys-backed media store works, but performance may not be ideal. If possible, try to use a region which is close to your Matrix server.
If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.
## Usage
After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure Goofys in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_s3_media_store_enabled: true
matrix_s3_media_store_bucket_name: "your-bucket-name"
matrix_s3_media_store_aws_access_key: "access-key-goes-here"
matrix_s3_media_store_aws_secret_key: "secret-key-goes-here"
matrix_s3_media_store_region: "eu-central-1"
```
You can use any S3-compatible object store by **additionally** configuring these variables:
```yaml
matrix_s3_media_store_custom_endpoint_enabled: true
matrix_s3_media_store_custom_endpoint: "https://your-custom-endpoint"
```
If you have local media store files and wish to migrate to Backblaze B2 subsequently, follow our [migration guide to Backblaze B2](#migrating-to-backblaze-b2) below instead of applying this configuration as-is.
## Migrating from local filesystem storage to S3
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before migrating your local media store to an S3-backed one.
Follow one of the guides below for a migration path from a locally-stored media store to one stored on S3-compatible storage:
- [Storing Matrix media files on Amazon S3 with Goofys (optional)](#storing-matrix-media-files-on-amazon-s3-with-goofys-optional)
- [Usage](#usage)
- [Migrating from local filesystem storage to S3](#migrating-from-local-filesystem-storage-to-s3)
- [Migrating to any S3-compatible storage (universal, but likely slow)](#migrating-to-any-s3-compatible-storage-universal-but-likely-slow)
- [Migrating to Backblaze B2](#migrating-to-backblaze-b2)
### Migrating to any S3-compatible storage (universal, but likely slow)
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
1. Proceed with the steps below without stopping Matrix services
2. Start by adding the base S3 configuration in your `vars.yml` file (seen above, may be different depending on the S3 provider of your choice)
3. In addition to the base configuration you see above, add this to your `vars.yml` file:
```yaml
matrix_s3_media_store_path: /matrix/s3-media-store
```
This enables S3 support, but mounts the S3 storage bucket to `/matrix/s3-media-store` without hooking it to your homeserver yet. Your homeserver will still continue using your local filesystem for its media store.
5. Run the playbook to apply the changes: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
6. Do an **initial sync of your files** by running this **on the server** (it may take a very long time):
```sh
sudo -u matrix -- rsync --size-only --ignore-existing -avr /matrix/synapse/storage/media-store/. /matrix/s3-media-store/.
```
You may need to install `rsync` manually.
7. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
8. Start the S3 service by running this **on the server**: `systemctl start matrix-goofys`
9. Sync the files again by re-running the `rsync` command you see in step #6
10. Stop the S3 service by running this **on the server**: `systemctl stop matrix-goofys`
11. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
12. Remove the `matrix_s3_media_store_path` configuration from your `vars.yml` file (undoing step #3 above)
13. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
14. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
15. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
### Migrating to Backblaze B2
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
1. While all Matrix services are running, run the following command on the server:
(you need to adjust the 3 `--env` line below with your own data)
```sh
docker run -it --rm -w /work \
--env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
--env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
--env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
--mount type=bind,src=/matrix/synapse/storage/media-store,dst=/work,ro \
--entrypoint=/bin/sh \
docker.io/tianon/backblaze-b2:3.6.0 \
-c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET && b2 sync /work b2://$B2_BUCKET_NAME --skipNewer'
```
This is some initial file sync, which may take a very long time.
2. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
3. Run the command from step #1 again.
Doing this will sync any new files that may have been created locally in the meantime.
Now that Matrix services aren't running, we're sure to get Backblaze B2 and your local media store fully in sync.
4. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
5. Put the [Backblaze B2 settings seen above](#backblaze-b2) in your `vars.yml` file
6. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
7. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
8. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`

193
docs/configuring-playbook-s3.md
View File

@ -1,50 +1,19 @@
# Storing Synapse media files on Amazon S3 or another compatible Object Storage (optional)
# Storing Matrix media files on Amazon S3 (optional)
By default, this playbook configures your server to store Synapse's content repository (`media_store`) files on the local filesystem.
If that's alright, you can skip this.
As an alternative to storing media files on the local filesystem, you can store them on [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible object store.
If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
You can do this either by sticking to Synapse's media repository and making that use S3 (read below for this method), or by switching to an external media storage implementation like [matrix-media-repo](configuring-playbook-matrix-media-repo.md).
Using a Goofys-backed media store works, but performance may not be ideal. If possible, try to use a region which is close to your Matrix server.
First, [choose an Object Storage provider](#choosing-an-object-storage-provider).
If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.
Then, [create the S3 bucket](#bucket-creation-and-security-configuration).
Finally, [set up S3 storage for Synapse](#setting-up) (with [Goofys](configuring-playbook-s3-goofys.md), [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md), or use s3 datastore with the [matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/configuration/s3-datastore.html)).
## Choosing an Object Storage provider
You can create [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible object store like [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html), [Wasabi](https://wasabi.com), [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces), etc.
Amazon S3 and Backblaze S3 are pay-as-you with no minimum charges for storing too little data.
All these providers have different prices, with Backblaze B2 appearing to be the cheapest.
Wasabi has a minimum charge of 1TB if you're storing less than 1TB, which becomes expensive if you need to store less data than that.
Digital Ocean Spaces has a minimum charge of 250GB ($5/month as of 2022-10), which is also expensive if you're storing less data than that.
Important aspects of choosing the right provider are:
- a provider by a company you like and trust (or dislike less than the others)
- a provider which has a data region close to your Matrix server (if it's farther away, high latency may cause slowdowns)
- a provider which is OK pricewise
- a provider with free or cheap egress (if you need to get the data out often, for some reason) - likely not too important for the common use-case
## Bucket creation and Security Configuration
Now that you've [chosen an Object Storage provider](#choosing-an-object-storage-provider), you need to create a storage bucket.
How you do this varies from provider to provider, with Amazon S3 being the most complicated due to its vast number of services and complicated security policies.
Below, we provider some guides for common providers. If you don't see yours, look at the others for inspiration or read some guides online about how to create a bucket. Feel free to contribute to this documentation with an update!
## Amazon S3
You'll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example IAM security policy:
You'll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example security policy:
```json
{
@ -65,46 +34,154 @@ You'll need an Amazon S3 bucket and some IAM user credentials (access key + secr
}
```
**NOTE**: This policy needs to be attached to an IAM user created from the **Security Credentials** menu. This is not a **Bucket Policy**.
You then need to enable S3 support in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`).
It would be something like this:
```yaml
matrix_s3_media_store_enabled: true
matrix_s3_media_store_bucket_name: "your-bucket-name"
matrix_s3_media_store_aws_access_key: "access-key-goes-here"
matrix_s3_media_store_aws_secret_key: "secret-key-goes-here"
matrix_s3_media_store_region: "eu-central-1"
```
## Backblaze B2
## Using other S3-compatible object stores
To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html) you first need to sign up.
You can use any S3-compatible object store by **additionally** configuring these variables:
You [can't easily change which region (US, Europe) your Backblaze account stores files in](https://old.reddit.com/r/backblaze/comments/hi1v90/make_the_choice_for_the_b2_data_center_region/), so make sure to carefully choose the region when signing up (hint: it's a hard to see dropdown below the username/password fields in the signup form).
```yaml
matrix_s3_media_store_custom_endpoint_enabled: true
# Example: "https://storage.googleapis.com"
matrix_s3_media_store_custom_endpoint: "your-custom-endpoint"
```
After logging in to Backblaze:
### Backblaze B2
To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html):
- create a new **private** bucket through its user interface (you can call it something like `matrix-DOMAIN-media-store`)
- note the **Endpoint** for your bucket (something like `s3.us-west-002.backblazeb2.com`).
- adjust its Lifecycle Rules to: Keep only the last version of the file
- note the **Endpoint** for your bucket (something like `s3.us-west-002.backblazeb2.com`)
- adjust its lifecycle rules to use the following **custom** rules:
- File Path: *empty value*
- Days Till Hide: *empty value*
- Days Till Delete: `1`
- go to [App Keys](https://secure.backblaze.com/app_keys.htm) and use the **Add a New Application Key** to create a new one
- restrict it to the previously created bucket (e.g. `matrix-DOMAIN-media-store`)
- give it *Read & Write* access
The `keyID` value is your **Access Key** and `applicationKey` is your **Secret Key**.
Copy the `keyID` and `applicationKey`.
For configuring [Goofys](configuring-playbook-s3-goofys.md) or [s3-synapse-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) you will need:
You need the following *additional* playbook configuration (on top of what you see above):
- **Endpoint URL** - this is the **Endpoint** value you saw above, but prefixed with `https://`
```yaml
matrix_s3_media_store_bucket_name: "YOUR_BUCKET_NAME_GOES_HERE"
matrix_s3_media_store_aws_access_key: "YOUR_keyID_GOES_HERE"
matrix_s3_media_store_aws_secret_key: "YOUR_applicationKey_GOES_HERE"
matrix_s3_media_store_custom_endpoint_enabled: true
matrix_s3_media_store_custom_endpoint: "https://s3.us-west-002.backblazeb2.com" # this may be different for your bucket
```
- **Region** - use the value you see in the Endpoint (e.g. `us-west-002`)
- **Storage Class** - use `STANDARD`. Backblaze B2 does not have different storage classes, so it doesn't make sense to use any other value.
If you have local media store files and wish to migrate to Backblaze B2 subsequently, follow our [migration guide to Backblaze B2](#migrating-to-backblaze-b2) below instead of applying this configuration as-is.
## Other providers
## Migrating from local filesystem storage to S3
For other S3-compatible providers, you may not need to configure security policies, etc. (just like for [Backblaze B2](#backblaze-b2)).
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before migrating your local media store to an S3-backed one.
You most likely just need to create an S3 bucket and get some credentials (access key and secret key) for accessing the bucket in a read/write manner.
Follow one of the guides below for a migration path from a locally-stored media store to one stored on S3-compatible storage:
- [Migrating to any S3-compatible storage (universal, but likely slow)](#migrating-to-any-s3-compatible-storage-universal-but-likely-slow)
- [Migrating to Backblaze B2](#migrating-to-backblaze-b2)
### Migrating to any S3-compatible storage (universal, but likely slow)
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
1. Proceed with the steps below without stopping Matrix services
2. Start by adding the base S3 configuration in your `vars.yml` file (seen above, may be different depending on the S3 provider of your choice)
3. In addition to the base configuration you see above, add this to your `vars.yml` file:
```yaml
matrix_s3_media_store_path: /matrix/s3-media-store
```
This enables S3 support, but mounts the S3 storage bucket to `/matrix/s3-media-store` without hooking it to your homeserver yet. Your homeserver will still continue using your local filesystem for its media store.
5. Run the playbook to apply the changes: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
6. Do an **initial sync of your files** by running this **on the server** (it may take a very long time):
```sh
sudo -u matrix -- rsync --size-only --ignore-existing -avr /matrix/synapse/storage/media-store/. /matrix/s3-media-store/.
```
You may need to install `rsync` manually.
7. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
8. Start the S3 service by running this **on the server**: `systemctl start matrix-goofys`
9. Sync the files again by re-running the `rsync` command you see in step #6
10. Stop the S3 service by running this **on the server**: `systemctl stop matrix-goofys`
11. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
12. Remove the `matrix_s3_media_store_path` configuration from your `vars.yml` file (undoing step #3 above)
13. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
14. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
15. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
## Setting up
### Migrating to Backblaze B2
To set up Synapse to store files in S3, follow the instructions for the method of your choice:
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
- using [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) (recommended)
- using [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md)
- using [matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/configuration/s3-datastore.html)
1. While all Matrix services are running, run the following command on the server:
(you need to adjust the 3 `--env` line below with your own data)
```sh
docker run -it --rm -w /work \
--env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
--env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
--env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
-v /matrix/synapse/storage/media-store/:/work \
--entrypoint=/bin/sh \
docker.io/tianon/backblaze-b2:2.1.0 \
-c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET > /dev/null && b2 sync /work/ b2://$B2_BUCKET_NAME'
```
This is some initial file sync, which may take a very long time.
2. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
3. Run the command from step #1 again.
Doing this will sync any new files that may have been created locally in the meantime.
Now that Matrix services aren't running, we're sure to get Backblaze B2 and your local media store fully in sync.
4. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
5. Put the [Backblaze B2 settings seen above](#backblaze-b2) in your `vars.yml` file
6. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
7. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
8. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`

61
docs/configuring-playbook-sliding-sync-proxy.md
View File

@ -1,61 +0,0 @@
# Setting up Sliding Sync Proxy (optional)
The playbook can install and configure [sliding-sync](https://github.com/matrix-org/sliding-sync) proxy for you.
Sliding Sync is an implementation of [MSC3575](https://github.com/matrix-org/matrix-spec-proposals/blob/kegan/sync-v3/proposals/3575-sync.md) and a prerequisite for running the new (**still beta**) Element X clients ([Element X iOS](https://github.com/element-hq/element-x-ios) and [Element X Android](https://github.com/element-hq/element-x-android)).
See the project's [documentation](https://github.com/matrix-org/sliding-sync) to learn more.
Element X iOS is [available on TestFlight](https://testflight.apple.com/join/uZbeZCOi).
Element X Android is [available on the Github Releases page](https://github.com/element-hq/element-x-android/releases).
**NOTE**: The sliding-sync proxy is **not required** when using the **Conduit homeserver**. Starting from version `0.6.0` Conduit has native support for some sliding sync features. If there are issues with the native implementation, you might have a better experience when enabling the sliding-sync proxy anyway.
## Decide on a domain and path
By default, the Sliding Sync proxy is configured to be served on the Matrix domain (`matrix.DOMAIN`, controlled by `matrix_server_fqn_matrix`), under the `/sliding-sync` path.
This makes it easy to set it up, **without** having to [adjust your DNS records](#adjusting-dns-records).
If you'd like to run the Sliding Sync proxy on another hostname or path, use the `matrix_sliding_sync_hostname` and `matrix_sliding_sync_path_prefix` variables.
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_sliding_sync_enabled: true
```
## Installing
After potentially [adjusting DNS records](#adjusting-dns-records) and configuring the playbook, run the [installation](installing.md) command again: `just install-all`.
### External databases
Please note that, if your setup utilizes an external database, you must also establish configuration for the sliding sync proxy. Alter the defaults below to suit your configuration:
```yaml
matrix_sliding_sync_database_username: 'matrix_sliding_sync'
matrix_sliding_sync_database_password: ''
matrix_sliding_sync_database_hostname: ''
matrix_sliding_sync_database_port: 5432
matrix_sliding_sync_database_name: 'matrix_sliding_sync'
```
## Usage
You **don't need to do anything special** to make use of the Sliding Sync Proxy.
Simply open your client which supports Sliding Sync (like Element X) and log in.
When the Sliding Sync proxy is [installed](#installing), your `/.well-known/matrix/client` file is also updated. A new `org.matrix.msc3575.proxy` section and `url` property are added there and made to point to your Sliding Sync proxy's base URL (e.g. `https://matrix.DOMAIN/sliding-sync`).
This allows clients which support Sliding Sync to detect the Sliding Sync Proxy's URL and make use of it.

177
docs/configuring-playbook-ssl-certificates.md
View File

@ -1,126 +1,111 @@
# Adjusting SSL certificate retrieval (optional, advanced)
By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (e.g. `matrix.<your-domain>` and others)
By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (`matrix.<your-domain>` and possibly `element.<your-domain>`)
This guide is about using the integrated Traefik server and doesn't apply if you're using [your own webserver](configuring-playbook-own-webserver.md).
Those certificates are used when configuring the nginx reverse proxy installed by this playbook.
They can also be used for configuring [your own webserver](configuring-playbook-own-webserver.md), in case you're not using the integrated nginx server provided by the playbook.
If you need to retrieve certificates for other domains (e.g. your base domain) or more control over certificate retrieval, read below.
## Using staging Let's Encrypt certificates instead of real ones
Things discussed in this document:
For testing purposes, you may wish to use staging certificates provide by Let's Encrypt.
- [Using self-signed SSL certificates](#using-self-signed-ssl-certificates), if you can't use Let's Encrypt or just need a test setup
You can do this with the following configuration:
- [Using your own SSL certificates](#using-your-own-ssl-certificates), if you don't want to or can't use Let's Encrypt certificates, but are still interested in using the integrated nginx reverse proxy server
```yaml
traefik_config_certificatesResolvers_acme_use_staging: true
```
- [Not bothering with SSL certificates](#not-bothering-with-ssl-certificates), if you're using [your own webserver](configuring-playbook-own-webserver.md) and would rather this playbook leaves SSL certificate management to you
## Disabling SSL termination
For testing or other purposes, you may wish to install services without SSL termination and have services exposed to `http://` instead of `https://`.
You can do this with the following configuration:
```yaml
traefik_config_entrypoint_web_secure_enabled: false
```
- [Obtaining SSL certificates for additional domains](#obtaining-ssl-certificates-for-additional-domains), if you'd like to host additional domains on the Matrix server and would like the playbook to help you obtain and renew certificates for those domains automatically
## Using self-signed SSL certificates
If you'd like to use your own SSL certificates, instead of the default (SSL certificates obtained automatically via [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) from [Let's Encrypt](https://letsencrypt.org/)):
For private deployments (not publicly accessible from the internet), you may not be able to use Let's Encrypt certificates.
- generate your self-signed certificate files
- follow the [Using your own SSL certificates](#using-your-own-ssl-certificates) documentation below
If self-signed certificates are alright with you, you can ask the playbook to generate such for you with the following configuration:
```yaml
matrix_ssl_retrieval_method: self-signed
```
If you get a `Cannot reach homeserver` error in Element, you will have to visit `https://matrix.<your-domain>` in your browser and agree to the certificate exception before you can login.
## Using your own SSL certificates
To use your own SSL certificates with Traefik, you need to:
- disable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/) support
- put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
- register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/)
- put the SSL files on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
If you'd like to manage SSL certificates by yourself and have the playbook use your certificate files, you can use the following configuration:
```yaml
# Disable ACME / Let's Encrypt support.
traefik_config_certificatesResolvers_acme_enabled: false
# Disabling ACME support (above) automatically disables the creation of the SSL directory.
# Force-enable it here, because we'll add our certificate files there.
traefik_ssl_dir_enabled: true
# Tell Traefik to load our custom configuration file (certificates.yml).
# The file is created below, in `aux_file_definitions`.
# The `/config/..` path is an in-container path, not a path on the host (like `/matrix/traefik/config`). Do not change it!
traefik_configuration_extension_yaml: |
providers:
file:
filename: /config/certificates.yml
watch: true
# Use the aux role to create our custom files on the server.
# If you'd like to do this manually, you remove this `aux_file_definitions` variable.
aux_file_definitions:
# Create the privkey.pem file on the server by
# uploading a file from the computer where Ansible is running.
- dest: "{{ traefik_ssl_dir_path }}/privkey.pem"
src: /path/on/your/Ansible/computer/to/privkey.pem
# Alternatively, comment out `src` above and uncomment the lines below to provide the certificate content inline.
# Note the indentation level.
# content: |
# FILE CONTENT
# HERE
# Create the cert.pem file on the server
# uploading a file from the computer where Ansible is running.
- dest: "{{ traefik_ssl_dir_path }}/cert.pem"
src: /path/on/your/Ansible/computer/to/cert.pem
# Alternatively, comment out `src` above and uncomment the lines below to provide the certificate content inline.
# Note the indentation level.
# content: |
# FILE CONTENT
# HERE
# Create the custom Traefik configuration.
# The `/ssl/..` paths below are in-container paths, not paths on the host (/`matrix/traefik/ssl/..`). Do not change them!
- dest: "{{ traefik_config_dir_path }}/certificates.yml"
content: |
tls:
certificates:
- certFile: /ssl/cert.pem
keyFile: /ssl/privkey.pem
stores:
default:
defaultCertificate:
certFile: /ssl/cert.pem
keyFile: /ssl/privkey.pem
matrix_ssl_retrieval_method: manually-managed
```
## Using a DNS-01 ACME challenge type, instead of HTTP-01
With such a configuration, the playbook would expect you to drop the SSL certificate files in the directory specified by `matrix_ssl_config_dir_path` (`/matrix/ssl/config` by default) obeying the following hierarchy:
You can configure Traefik to use the [DNS-01 challenge type](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) for Let's Encrypt. This is less commonly used than the default [HTTP-01 challenge type](https://letsencrypt.org/docs/challenge-types/#http-01-challenge), but it can be helpful to:
- `<matrix_ssl_config_dir_path>/live/<domain>/fullchain.pem`
- `<matrix_ssl_config_dir_path>/live/<domain>/privkey.pem`
- `<matrix_ssl_config_dir_path>/live/<domain>/chain.pem`
- hide your public IP from Let's Encrypt logs
- allow you to obtain SSL certificates for servers which are not accessible (via HTTP) from the public internet (and for which the HTTP-01 challenge would fail)
where `<domain>` refers to the domains that you need (usually `matrix.<your-domain>` and `element.<your-domain>`).
This is an example for how to edit the `vars.yml` file if you're using Cloudflare:
## Not bothering with SSL certificates
If you're [using an external web server](configuring-playbook-own-webserver.md) which is not nginx, or you would otherwise want to manage its certificates without this playbook getting in the way, you can completely disable SSL certificate management with the following configuration:
```yaml
traefik_config_certificatesResolvers_acme_dnsChallenge_enabled: true
traefik_config_certificatesResolvers_acme_dnsChallenge_provider: "cloudflare"
traefik_config_certificatesResolvers_acme_dnsChallenge_delayBeforeCheck: 60
traefik_config_certificatesResolvers_acme_dnsChallenge_resolvers:
- "1.1.1.1:53"
traefik_environment_variables_additional_variables: |
CF_API_EMAIL=redacted
CF_ZONE_API_TOKEN=redacted
CF_DNS_API_TOKEN=redacted
LEGO_DISABLE_CNAME_SUPPORT=true
matrix_ssl_retrieval_method: none
```
Make sure to change the value of "provider" to your particular DNS solution, and provide the appropriate environment variables. The full list of supported providers is available [here](https://doc.traefik.io/traefik/https/acme/#providers).
With such a configuration, no certificates will be retrieved at all. You're free to manage them however you want.
This example assumes you're using Cloudflare to manage your DNS zone. Note that it requires the use of two tokens: one for reading all zones (`CF_ZONE_API_TOKEN`) and another that must be able to edit the particular domain you're using (`CF_DNS_API_TOKEN`). For security, it's recommended that you create two fine-grained tokens for this purpose, but you might choose to use the same token for both.
## Obtaining SSL certificates for additional domains
The playbook tries to be smart about the certificates it will obtain for you.
By default, it obtains certificates for:
- `matrix.<your-domain>` (`matrix_server_fqn_matrix`)
- possibly for `element.<your-domain>`, unless you have disabled the [Element client component](configuring-playbook-client-element.md) using `matrix_client_element_enabled: false`
- possibly for `riot.<your-domain>`, if you have explicitly enabled Riot to Element redirection (for background compatibility) using `matrix_nginx_proxy_proxy_riot_compat_redirect_enabled: true`
- possibly for `hydrogen.<your-domain>`, if you have explicitly [set up Hydrogen client](configuring-playbook-client-hydrogen.md).
- possibly for `cinny.<your-domain>`, if you have explicitly [set up Cinny client](configuring-playbook-client-cinny.md).
- possibly for `dimension.<your-domain>`, if you have explicitly [set up Dimension](configuring-playbook-dimension.md).
- possibly for `goneb.<your-domain>`, if you have explicitly [set up Go-NEB bot](configuring-playbook-bot-go-neb.md).
- possibly for `jitsi.<your-domain>`, if you have explicitly [set up Jitsi](configuring-playbook-jitsi.md).
- possibly for `stats.<your-domain>`, if you have explicitly [set up Grafana](configuring-playbook-prometheus-grafana.md).
- possibly for `sygnal.<your-domain>`, if you have explicitly [set up Sygnal](configuring-playbook-sygnal.md).
- possibly for your base domain (`<your-domain>`), if you have explicitly configured [Serving the base domain](configuring-playbook-base-domain-serving.md)
If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too.
To do that, simply define your own custom configuration like this:
```yaml
# In this example, we retrieve 2 extra certificates,
# one for the base domain (in the `matrix_domain` variable) and one for a hardcoded domain.
# Adding any other additional domains (hosted on the same machine) is possible.
matrix_ssl_additional_domains_to_obtain_certificates_for:
- '{{ matrix_domain }}'
- 'another.domain.example.com'
```
After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually obtain certificates you should:
- make sure the web server occupying port 80 is stopped. If you are using matrix-nginx-proxy server (which is the default for this playbook), you need to stop it temporarily by running `systemctl stop matrix-nginx-proxy` on the server.
- re-run the SSL part of the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-ssl,start`
The certificate files would be made available in `/matrix/ssl/config/live/<your-other-domain>/...`.
For automated certificate renewal to work, each port `80` vhost for each domain you are obtaining certificates for needs to forward requests for `/.well-known/acme-challenge` to the certbot container we use for renewal.
See how this is configured for the `matrix.` subdomain in `/matrix/nginx-proxy/conf.d/matrix-synapse.conf`
Don't be alarmed if the above configuration file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.
## Specify the SSL private key algorithm
If you'd like to [specify the private key type](https://eff-certbot.readthedocs.io/en/stable/using.html#using-ecdsa-keys) used with Let's Encrypt, define your own custom configuration like this:
```yaml
matrix_ssl_lets_encrypt_key_type: ecdsa
```

35
docs/configuring-playbook-sygnal.md
View File

@ -11,29 +11,6 @@ See the project's [documentation](https://github.com/matrix-org/sygnal) to learn
This optional playbook component is only useful to people who develop/build their own Matrix client applications themselves.
## Decide on a domain and path
By default, Sygnal is configured to use its own dedicated domain (`sygnal.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
# so we won't need to add additional DNS records for Sygnal.
matrix_sygnal_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /sygnal subpath
matrix_sygnal_path_prefix: /sygnal
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Sygnal domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
@ -53,7 +30,7 @@ matrix_sygnal_apps:
api_key: your_api_key_for_gcm
# .. more configuration ..
aux_file_definitions:
matrix_aux_file_definitions:
- dest: "{{ matrix_sygnal_data_path }}/my_key.p8"
content: |
some
@ -64,21 +41,23 @@ aux_file_definitions:
group: "{{ matrix_user_groupname }}"
```
For a more complete example of available fields and values they can take, see `roles/custom/matrix-sygnal/templates/sygnal.yaml.j2` (or the [upstream `sygnal.yaml.sample` configuration file](https://github.com/matrix-org/sygnal/blob/master/sygnal.yaml.sample)).
For a more complete example of available fields and values they can take, see `roles/matrix-sygnal/templates/sygnal.yaml.j2` (or the [upstream `sygnal.yaml.sample` configuration file](https://github.com/matrix-org/sygnal/blob/master/sygnal.yaml.sample)).
Configuring [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/) is easier, as it only requires that you provide some config values.
To configure [APNS](https://developer.apple.com/notifications/) (Apple Push Notification Service), you'd need to provide one or more certificate files.
To do that, the above example configuration:
- makes use of the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) (and its `aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See [`defaults/main.yml` file](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml) of the `aux` role for usage examples. It also makes sure the files are owned by `matrix:matrix`, so that Sygnal can read them. Of course, you can also install these files manually yourself, if you'd rather not use `aux`.
- makes use of the `matrix-aux` role (and its `matrix_aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See `roles/matrix-aux/defaults/main.yml` for usage examples. It also makes sure the files are owned by `matrix:matrix`, so that Sygnal can read them. Of course, you can also install these files manually yourself, if you'd rather not use `matrix-aux`.
- references these files in the Sygnal configuration (`matrix_sygnal_apps`) using a path like `/data/..` (the `/matrix/sygnal/data` directory on the host system is mounted into the `/data` directory inside the container)
## Installing
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
Don't forget to add `sygnal.<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
@ -87,6 +66,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
## Usage
To make use of your Sygnal installation, you'd need to build your own Matrix client application, which uses the same API keys (for [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/)) and certificates (for [APNS](https://developer.apple.com/notifications/)) and is to your Sygnal URL endpoint (e.g. `https://sygnal.DOMAIN`).
To make use of your Sygnal installation, you'd need to build your own Matrix client application, which uses the same API keys (for [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/)) and certificates (for [APNS](https://developer.apple.com/notifications/)) and is also pointed to `https://sygnal.DOMAIN` as the configured push server.
Refer to Sygnal's [Notes for application developers](https://github.com/matrix-org/sygnal/blob/master/docs/applications.md) document.

49
docs/configuring-playbook-synapse-admin.md
View File

@ -1,10 +1,10 @@
# Setting up Synapse Admin (optional)
The playbook can install and configure [etkecc/synapse-admin](https://github.com/etkecc/synapse-admin) (a [feature-rich](https://github.com/etkecc/synapse-admin#fork-differences) fork of [Awesome-Technologies/synapse-admin](https://github.com/Awesome-Technologies/synapse-admin)) for you.
The playbook can install and configure [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) for you.
synapse-admin is a web UI tool you can use to **administrate users, rooms, media, etc. on your Matrix server**. It's designed to work with the Synapse homeserver implementation, but to some extent may work with [Dendrite](./configuring-playbook-dendrite.md) as well.
It's a web UI tool you can use to **administrate users and rooms on your Matrix server**.
See the project's [documentation](https://github.com/etkecc/synapse-admin) to learn what it does and why it might be useful to you.
See the project's [documentation](https://github.com/Awesome-Technologies/synapse-admin) to learn what it does and why it might be useful to you.
## Adjusting the playbook configuration
@ -15,17 +15,16 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
matrix_synapse_admin_enabled: true
```
**Note**: Synapse Admin requires Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html) to function. Access to them is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, for additional security, we normally leave them unexposed, following [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). Because Synapse Admin needs these APIs to function, when installing Synapse Admin, the playbook **automatically** exposes the Synapse Admin API publicly for you. Depending on the homeserver implementation you're using (Synapse, Dendrite), this is equivalent to:
- for [Synapse](./configuring-playbook-synapse.md) (our default homeserver implementation): `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true`
- for [Dendrite](./configuring-playbook-dendrite.md): `matrix_dendrite_container_labels_public_client_synapse_admin_api_enabled: true`
By default, synapse-admin installation will be [restricted to only work with one homeserver](https://github.com/etkecc/synapse-admin/blob/e21e44362c879ac41f47c580b04210842b6ff3d7/README.md#restricting-available-homeserver) - the one managed by the playbook. To adjust these restrictions, tweak the `matrix_synapse_admin_config_restrictBaseUrl` variable.
**Note**: Synapse Admin requires Synapse's [Admin APIs](https://github.com/matrix-org/synapse/tree/master/docs/admin_api) to function. Access to them is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, for additional security, we normally leave them unexposed, following [official Synapse reverse-proxying recommendations](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints). Because Synapse Admin needs these APIs to function, when installing Synapse Admin, we **automatically** exposes them publicly for you (equivalent to `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true`).
## Installing
After configuring the playbook, run the [installation](installing.md) command again (`just install-all`).
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
@ -33,3 +32,33 @@ After configuring the playbook, run the [installation](installing.md) command ag
After installation, Synapse Admin will be accessible at: `https://matrix.DOMAIN/synapse-admin/`
To use Synapse Admin, you need to have [registered at least one administrator account](registering-users.md) on your server.
The Homeserver URL to use on Synapse Admin's login page is: `https://matrix.DOMAIN`
### Sample configuration for running behind Traefik 2.0
Below is a sample configuration for using this playbook with a [Traefik](https://traefik.io/) 2.0 reverse proxy.
This an extension to Traefik config sample in [own-webserver-documentation](./configuring-playbook-own-webserver.md).
```yaml
# Don't bind any HTTP or federation port to the host
# (Traefik will proxy directly into the containers)
matrix_synapse_admin_container_http_host_bind_port: ""
matrix_synapse_admin_container_extra_arguments:
# May be unnecessary depending on Traefik config, but can't hurt
- '--label "traefik.enable=true"'
# The Synapse Admin container will only receive traffic from this subdomain and path
- '--label "traefik.http.routers.matrix-synapse-admin.rule=(Host(`{{ matrix_server_fqn_matrix }}`) && Path(`{{matrix_synapse_admin_public_endpoint}}`))"'
# (Define your entrypoint)
- '--label "traefik.http.routers.matrix-synapse-admin.entrypoints=web-secure"'
# (The 'default' certificate resolver must be defined in Traefik config)
- '--label "traefik.http.routers.matrix-synapse-admin.tls.certResolver=default"'
# The Synapse Admin container uses port 80 by default
- '--label "traefik.http.services.matrix-synapse-admin.loadbalancer.server.port=80"'
```

47
docs/configuring-playbook-synapse-auto-accept-invite.md
View File

@ -1,47 +0,0 @@
# Setting up Synapse Auto Invite Accept (optional)
The playbook can install and configure [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) for you.
See that project's [documentation](https://github.com/matrix-org/synapse-auto-accept-invite) to learn what it does and why it might be useful to you.
In short, it automatically accepts room invites. You can specify that only 1:1 room invites are auto-accepted. Defaults to false if not specified.
**NOTE**: Synapse [v1.109.0](https://github.com/element-hq/synapse/releases/tag/v1.109.0), the same feature [has been merged](https://github.com/element-hq/synapse/pull/17147) into Synapse (see the [Native alternative](#native-alternative) section below). You'd better use the native feature, instead of the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) 3rd party module.
## Configuration
If you decide that you'd like to let this playbook install the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite module for you, you need a configuration like this:
```yaml
matrix_synapse_ext_synapse_auto_accept_invite_enabled: true
matrix_synapse_ext_synapse_auto_accept_invite_accept_invites_only_direct_messages: true
```
### Synapse worker deployments
In a [workerized Synapse deployment](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/c9a842147e09647c355799ca024d65a5de66b099/docs/configuring-playbook-synapse.md#load-balancing-with-workers) it is possible to run this module on a worker to reduce the load on the main process (Default is `null`). For example, add this to your configuration:
```yaml
matrix_synapse_ext_synapse_auto_accept_invite_worker_to_run_on: 'matrix-synapse-worker-generic-0'
```
There might be an [issue with federation](https://github.com/matrix-org/synapse-auto-accept-invite/issues/18).
## Native alternative
Since Synapse [v1.109.0](https://github.com/element-hq/synapse/releases/tag/v1.109.0), the functionality provided by the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) 3rd party module [has been made](https://github.com/element-hq/synapse/pull/17147) part of Synapse.
Here's example configuration for using the **native** Synapse feature:
```yml
matrix_synapse_auto_accept_invites_enabled: true
# Default settings below. Uncomment and adjust if necessary.
# matrix_synapse_auto_accept_invites_only_for_direct_messages: false
# matrix_synapse_auto_accept_invites_only_from_local_users: false
# If workers are enabled, you may delegate usage to a specific worker.
# matrix_synapse_auto_accept_invites_worker_to_run_on: 'matrix-synapse-worker-generic-0'
```

36
docs/configuring-playbook-synapse-auto-compressor.md
View File

@ -1,36 +0,0 @@
# Setting up synapse_auto_compressor
The playbook can install and configure [synapse_auto_compressor](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) for you.
It's a CLI tool that automatically compresses Synapse's `state_groups` database table in the background.
See the project's [documentation](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) 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_synapse_auto_compressor_enabled: 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
After installation, `synapse_auto_compressor` will run automatically every day at `00:00:00` (as defined in `matrix_synapse_auto_compressor_calendar` by default).
## Manually start the tool
For testing your setup it can be helpful to not wait until 00:00. If you want to run the tool immediately, log onto the server
and run `systemctl start matrix-synapse-auto-compressor`. Running this command will not return control to your terminal until the compression run is done, which may take a long time.
Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.

150
docs/configuring-playbook-synapse-s3-storage-provider.md
View File

@ -1,150 +0,0 @@
# Storing Synapse media files on Amazon S3 with synapse-s3-storage-provider (optional)
If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
you can use the [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) media provider module for Synapse.
An alternative (which has worse performance) is to use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md).
## How it works?
Summarized writings here are inspired by [this article](https://quentin.dufour.io/blog/2021-09-14/matrix-synapse-s3-storage/).
The way media storage providers in Synapse work has some caveats:
- Synapse still continues to use locally-stored files (for creating thumbnails, serving files, etc)
- the media storage provider is just an extra storage mechanism (in addition to the local filesystem)
- all files are stored locally at first, and then copied to the media storage provider (either synchronously or asynchronously)
- if a file is not available on the local filesystem, it's pulled from a media storage provider
You may be thinking **if all files are stored locally as well, what's the point**?
You can run some scripts to delete the local files once in a while (which we do automatically by default - see [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem)), thus freeing up local disk space. If these files are needed in the future (for serving them to users, etc.), Synapse will pull them from the media storage provider on demand.
While you will need some local disk space around, it's only to accommodate usage, etc., and won't grow as large as your S3 store.
## Installing
After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure `s3-storage-provider` in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_synapse_ext_synapse_s3_storage_provider_enabled: true
matrix_synapse_ext_synapse_s3_storage_provider_config_bucket: your-bucket-name
matrix_synapse_ext_synapse_s3_storage_provider_config_region_name: some-region-name # e.g. eu-central-1
matrix_synapse_ext_synapse_s3_storage_provider_config_endpoint_url: https://s3.REGION_NAME.amazonaws.com # adjust this
matrix_synapse_ext_synapse_s3_storage_provider_config_storage_class: STANDARD # or STANDARD_IA, etc.
# Authentication Method 1 - (access key id + secret)
# This works on all providers (AWS and other compatible systems).
# Uncomment the variables below to use it.
# matrix_synapse_ext_synapse_s3_storage_provider_config_access_key_id: access-key-goes-here
# matrix_synapse_ext_synapse_s3_storage_provider_config_secret_access_key: secret-key-goes-here
# Authentication Method 2 - EC2 instance profile which grants permission to access S3
# This only works on AWS when your server is hosted on an EC2 instance with the correct instance profile set.
# Uncomment the variable below to use it.
# matrix_synapse_ext_synapse_s3_storage_provider_config_ec2_instance_profile: true
# For additional advanced settings, take a look at `roles/custom/matrix-synapse/defaults/main.yml`
```
If you have existing files in Synapse's media repository (`/matrix/synapse/media-store/..`):
- new files will start being stored both locally and on the S3 store
- the existing files will remain on the local filesystem only until [migrating them to the S3 store](#migrating-your-existing-media-files-to-the-s3-store)
- at some point (and periodically in the future), you can delete local files which have been uploaded to the S3 store already
Regardless of whether you need to [Migrate your existing files to the S3 store](#migrating-your-existing-media-files-to-the-s3-store) or not, make sure you've familiarized yourself with [How it works?](#how-it-works) above and [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem) below.
## Migrating your existing media files to the S3 store
Migrating your existing data can happen in multiple ways:
- [using the `s3_media_upload` script from `synapse-s3-storage-provider`](#using-the-s3_media_upload-script-from-synapse-s3-storage-provider) (very slow when dealing with lots of data)
- [using another tool in combination with `s3_media_upload`](#using-another-tool-in-combination-with-s3_media_upload) (quicker when dealing with lots of data)
### Using the `s3_media_upload` script from `synapse-s3-storage-provider`
Instead of using `s3_media_upload` directly, which is very slow and painful for an initial data migration, we recommend [using another tool in combination with `s3_media_upload`](#using-another-tool-in-combination-with-s3_media_upload).
To copy your existing files, SSH into the server and run `/matrix/synapse/ext/s3-storage-provider/bin/shell`.
This launches a Synapse container, which has access to the local media store, Postgres database, S3 store and has some convenient environment variables configured for you to use (`MEDIA_PATH`, `BUCKET`, `ENDPOINT`, `UPDATE_DB_DAYS`, etc).
Then use the following commands (`$` values come from environment variables - they're **not placeholders** that you need to substitute):
1. `s3_media_upload update-db $UPDATE_DB_DURATION` - create a local SQLite database (`cache.db`) with a list of media repository files (from the `synapse` Postgres database) eligible for operating on
- `$UPDATE_DB_DURATION` is influenced by the `matrix_synapse_ext_synapse_s3_storage_provider_update_db_day_count` variable (defaults to `0`)
- `$UPDATE_DB_DURATION` defaults to `0d` (0 days), which means **include files which haven't been accessed for more than 0 days** (that is, **all files will be included**).
2. `s3_media_upload check-deleted $MEDIA_PATH` - check whether files in the local cache still exist in the local media repository directory
3. `s3_media_upload upload $MEDIA_PATH $BUCKET --delete --storage-class $STORAGE_CLASS --endpoint-url $ENDPOINT` - uploads locally-stored files to S3 and deletes them from the local media repository directory
The `s3_media_upload upload` command may take a lot of time to complete.
Instead of running the above commands manually in the shell, you can also run the `/matrix/synapse/ext/s3-storage-provider/bin/migrate` script which will run the same commands automatically. We demonstrate how to do it manually, because:
- it's what the upstream project demonstrates and it teaches you how to use the `s3_media_upload` tool
- allows you to check and verify the output of each command, to catch mistakes
- includes progress bars and detailed output for each command
- allows you to easily interrupt slow-running commands, etc. (the `/matrix/synapse/ext/s3-storage-provider/bin/migrate` starts a container without interactive TTY support, so `Ctrl+C` may not work and you and require killing via `docker kill ..`)
### Using another tool in combination with `s3_media_upload`
To migrate your existing local data to S3, we recommend to:
- **first** use another tool ([`aws s3`](#copying-data-to-amazon-s3) or [`b2 sync`](#copying-data-to-backblaze-b2), etc.) to copy the local files to the S3 bucket
- **only then** [use the `s3_media_upload` tool to finish the migration](#using-the-s3_media_upload-script-from-synapse-s3-storage-provider) (this checks to ensure all files are uploaded and then deletes the local files)
#### Copying data to Amazon S3
To copy to AWS S3, start a container on the Matrix server like this:
```sh
docker run -it --rm \
-w /work \
--env-file=/matrix/synapse/ext/s3-storage-provider/env \
--mount type=bind,src=/matrix/synapse/storage/media-store,dst=/work,ro \
--entrypoint=/bin/sh \
docker.io/amazon/aws-cli:2.9.16 \
-c 'aws s3 sync /work/. s3://$BUCKET/'
```
#### Copying data to an S3 alternative using the aws-s3 tool
To copy to a provider other than AWS S3 (e.g. Wasabi, Digital Ocean Spaces, etc.), you can use the command for [Copying data to Amazon S3](#copying-data-to-amazon-s3) with an added `--endpoint-url=$ENDPOINT` argument.
Add this argument to the command **as-is** (`$ENDPOINT` is an environment variable corresponding to `matrix_synapse_ext_synapse_s3_storage_provider_config_endpoint_url`, so you don't need to touch it). Make sure to add the argument **before** the final quote (`'`) of the command.
#### Copying data to Backblaze B2
You can copy files to Backblaze B2 either by following the [Copying data to an S3 alternative using the aws-s3 tool](#copying-data-to-an-s3-alternative-using-the-aws-s3-tool) or by using the B2-specific [b2 command-line tool](https://www.backblaze.com/b2/docs/quick_command_line.html) as described below.
To copy the data using the `b2` tool, start a container on the Matrix server like this:
```sh
docker run -it --rm \
-w /work \
--env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
--env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
--env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
--mount type=bind,src=/matrix/synapse/storage/media-store,dst=/work,ro \
--entrypoint=/bin/sh \
docker.io/tianon/backblaze-b2:3.6.0 \
-c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET && b2 sync /work b2://$B2_BUCKET_NAME --skipNewer'
```
## Periodically cleaning up the local filesystem
As described in [How it works?](#how-it-works) above, when new media is uploaded to the Synapse homeserver, it's first stored locally and then also stored on the remote S3 storage.
By default, we periodically ensure that all local files are uploaded to S3 and are then removed from the local filesystem. This is done automatically using:
- the `/matrix/synapse/ext/s3-storage-provider/bin/migrate` script
- .. invoked via the `matrix-synapse-s3-storage-provider-migrate.service` service
- .. triggered by the `matrix-synapse-s3-storage-provider-migrate.timer` timer, every day at 05:00
So.. you don't need to perform any maintenance yourself.

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