mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2025-02-06 15:25:03 +01:00
Compare commits
1 Commits
28e234deea
...
d35272ffc1
| Author | SHA1 | Date | |
|---|---|---|---|
|
d35272ffc1 |
2
.github/ISSUE_TEMPLATE/feature_request.md
vendored
2
.github/ISSUE_TEMPLATE/feature_request.md
vendored
@ -8,7 +8,7 @@ assignees: ''
|
||||
---
|
||||
|
||||
**Is your feature request related to a problem? Please describe.**
|
||||
A clear and concise description of what the problem is. Ex. I'm always frustrated when […]
|
||||
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
|
||||
|
||||
<!--
|
||||
NOTE: When submitting feature requests, be aware that:
|
||||
|
||||
3
.github/renovate.json
vendored
3
.github/renovate.json
vendored
@ -20,8 +20,5 @@
|
||||
],
|
||||
"ignoreUnstable": false
|
||||
}
|
||||
],
|
||||
"ignoreDeps": [
|
||||
"ghcr.io/matrixgpt/matrix-chatgpt-bot"
|
||||
]
|
||||
}
|
||||
|
||||
327
CHANGELOG.md
327
CHANGELOG.md
File diff suppressed because it is too large
Load Diff
10
README.md
10
README.md
@ -32,8 +32,6 @@ While the [list of supported services](#-supported-services) and documentation i
|
||||
|
||||
- **Full installation guide (for advanced users)**: if you need to import an existing Matrix server's data into the new server or want to learn more while setting up the server, follow this guide by starting with the **[Prerequisites](./docs/prerequisites.md)** documentation page.
|
||||
|
||||
If you experience an issue on configuring the playbook, setting up your server, maintaining services on it, etc., please take a look at our [FAQ](./docs/faq.md). If you cannot find an answer to your question, feel free to ask for [help and support](#-support).
|
||||
|
||||
## ✔ 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.
|
||||
@ -65,6 +63,8 @@ Web clients for Matrix that you can host on your own domains.
|
||||
| [Cinny](https://github.com/ajbura/cinny) | ❌ | Simple, elegant and secure web client | [Link](docs/configuring-playbook-client-cinny.md) |
|
||||
| [SchildiChat Web](https://schildi.chat/) | ❌ | Based on Element Web, with a more traditional instant messaging experience | [Link](docs/configuring-playbook-client-schildichat-web.md) |
|
||||
|
||||
|
||||
|
||||
### Server Components
|
||||
|
||||
Services that run on the server to make the various parts of your installation work.
|
||||
@ -79,6 +79,7 @@ Services that run on the server to make the various parts of your installation w
|
||||
| [ma1sd](https://github.com/ma1uta/ma1sd) | ❌ | Matrix Identity Server | [Link](docs/configuring-playbook-ma1sd.md)
|
||||
| [ddclient](https://github.com/linuxserver/docker-ddclient) | ❌ | Dynamic DNS | [Link](docs/configuring-playbook-dynamic-dns.md) |
|
||||
|
||||
|
||||
### Authentication
|
||||
|
||||
Extend and modify how users are authenticated on your homeserver.
|
||||
@ -93,6 +94,7 @@ Extend and modify how users are authenticated on your homeserver.
|
||||
| [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (UVS) | ❌ | Service to verify details of a user based on an Open ID token | [Link](docs/configuring-playbook-user-verification-service.md) |
|
||||
| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | A spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
|
||||
|
||||
|
||||
### File Storage
|
||||
|
||||
Use alternative file storage to the default `media_store` folder.
|
||||
@ -138,6 +140,7 @@ Bridges can be used to connect your Matrix installation with third-party communi
|
||||
| [Email2Matrix](https://github.com/devture/email2matrix) | ❌ | Bridge for relaying emails to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) |
|
||||
| [Postmoogle](https://github.com/etkecc/postmoogle) | ❌ | Email to Matrix bridge | [Link](docs/configuring-playbook-bridge-postmoogle.md) |
|
||||
|
||||
|
||||
### Bots
|
||||
|
||||
Bots provide various additional functionality to your installation.
|
||||
@ -184,12 +187,14 @@ Various services that don't fit any other categories.
|
||||
| [Sygnal](https://github.com/matrix-org/sygnal) | ❌ | Push gateway | [Link](docs/configuring-playbook-sygnal.md) |
|
||||
| [ntfy](https://ntfy.sh) | ❌ | Push notifications server | [Link](docs/configuring-playbook-ntfy.md) |
|
||||
|
||||
|
||||
## 🆕 Changes
|
||||
|
||||
This playbook evolves over time, sometimes with backward-incompatible changes.
|
||||
|
||||
When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up with what's new.
|
||||
|
||||
|
||||
## 🆘 Support
|
||||
|
||||
- Matrix room: [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com)
|
||||
@ -198,6 +203,7 @@ 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
|
||||
|
||||
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)).
|
||||
|
||||
@ -10,6 +10,7 @@ The playbook automatically determines the target server's architecture (the `mat
|
||||
|
||||
Some tools and container images can be built on the host or other measures can be used to install on that architecture.
|
||||
|
||||
|
||||
## 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).
|
||||
|
||||
@ -5,6 +5,7 @@ This playbook is meant to be run using [Ansible](https://www.ansible.com/).
|
||||
|
||||
Ansible typically runs on your local computer and carries out tasks on a remote server. If your local computer cannot run Ansible, you can also run Ansible on some server somewhere (including the server you wish to install to).
|
||||
|
||||
|
||||
## Supported Ansible versions
|
||||
|
||||
To manually check which version of Ansible you're on, run: `ansible --version`.
|
||||
@ -15,6 +16,7 @@ We're not sure what's the minimum version of Ansible that can run this playbook
|
||||
|
||||
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).
|
||||
|
||||
|
||||
## Upgrading Ansible
|
||||
|
||||
Depending on your distribution, you may be able to upgrade Ansible in a few different ways:
|
||||
@ -25,8 +27,10 @@ Depending on your distribution, you may be able to upgrade Ansible in a few diff
|
||||
|
||||
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.
|
||||
|
||||
|
||||
**Note**: Both of the above methods are a bad way to run system software such as Ansible. If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software.
|
||||
|
||||
|
||||
## 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).
|
||||
@ -35,6 +39,7 @@ This ensures that you're using a very recent Ansible version, which is less like
|
||||
|
||||
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:
|
||||
@ -46,7 +51,7 @@ Once you have a working Docker installation on the server, **clone the playbook*
|
||||
|
||||
You would then need to add `ansible_connection=community.docker.nsenter` to the host line in `inventory/hosts`. This tells Ansible to connect to the "remote" machine by switching Linux namespaces with [nsenter](https://man7.org/linux/man-pages/man1/nsenter.1.html), instead of using SSH.
|
||||
|
||||
Alternatively, you can leave your `inventory/hosts` as is and specify the connection type in **each** `ansible-playbook` call you do later, like this: `ansible-playbook --connection=community.docker.nsenter …`
|
||||
Alternatively, you can leave your `inventory/hosts` as is and specify the connection type in **each** `ansible-playbook` call you do later, like this: `ansible-playbook --connection=community.docker.nsenter ...`
|
||||
|
||||
Run this from the playbook's directory:
|
||||
|
||||
@ -64,7 +69,8 @@ Once you execute the above command, you'll be dropped into a `/work` directory i
|
||||
|
||||
First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
|
||||
|
||||
Finally, you can execute `ansible-playbook …` (or `ansible-playbook --connection=community.docker.nsenter …`) commands as per normal now.
|
||||
Finally, you can execute `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)
|
||||
|
||||
@ -85,20 +91,20 @@ Once you execute the above command, you'll be dropped into a `/work` directory i
|
||||
|
||||
First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
|
||||
|
||||
Finally, you execute `ansible-playbook …` commands as per normal now.
|
||||
Finally, you execute `ansible-playbook ...` commands as per normal now.
|
||||
|
||||
|
||||
#### If you don't use SSH keys for authentication
|
||||
|
||||
If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`).
|
||||
|
||||
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:
|
||||
|
||||
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:
|
||||
```sh
|
||||
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:
|
||||
|
||||
@ -1,7 +1,6 @@
|
||||
(Adapted from the [upstream project](https://github.com/element-hq/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.
|
||||
|
||||
@ -73,22 +73,13 @@ Steps 1 and 2 above only need to be done once, while preparing your [configurati
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
Now that you've [prepared the bot account and room](#account-and-room-preparation), [configured the playbook](#adjusting-the-playbook-configuration), and potentially [adjusted your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
Now that you've [prepared the bot account and room](#account-and-room-preparation), [configured the playbook](#adjusting-the-playbook-configuration), and potentially [adjusted your DNS records](#adjusting-dns-records), you can run the [installation](installing.md) command: `just install-all`
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
Then, you can proceed to [Usage](#usage).
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -16,20 +16,7 @@ matrix_appservice_double_puppet_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -4,6 +4,7 @@ The playbook can install and configure the [Draupnir](https://github.com/the-dra
|
||||
|
||||
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.
|
||||
@ -16,9 +17,10 @@ Normal Draupnir does come with the benefit of access to Synapse Admin features.
|
||||
|
||||
Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
### Create a main management room.
|
||||
### 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.
|
||||
|
||||
@ -29,11 +31,11 @@ This management room is used to control who has access to your D4A deployment. T
|
||||
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.
|
||||
|
||||
### Give your main management room an alias.
|
||||
### 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.
|
||||
|
||||
### Adjusting the playbook configuration.
|
||||
### 3. Adjusting the playbook configuration.
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
|
||||
@ -45,22 +47,14 @@ matrix_appservice_draupnir_for_all_enabled: true
|
||||
matrix_appservice_draupnir_for_all_master_control_room_alias: "ALIAS_FROM_STEP_2_GOES_HERE"
|
||||
```
|
||||
|
||||
### Installing
|
||||
### 4. Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
## Usage
|
||||
|
||||
@ -68,7 +62,7 @@ If you made it through all the steps above and your main control room was joined
|
||||
|
||||
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.
|
||||
|
||||
### Granting Users the ability to use D4A
|
||||
### 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.
|
||||
|
||||
@ -76,7 +70,7 @@ The bot requires a powerlevel of 50 in the management room to control who is all
|
||||
|
||||
To allow users or whole homeservers you type /plain @draupnir-main:example.com allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
|
||||
|
||||
### How to provision a D4A once you are allowed to.
|
||||
### 2. How to provision a D4A once you are allowed to.
|
||||
|
||||
Open a DM with @draupnir-main:example.com and if using an Element client 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.
|
||||
|
||||
|
||||
@ -71,17 +71,12 @@ Check the [backup_borg role](https://github.com/mother-of-all-self-hosting/ansib
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Manually start a backup
|
||||
|
||||
For testing your setup it can be helpful to not wait until 4am. If you want to run the backup immediately, log onto the server and run `systemctl start matrix-backup-borg`. This will not return until the backup is done, so possibly a long time. Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.
|
||||
|
||||
@ -33,6 +33,7 @@ Doing this, the playbook will:
|
||||
|
||||
- serve a simple homepage at `https://example.com` with content `Hello from example.com` (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).
|
||||
|
||||
|
||||
## 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.
|
||||
@ -55,6 +56,7 @@ With this configuration, Ansible will no longer mess around with the `/matrix/st
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@ -11,10 +11,12 @@ It supports [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/ch
|
||||
|
||||
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**:
|
||||
@ -28,6 +30,7 @@ There are **a lot of configuration options** (some required, some possibly requi
|
||||
|
||||
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.example.com/vars.yml` file:
|
||||
@ -70,6 +73,7 @@ matrix_bot_baibot_config_persistence_config_encryption_key: 'A_HEX_STRING_OF_64_
|
||||
|
||||
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).
|
||||
@ -135,6 +139,7 @@ Depending on your propensity for [GitOps](https://en.wikipedia.org/wiki/DevOps#G
|
||||
|
||||
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.
|
||||
@ -161,6 +166,7 @@ If you'd like to use more than one model, take a look at the [Configuring additi
|
||||
|
||||
💡 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.
|
||||
@ -194,6 +200,7 @@ If you'd like to use more than one model, take a look at the [Configuring additi
|
||||
|
||||
💡 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.
|
||||
@ -222,6 +229,7 @@ If you'd like to use more than one model, take a look at the [Configuring additi
|
||||
|
||||
💡 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.
|
||||
@ -252,6 +260,7 @@ If you'd like to use more than one model, take a look at the [Configuring additi
|
||||
|
||||
💡 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.
|
||||
@ -262,6 +271,7 @@ Some of these popular services already have **shortcut** providers (see [support
|
||||
|
||||
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.
|
||||
@ -317,6 +327,7 @@ As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.
|
||||
|
||||
💡 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**).
|
||||
@ -362,24 +373,21 @@ 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 it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
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.
|
||||
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
- 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
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_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
|
||||
|
||||
@ -395,6 +403,7 @@ Send `!bai help` to the room at any time to see the bot's help menu for addition
|
||||
|
||||
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`
|
||||
|
||||
@ -56,22 +56,18 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
- 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
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_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.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ The playbook can install and configure [matrix-chatgpt-bot](https://github.com/m
|
||||
|
||||
Talk to [ChatGPT](https://openai.com/blog/chatgpt/) via your favourite Matrix client!
|
||||
|
||||
## Register the bot account
|
||||
## 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.
|
||||
|
||||
@ -20,13 +20,15 @@ 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
|
||||
```
|
||||
|
||||
## Get an access token and create encryption keys
|
||||
|
||||
## 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).
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
## 3. Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
|
||||
@ -51,22 +53,15 @@ matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a
|
||||
|
||||
You will need to get tokens for ChatGPT.
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
## 4. Installing
|
||||
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -6,9 +6,10 @@ See the project's [documentation](https://github.com/the-draupnir-project/Draupn
|
||||
|
||||
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.
|
||||
|
||||
## Register the bot account
|
||||
## 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.
|
||||
|
||||
@ -24,11 +25,13 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupni
|
||||
|
||||
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.
|
||||
|
||||
## Get an access token
|
||||
|
||||
## 2. Get an access token
|
||||
|
||||
Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
|
||||
|
||||
## Make sure the account is free from rate limiting
|
||||
|
||||
## 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.
|
||||
|
||||
@ -36,7 +39,9 @@ If your Synapse Admin API is exposed to the internet for some reason like runnin
|
||||
|
||||
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 itself. If you made Draupnir Admin you can just use the Draupnir token.
|
||||
|
||||
## Create a management room
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@ -46,11 +51,12 @@ Once you have created the room you need to copy the room ID so you can tell the
|
||||
|
||||
Finally invite the `@bot.draupnir:example.com` account you created earlier into the room.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
## 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).
|
||||
|
||||
### a. Configuration with E2EE support
|
||||
### 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.
|
||||
|
||||
@ -85,13 +91,13 @@ matrix_bot_draupnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matr
|
||||
matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
|
||||
```
|
||||
|
||||
### b. Configuration without E2EE support
|
||||
### 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.example.com/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 your own values.
|
||||
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
|
||||
@ -101,30 +107,20 @@ matrix_bot_draupnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
|
||||
matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
|
||||
```
|
||||
|
||||
### c. Migrating from Mjolnir (Only required if migrating.)
|
||||
### 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.
|
||||
|
||||
## Installing
|
||||
## 6. Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the Pantalaimon's password (`matrix_bot_draupnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_draupnir_pantalaimon_password` to let Pantalaimon know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
@ -194,6 +190,7 @@ To **enable a given protection**, send a command like this: `!draupnir enable PR
|
||||
|
||||
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.example.com/vars.yml` file.
|
||||
|
||||
@ -8,6 +8,7 @@ Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the ori
|
||||
|
||||
See the project's [documentation](https://github.com/matrix-org/go-neb) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
||||
## Registering the bot user
|
||||
|
||||
The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver.
|
||||
@ -24,6 +25,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb
|
||||
|
||||
Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Go-NEB, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -217,20 +219,12 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -6,6 +6,7 @@ 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.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Honoroit, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -47,22 +48,18 @@ If you've decided to use the default hostname, you won't need to do any extra DN
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
- 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
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_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.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -6,6 +6,7 @@ The bot allows you to easily **create and manage registration tokens** aka. invi
|
||||
|
||||
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
|
||||
|
||||
To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -31,22 +32,7 @@ The bot account will be created automatically.
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_matrix_registration_bot_bot_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_registration_bot_bot_password` to let the bot know its new password.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
@ -58,7 +44,7 @@ You can also refer to the upstream [Usage documentation](https://github.com/moan
|
||||
|
||||
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 method from access_token to password etc… you can use:
|
||||
To clean the cache (session & encryption data) after you changed the bot's username, changed the login method from access_token to password etc... you can use:
|
||||
|
||||
```sh
|
||||
just run-tags bot-matrix-registration-bot-clean-cache
|
||||
|
||||
@ -6,6 +6,7 @@ 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.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -23,24 +24,21 @@ matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT
|
||||
matrix_bot_matrix_reminder_bot_reminders_timezone: Europe/London
|
||||
```
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
- 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
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_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.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -49,22 +49,11 @@ If you've decided to use the default hostname, you won't need to do any extra DN
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all`
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- 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, and then update `matrix_bot_maubot_initial_password` to let the bot know its new password.
|
||||
- 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, and then update `matrix_bot_maubot_initial_password` to let the bot know its new password
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -4,7 +4,8 @@ The playbook can install and configure the [Mjolnir](https://github.com/matrix-o
|
||||
|
||||
See the project's [documentation](https://github.com/matrix-org/mjolnir) to learn what it does and why it might be useful to you.
|
||||
|
||||
## Register the bot account
|
||||
|
||||
## 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.
|
||||
|
||||
@ -20,11 +21,13 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.mjolnir
|
||||
|
||||
If you would like Mjolnir to be able to deactivate users, move aliases, shutdown rooms, etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
|
||||
|
||||
## Get an access token
|
||||
|
||||
## 2. Get an access token
|
||||
|
||||
Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
|
||||
|
||||
## Make sure the account is free from rate limiting
|
||||
|
||||
## 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.
|
||||
|
||||
@ -32,7 +35,7 @@ If your Synapse Admin API is exposed to the internet for some reason like runnin
|
||||
|
||||
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 itself. If you made Mjolnir Admin you can just use the Mjolnir token.
|
||||
|
||||
## Create a management room
|
||||
## 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.
|
||||
|
||||
@ -42,11 +45,12 @@ Once you have created the room you need to copy the room ID so you can tell the
|
||||
|
||||
Finally invite the `@bot.mjolnir:example.com` account you created earlier into the room.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
## 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).
|
||||
|
||||
### a. Configuration with E2EE support
|
||||
### 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.
|
||||
|
||||
@ -81,13 +85,13 @@ matrix_bot_mjolnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matri
|
||||
matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
|
||||
```
|
||||
|
||||
### b. Configuration without E2EE support
|
||||
### 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.example.com/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 your own values.
|
||||
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_mjolnir_enabled: true
|
||||
@ -97,10 +101,11 @@ matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
|
||||
matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
|
||||
```
|
||||
|
||||
## Adding Mjolnir synapse antispam module (optional)
|
||||
## 6. Adding Mjolnir synapse antispam module (optional)
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
|
||||
|
||||
```yaml
|
||||
matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled: true
|
||||
matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_invites: true
|
||||
@ -109,24 +114,15 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_usernames: false
|
||||
matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
|
||||
```
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
## 7. Installing
|
||||
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the Pantalaimon's password (`matrix_bot_mjolnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_mjolnir_pantalaimon_password` to let Pantalaimon know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -8,46 +8,38 @@ The playbook can install and configure [matrix-appservice-discord](https://githu
|
||||
|
||||
See the project's [documentation](https://github.com/matrix-org/matrix-appservice-discord/blob/master/README.md) to learn what it does and why it might be useful to you.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Create a Discord Application [here](https://discordapp.com/developers/applications). Then retrieve Client ID, and create a bot from the Bot tab and retrieve the Bot token.
|
||||
## Setup Instructions
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
Instructions loosely based on [this](https://github.com/matrix-org/matrix-appservice-discord#setting-up).
|
||||
|
||||
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
1. Create a Discord Application [here](https://discordapp.com/developers/applications).
|
||||
2. Retrieve Client ID.
|
||||
3. Create a bot from the Bot tab and retrieve the Bot token.
|
||||
4. Enable the bridge with the following configuration in your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
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"
|
||||
```yaml
|
||||
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"
|
||||
```
|
||||
|
||||
# As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
|
||||
# Note: This deprecated method is considered insecure.
|
||||
#
|
||||
# matrix_synapse_configuration_extension_yaml: |
|
||||
# use_appservice_legacy_authorization: true
|
||||
```
|
||||
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:
|
||||
|
||||
## Installing
|
||||
```yaml
|
||||
matrix_synapse_configuration_extension_yaml: |
|
||||
use_appservice_legacy_authorization: true
|
||||
```
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
**Note**: This deprecated method is considered insecure.
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
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.
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
Other configuration options are available via the `matrix_appservice_discord_configuration_extension_yaml` variable.
|
||||
|
||||
## Self-Service Bridging (Manual)
|
||||
|
||||
Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. To enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. This is disabled by default, so it must be enabled by adding this to your `vars.yml`:
|
||||
|
||||
```yaml
|
||||
matrix_appservice_discord_bridge_enableSelfServiceBridging: true
|
||||
@ -55,32 +47,27 @@ matrix_appservice_discord_bridge_enableSelfServiceBridging: true
|
||||
|
||||
**Note**: If self-service bridging is not enabled, `!discord help` commands will return no results.
|
||||
|
||||
### Usage
|
||||
Once self-service is enabled:
|
||||
|
||||
Once self-service is enabled, start a chat with `@_discord_bot:example.com` and say `!discord help bridge`.
|
||||
|
||||
Then, follow the instructions in the help output message.
|
||||
|
||||
If the bot is not already in the Discord server, follow the provided invite link. This may require you to be a administrator of the Discord server.
|
||||
|
||||
On the Discord side, you can say `!matrix help` to get a list of available commands to manage the bridge and Matrix users.
|
||||
1. Start a chat with `@_discord_bot:example.com` and say `!discord help bridge`.
|
||||
2. Follow the instructions in the help output message. If the bot is not already in the Discord server, follow the provided invite link. This may require you to be a administrator of the Discord server.
|
||||
|
||||
**Note**: Encrypted Matrix rooms are not supported as of writing.
|
||||
|
||||
On the Discord side, you can say `!matrix help` to get a list of available commands to manage the bridge and Matrix users.
|
||||
|
||||
## Portal Bridging (Automatic)
|
||||
|
||||
Through portal bridging, Matrix rooms will automatically be created by the bot and bridged to the relevant Discord room. This is done by simply joining a room with a specific name pattern (`#_discord_<guildID>_<channelID>`).
|
||||
|
||||
All Matrix rooms created this way are **listed publicly** by default, and you will not have admin permissions to change this. To get more control, [make yourself a room Administrator](#getting-administrator-access-in-a-portal-bridged-room). You can then unlist the room from the directory and change the join rules.
|
||||
|
||||
To disable portal bridging, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
If you want to disable portal bridging, set the following in `vars.yml`:
|
||||
|
||||
```yaml
|
||||
matrix_appservice_discord_bridge_disablePortalBridging: true
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
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).
|
||||
|
||||
@ -62,20 +62,7 @@ matrix_appservice_irc_ircService_servers:
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
The playbook can install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) for you. `matrix-appservice-kakaotalk` is a bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code.
|
||||
|
||||
⚠️ **Warning**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
|
||||
**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.
|
||||
|
||||
@ -33,21 +33,12 @@ Take a look at:
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
## Usage
|
||||
|
||||
Start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
|
||||
@ -2,94 +2,92 @@
|
||||
|
||||
**Notes**:
|
||||
- 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.
|
||||
- Currently (as of November, 2024) **this component is not available for new installation unless you have already created a classic Slack application** (which the bridge makes use of in order to enable bridging between Slack and Matrix), because the creation of classic Slack applications has been discontinued since June 4 2024. The author of the bridge claims [here](https://github.com/matrix-org/matrix-appservice-slack/issues/789#issuecomment-2172947787) that he plans to support the modern Slack application and until then "the best (and only) option for new installations is to use the webhook bridging".
|
||||
- Currently (as of November, 2024) this component is not available for new installation unless you have already created a classic Slack application (which the bridge makes use of in order to enable bridging between Slack and Matrix), because the creation of classic Slack applications has been discontinued since June 4 2024. The author of the bridge claims [here](https://github.com/matrix-org/matrix-appservice-slack/issues/789#issuecomment-2172947787) that he plans to support the modern Slack application and until then "the best (and only) option for new installations is to use the webhook bridging".
|
||||
|
||||
The playbook can install and configure [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) for you.
|
||||
|
||||
See the project's [documentation](https://github.com/matrix-org/matrix-appservice-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
|
||||
|
||||
## Prerequisites
|
||||
## Setup Instructions:
|
||||
|
||||
### Create a Classic Slack App
|
||||
loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Setup)
|
||||
|
||||
First, you need to create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
|
||||
1. Create a new Matrix room to act as the administration control room. Note its internal room ID. This can be done in Element Web by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top.
|
||||
|
||||
Name the app "matrixbot" (or anything else you'll remember). Select the team/workspace this app will belong to. Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
|
||||
2. Enable the bridge by adding the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
Then, click on Event Subscriptions and enable them and use the request url: `https://matrix.example.com/appservice-slack`.
|
||||
```yaml
|
||||
matrix_appservice_slack_enabled: true
|
||||
matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
|
||||
```
|
||||
|
||||
Add the following events as `Bot User Events` and save:
|
||||
3. Enable puppeting (optional, but recommended)
|
||||
|
||||
- team_domain_change
|
||||
- message.channels
|
||||
- message.groups (if you want to bridge private channels)
|
||||
- reaction_added
|
||||
- reaction_removed
|
||||
```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"
|
||||
```
|
||||
|
||||
Next, click on "OAuth & Permissions" and add the following scopes:
|
||||
4. Enable Team Sync (optional)
|
||||
|
||||
- chat:write:bot
|
||||
- users:read
|
||||
- reactions:write
|
||||
- files:write:user (if you want to bridge files)
|
||||
```yaml
|
||||
matrix_appservice_slack_team_sync_enabled: true
|
||||
```
|
||||
|
||||
**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.
|
||||
See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### Create an administration control room on Matrix
|
||||
6. Invite the bridge bot user into the admin room:
|
||||
|
||||
Create a new Matrix room to act as the administration control room.
|
||||
```
|
||||
/invite @slackbot:example.com
|
||||
```
|
||||
|
||||
Note its internal room ID. This can be done in Element Web by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top.
|
||||
Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
7. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
|
||||
|
||||
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
Name the app "matrixbot" (or anything else you'll remember).
|
||||
|
||||
```yaml
|
||||
matrix_appservice_slack_enabled: true
|
||||
matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
|
||||
Select the team/workspace this app will belong to.
|
||||
|
||||
# Uncomment to enable puppeting (optional, but recommended)
|
||||
# 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"
|
||||
Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
|
||||
|
||||
# Uncomment to enable Team Sync (optional)
|
||||
# See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
|
||||
# matrix_appservice_slack_team_sync_enabled: true
|
||||
```
|
||||
8. Click on Event Subscriptions and enable them and use the request url `https://matrix.example.com/appservice-slack`. Then add the following events and save:
|
||||
|
||||
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
|
||||
Bot User Events:
|
||||
|
||||
## Installing
|
||||
- team_domain_change
|
||||
- message.channels
|
||||
- message.groups (if you want to bridge private channels)
|
||||
- reaction_added
|
||||
- reaction_removed
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
9. Click on OAuth & Permissions and add the following scopes:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
- chat:write:bot
|
||||
- users:read
|
||||
- reactions:write
|
||||
|
||||
**Notes**:
|
||||
If you want to bridge files, also add the following:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
- files:write:user
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
**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.
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
10. 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.
|
||||
|
||||
## Usage
|
||||
11. If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
|
||||
|
||||
Send `/invite @slackbot:example.com` to invite the bridge bot user into the admin room.
|
||||
* Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like !qporfwt:example.com.
|
||||
|
||||
If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
|
||||
* Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:example.com` for Matrix.
|
||||
|
||||
- Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like `!qporfwt:example.com`.
|
||||
- Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:example.com` for Matrix.
|
||||
- Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel ID>/details/`.
|
||||
- Issue a link command in the administration control room with these collected values as arguments:
|
||||
* Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel ID>/details/`.
|
||||
|
||||
* Issue a link command in the administration control room with these collected values as arguments:
|
||||
|
||||
with file bridging:
|
||||
|
||||
@ -109,28 +107,30 @@ If Team Sync is not enabled, for each channel you would like to bridge, perform
|
||||
link -I CHANNELID -R !qporfwt:example.com -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
### Unlinking
|
||||
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
|
||||
|
||||
Channels can be unlinked again by sending this:
|
||||
12. Unlinking
|
||||
|
||||
```
|
||||
unlink --room !qporfwt:example.com
|
||||
```
|
||||
Channels can be unlinked again like this:
|
||||
|
||||
Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged Matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
|
||||
```
|
||||
unlink --room !qporfwt:example.com
|
||||
```
|
||||
|
||||
Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged Matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
As always, check the logs: `journalctl -fu matrix-appservice-slack`
|
||||
* As always, check the logs: `journalctl -fu matrix-appservice-slack`
|
||||
|
||||
### Linking: "Room is now pending-name"
|
||||
* Linking: "Room is now pending-name"
|
||||
|
||||
This typically means that you haven't used the correct Slack channel ID. Unlink the room and recheck 'Determine the "channel ID"' from above.
|
||||
This typically means that you haven't used the correct Slack channel ID. Unlink the room and recheck 'Determine the "channel ID"' from above.
|
||||
|
||||
### Messages work from Matrix to Slack, but not the other way around
|
||||
* Messages work from M to S, but not the other way around
|
||||
|
||||
Check you logs, if they say something like
|
||||
Check you logs, if they say something like
|
||||
|
||||
`WARN SlackEventHandler Ignoring message from unrecognised Slack channel ID : %s (%s) <the channel ID> <some other ID>`
|
||||
`WARN SlackEventHandler Ignoring message from unrecognised Slack channel ID : %s (%s) <the channel ID> <some other ID>`
|
||||
|
||||
then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.
|
||||
then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.
|
||||
|
||||
@ -4,84 +4,70 @@
|
||||
|
||||
The playbook can install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) for you. This bridge provides support for Slack-compatible webhooks.
|
||||
|
||||
See the project's [documentation](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md) to learn what it does and why it might be useful to you.
|
||||
Setup Instructions:
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
loosely based on [this](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md)
|
||||
|
||||
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
1. Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_appservice_webhooks_enabled: true
|
||||
matrix_appservice_webhooks_api_secret: '<your_secret>'
|
||||
```yaml
|
||||
matrix_appservice_webhooks_enabled: true
|
||||
matrix_appservice_webhooks_api_secret: '<your_secret>'
|
||||
```
|
||||
|
||||
# Uncomment to increase the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
|
||||
# matrix_appservice_webhooks_log_level: 'verbose'
|
||||
2. In case you want to change the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service` you can adjust this in `inventory/host_vars/matrix.example.com/vars.yml` as well.
|
||||
|
||||
# As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
|
||||
# Note: This deprecated method is considered insecure.
|
||||
#
|
||||
# matrix_synapse_configuration_extension_yaml: |
|
||||
# use_appservice_legacy_authorization: true
|
||||
```
|
||||
**Note**: default value is: `info` and availabe log levels are : `info`, `verbose`
|
||||
|
||||
## Installing
|
||||
```yaml
|
||||
matrix_appservice_webhooks_log_level: '<log_level>'
|
||||
```
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
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:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
```yaml
|
||||
matrix_synapse_configuration_extension_yaml: |
|
||||
use_appservice_legacy_authorization: true
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
**Note**: This deprecated method is considered insecure.
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
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.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
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.
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
6. Invite the bridge bot user to your room:
|
||||
|
||||
## Usage
|
||||
- either with `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
|
||||
|
||||
Invite the bridge bot user to your room in either way.
|
||||
- or simply add the bridge bot to a private channel (personal channels imply you being an administrator)
|
||||
|
||||
- Send `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
|
||||
- Add the bridge bot to a private channel (personal channels imply you being an administrator)
|
||||
7. Send a message to the bridge bot in order to receive a private message including the webhook link.
|
||||
|
||||
You then need to send a message to the bridge bot in order to receive a private message including the webhook link:
|
||||
```
|
||||
!webhook
|
||||
```
|
||||
|
||||
```
|
||||
!webhook
|
||||
```
|
||||
8. The JSON body for posting messages will have to look like this:
|
||||
|
||||
The JSON body for posting messages will have to look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
```json
|
||||
{
|
||||
"text": "Hello world!",
|
||||
"format": "plain",
|
||||
"displayName": "My Cool Webhook",
|
||||
"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
You can test this via curl like so:
|
||||
You can test this via curl like so:
|
||||
|
||||
```sh
|
||||
curl --header "Content-Type: application/json" \
|
||||
--data '{
|
||||
"text": "Hello world!",
|
||||
"format": "plain",
|
||||
"displayName": "My Cool Webhook",
|
||||
"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
|
||||
}' \
|
||||
<the webhook link you've gotten from the bridge bot>
|
||||
```
|
||||
|
||||
### Setting Webhooks with Dimension integration manager
|
||||
|
||||
If you're using the [Dimension integration manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge with it.
|
||||
|
||||
To configure it, open the Dimension integration manager, and go to "Settings" and "Bridges", then select edit action for "Webhook Bridge".
|
||||
|
||||
On the UI, press "Add self-hosted Bridge" button and populate "Provisioning URL" and "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.
|
||||
```sh
|
||||
curl --header "Content-Type: application/json" \
|
||||
--data '{
|
||||
"text": "Hello world!",
|
||||
"format": "plain",
|
||||
"displayName": "My Cool Webhook",
|
||||
"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
|
||||
}' \
|
||||
<the link you've gotten in 5.>
|
||||
```
|
||||
|
||||
@ -15,14 +15,15 @@ matrix_beeper_linkedin_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_beeper_linkedin_bridge_encryption_allow: true
|
||||
matrix_beeper_linkedin_bridge_encryption_default: true
|
||||
matrix_beeper_linkedin_configuration_extension_yaml: |
|
||||
bridge:
|
||||
encryption:
|
||||
allow: true
|
||||
default: true
|
||||
```
|
||||
|
||||
If you would like to be able to administrate the bridge from your account it can be configured like this:
|
||||
|
||||
```yaml
|
||||
matrix_beeper_linkedin_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -34,20 +35,7 @@ You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/co
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Set up Double Puppeting by enabling Appservice Double Puppet or Shared Secret Auth
|
||||
|
||||
@ -57,6 +45,7 @@ Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppe
|
||||
|
||||
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
You then need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
@ -67,6 +56,7 @@ If you run into trouble, check the [Troubleshooting](#troubleshooting) section b
|
||||
|
||||
After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting-by-enabling-appservice-double-puppet-or-shared-secret-auth), if you haven't already done so.
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bridge asking for 2FA even if you don't have 2FA enabled
|
||||
|
||||
@ -14,20 +14,7 @@ matrix_go_skype_bridge_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -49,20 +49,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -8,6 +8,7 @@ See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/l
|
||||
|
||||
**Note**: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however was deprecated by its author.
|
||||
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) to learn what the individual options do.
|
||||
@ -24,9 +25,9 @@ Finally, run the playbook (see [installing](installing.md)).
|
||||
|
||||
### End-to-bridge encryption
|
||||
|
||||
You can enable [encryption](https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html) for Hookshot by adding `matrix_hookshot_encryption_enabled: true` to your configuration (`vars.yml`) and [executing the playbook](installing.md) again.
|
||||
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 --tags=reset-hookshot-encryption`.
|
||||
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
|
||||
|
||||
@ -40,6 +41,7 @@ Refer to [Hookshot's documentation](https://matrix-org.github.io/matrix-hookshot
|
||||
|
||||
**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
|
||||
|
||||
### URLs for bridges setup
|
||||
@ -70,7 +72,6 @@ The GitHub bridge requires you to install a private key file. This can be done i
|
||||
- use the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) to copy the file from an arbitrary path on your ansible client to the correct path on the server.
|
||||
|
||||
To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following additional configuration:
|
||||
|
||||
```yaml
|
||||
aux_file_definitions:
|
||||
- dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
|
||||
@ -79,7 +80,6 @@ aux_file_definitions:
|
||||
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).
|
||||
|
||||
### Provisioning API
|
||||
|
||||
@ -33,20 +33,7 @@ matrix_sms_bridge_provider_android_truststore_password: 123
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -8,6 +8,7 @@ The playbook can install and configure [mautrix-discord](https://github.com/maut
|
||||
|
||||
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).
|
||||
@ -41,21 +42,12 @@ Take a look at:
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
## Usage
|
||||
|
||||
### Logging in
|
||||
@ -75,7 +67,7 @@ To acquire the token, open Discord in a private browser window. Then open the de
|
||||
1. Start a chat with `@discordbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
2. If you would like to login to Discord using a token, send `login-token` command, otherwise, send `login-qr` command.
|
||||
3. You'll see a QR code which you need to scan with the Discord app on your phone. You can scan it with the camera app too, which will open Discord, which will then instruct you to scan it a 2nd time in the Discord app.
|
||||
4. After confirming (in the Discord app) that you'd like to allow this login, the bot should respond with "Succcessfully authenticated as …"
|
||||
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:
|
||||
|
||||
@ -23,7 +23,6 @@ matrix_mautrix_facebook_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_facebook_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -33,7 +32,6 @@ matrix_mautrix_facebook_configuration_extension_yaml: |
|
||||
```
|
||||
|
||||
If you would like to be able to administrate the bridge from your account it can be configured like this:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_facebook_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -57,20 +55,7 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-facebook/templates/c
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -20,20 +20,7 @@ matrix_mautrix_gmessages_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -20,20 +20,7 @@ matrix_mautrix_googlechat_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
@ -61,6 +48,7 @@ Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppe
|
||||
|
||||
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
|
||||
|
||||
|
||||
#### Method 2: manually, by asking each user to provide a working access token
|
||||
|
||||
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
|
||||
|
||||
@ -22,20 +22,7 @@ matrix_mautrix_hangouts_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -17,7 +17,6 @@ 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:
|
||||
@ -27,7 +26,6 @@ matrix_mautrix_instagram_configuration_extension_yaml: |
|
||||
```
|
||||
|
||||
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 }}"
|
||||
@ -44,20 +42,7 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-instagram/templates/
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -48,7 +48,6 @@ Different levels of permission can be granted to users:
|
||||
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
|
||||
@ -69,20 +68,7 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templ
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -48,6 +48,7 @@ You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variab
|
||||
|
||||
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.
|
||||
@ -61,7 +62,6 @@ Different levels of permission can be granted to users:
|
||||
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
|
||||
@ -82,20 +82,7 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templ
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -41,7 +41,6 @@ Different levels of permission can be granted to users:
|
||||
The permissions are following the sequence: nothing < relay < user < admin.
|
||||
|
||||
The default permissions are set as follows:
|
||||
|
||||
```yaml
|
||||
permissions:
|
||||
'*': relay
|
||||
@ -49,7 +48,6 @@ permissions:
|
||||
```
|
||||
|
||||
If you want to augment the preset permissions, you might want to set the additional permissions with the following settings in your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_signal_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -60,7 +58,6 @@ matrix_mautrix_signal_configuration_extension_yaml: |
|
||||
This will add the admin permission to the specific user, while keeping the default permissions.
|
||||
|
||||
In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_signal_bridge_permissions:
|
||||
'@ADMIN:example.com': admin
|
||||
@ -71,20 +68,7 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/con
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -10,6 +10,7 @@ See the project's [documentation](https://docs.mau.fi/bridges/go/slack/index.htm
|
||||
|
||||
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).
|
||||
@ -43,21 +44,12 @@ Take a look at:
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Start a chat with `@slackbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
|
||||
@ -22,20 +22,7 @@ matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
@ -52,7 +39,6 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
|
||||
```
|
||||
|
||||
You might also want to give permissions to administrate the bot:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_telegram_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -63,7 +49,6 @@ 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
|
||||
```
|
||||
|
||||
@ -22,20 +22,7 @@ matrix_mautrix_twitter_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -36,20 +36,7 @@ If you want to activate the relay bot in a room, send `!wa set-relay`. To deacti
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -41,20 +41,7 @@ By default, you will need to create a CNAME record for `wsproxy`. See [Configuri
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -18,20 +18,7 @@ matrix_mx_puppet_discord_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -14,20 +14,7 @@ matrix_mx_puppet_groupme_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -14,20 +14,7 @@ matrix_mx_puppet_instagram_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -23,21 +23,12 @@ matrix_mx_puppet_slack_oauth_client_secret: "<SLACK_APP_CLIENT_SECRET>"
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
## Usage
|
||||
|
||||
Once the bot is enabled you need to start a chat with `Slack Puppet Bridge` with the handle `@_slackpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
|
||||
@ -14,20 +14,7 @@ matrix_mx_puppet_steam_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -25,20 +25,7 @@ matrix_mx_puppet_twitter_environment: ''
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -19,6 +19,7 @@ If you don't open these ports, you will still be able to send emails, but not re
|
||||
|
||||
These port numbers are configurable via the `matrix_postmoogle_smtp_host_bind_port` and `matrix_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -48,22 +49,18 @@ You will also need to add several DNS records so that Postmoogle can send emails
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create a user account of the bridge's bot.
|
||||
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create a user account of the bridge's bot
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
- if you change the bridge's bot password (`matrix_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_postmoogle_password` to let the bot know its new password
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bridge's bot password (`matrix_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_postmoogle_password` to let the bot know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -14,20 +14,7 @@ matrix_wechat_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -63,20 +63,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -8,6 +8,7 @@ Cinny is a web client focusing primarily on simple, elegant and secure interface
|
||||
|
||||
- [app.cinny.in](https://app.cinny.in), hosted by the [Cinny](https://cinny.in/) developers
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -41,13 +42,4 @@ If you've adjusted `matrix_client_cinny_hostname`, you will need to adjust your
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook and [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -7,6 +7,7 @@ By default, this playbook installs the [Element Web](https://github.com/element-
|
||||
- [app.element.io](https://app.element.io/), hosted by [Element](https://element.io/)
|
||||
- [app.etke.cc](https://app.etke.cc/), hosted by [etke.cc](https://etke.cc/)
|
||||
|
||||
|
||||
## Disabling Element Web
|
||||
|
||||
If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -15,6 +16,7 @@ If you'd like for the playbook to not install Element Web (or to uninstall it if
|
||||
matrix_client_element_enabled: false
|
||||
```
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
The playbook provides some customization variables you could use to change Element Web's settings.
|
||||
@ -31,6 +33,7 @@ Alternatively, **if there is no pre-defined variable** for an Element Web settin
|
||||
|
||||
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
|
||||
|
||||
|
||||
### Themes
|
||||
|
||||
To change the look of Element Web, you can define your own themes manually by using the `matrix_client_element_setting_defaults_custom_themes` setting.
|
||||
@ -68,13 +71,4 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -39,13 +39,4 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -8,6 +8,8 @@ SchildiChat Web is a feature-rich messenger for Matrix based on Element Web with
|
||||
|
||||
- [app.schildi.chat](https://app.schildi.chat/), hosted by the [SchildiChat](https://schildi.chat/) developers
|
||||
|
||||
**WARNING**: SchildiChat Web is based on Element Web, but its releases are lagging behind. As of 2024-11, SchildiChat Web is many releases behind (it being based on Element Web `v1.11.36`, while Element Web is now on `v1.11.85`). Element Web frequently suffers from security issues (see [here](https://github.com/element-hq/element-web/security) for known issues), so running something based on an ancient Element Web release is **unsafe**. Use SchildiChat Web at your own risk!
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable SchildiChat Web, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -67,13 +69,4 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -27,6 +27,7 @@ Since it is difficult to create the first user account on Conduit (see [famedly/
|
||||
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.
|
||||
@ -35,6 +36,7 @@ You will have to manually register appservices using the the [register-appservic
|
||||
|
||||
Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`, then pass the content to Conduit:
|
||||
|
||||
|
||||
@conduit:example.com: register-appservice
|
||||
```
|
||||
as_token: <token>
|
||||
|
||||
@ -30,15 +30,8 @@ Alternatively, **if there is no pre-defined variable** for a Dendrite setting yo
|
||||
|
||||
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_dendrite_configuration` (or `matrix_dendrite_configuration_yaml`). You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
|
||||
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -69,20 +69,14 @@ By default, you will need to create a CNAME record for `dimension`. See [Configu
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
After Dimension has been installed you may need to log out and log back in for it to pick up the new integration manager. Then you can access integrations in Element Web by opening a room, clicking the Room info button (`i`) button in the top right corner of the screen, and then clicking Add widgets, bridges & bots.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
- After Dimension has been installed you may need to log out and log back in for it to pick up the new integration manager. Then you can access integrations in Element Web by opening a room, clicking the Room info button (`i`) button in the top right corner of the screen, and then clicking Add widgets, bridges & bots.
|
||||
|
||||
## Jitsi domain
|
||||
|
||||
@ -90,6 +84,7 @@ By default Dimension will use [jitsi.riot.im](https://jitsi.riot.im/) as the `co
|
||||
|
||||
In the interim until the above limitation is resolved, an admin user needs to configure the domain via the admin ui once dimension is running. In Element Web, go to *Manage Integrations* → *Settings* → *Widgets* → *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@ -25,16 +25,7 @@ matrix_dynamic_dns_domain_configurations:
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Additional Reading
|
||||
|
||||
|
||||
@ -10,10 +10,12 @@ By default, emails are sent from `matrix@matrix.example.com`, as specified by th
|
||||
|
||||
💡 To improve deliverability, we recommend [relaying email through another SMTP server](#relaying-email-through-another-smtp-server) anyway.
|
||||
|
||||
|
||||
## Firewall settings
|
||||
|
||||
No matter whether you send email directly (the default) or you relay email through another host (see how below), you'll probably need to allow outgoing traffic for TCP ports 25/587 (depending on configuration).
|
||||
|
||||
|
||||
## Relaying email through another SMTP server
|
||||
|
||||
If you'd like to relay email through another SMTP server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
@ -30,8 +32,8 @@ exim_relay_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
|
||||
|
||||
### 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`.
|
||||
|
||||
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`.
|
||||
|
||||
@ -6,6 +6,7 @@ The playbook can install and configure [email2matrix](https://github.com/devture
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Preparation
|
||||
|
||||
### DNS configuration
|
||||
@ -82,16 +83,6 @@ Refer to the official documentation [here](https://github.com/devture/email2matr
|
||||
|
||||
## Installing
|
||||
|
||||
To enable Email2Matrix, run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
To enable Email2Matrix, run the [installation](installing.md) command (`--tags=setup-email2matrix,start`).
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-email2matrix,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just run-tags setup-email2matrix,start` or `just setup-all`
|
||||
|
||||
`just run-tags setup-email2matrix,start` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
|
||||
|
||||
- After installation, you may wish to send a test email to the email address assigned to `mailbox1` (default: `mailbox1@matrix.example.com`) to make sure that Email2Matrix works as expected.
|
||||
After installation, you may wish to send a test email to the email address assigned to `mailbox1` (default: `mailbox1@matrix.example.com`) to make sure that Email2Matrix works as expected.
|
||||
|
||||
@ -33,6 +33,7 @@ etherpad_hostname: "{{ matrix_server_fqn_matrix }}"
|
||||
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.
|
||||
@ -43,22 +44,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the Etherpad admin user (`etherpad_admin_username`).
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the Etherpad admin user's password (`etherpad_admin_password` in your `vars.yml` file) subsequently, the admin user's credentials on the homeserver won't be updated automatically. If you'd like to change the admin user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `etherpad_admin_password` to let the admin user know its new password.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Usage
|
||||
|
||||
@ -66,30 +52,35 @@ The Etherpad UI should be available at `https://etherpad.example.com`, while the
|
||||
|
||||
If you've [decided on another hostname or path-prefix](#adjusting-the-etherpad-url) (e.g. `https://matrix.example.com/etherpad`), adjust these URLs accordingly before usage.
|
||||
|
||||
|
||||
### 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.example.com/admin/plugins`, install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
|
||||
|
||||
|
||||
### How to use Etherpad widgets without an integration manager (like Dimension)
|
||||
|
||||
This is how it works in Element Web, it might work quite similar with other clients:
|
||||
|
||||
To integrate a standalone Etherpad in a room, create your pad by visiting `https://etherpad.example.com`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` section.
|
||||
|
||||
|
||||
### 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 Web. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab.
|
||||
|
||||
|
||||
#### Removing the integrated Etherpad chat
|
||||
|
||||
If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
|
||||
|
||||
Example: `https://etherpad.example.com/p/$roomId_$padName?showChat=false`
|
||||
|
||||
|
||||
## Known issues
|
||||
|
||||
If your Etherpad widget fails to load, this might be due to Dimension generating a Pad name so long, the Etherpad app rejects it.
|
||||
|
||||
@ -16,6 +16,7 @@ matrix_synapse_federation_domain_whitelist:
|
||||
|
||||
If you wish to disable federation, you can do that with an empty list (`[]`), or better yet by completely disabling federation (see below).
|
||||
|
||||
|
||||
## Exposing the room directory over federation
|
||||
|
||||
By default, your server's public rooms directory is not exposed to other servers via federation.
|
||||
@ -26,6 +27,7 @@ If you wish to expose it, add this to your configuration file (`inventory/host_v
|
||||
matrix_synapse_allow_public_rooms_over_federation: true
|
||||
```
|
||||
|
||||
|
||||
## Disabling federation
|
||||
|
||||
To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
|
||||
@ -52,6 +54,7 @@ matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
|
||||
|
||||
Why? This change could be useful for people running small Synapse instances on small severs/VPSes to avoid being impacted by a simple DOS/DDOS when bandwidth, RAM, an CPU resources are limited and if your hosting provider does not provide a DOS/DDOS protection.
|
||||
|
||||
|
||||
The following changes in the configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other:
|
||||
|
||||
```yaml
|
||||
|
||||
@ -6,6 +6,7 @@ Jitsi installation is **not enabled by default**, because it's not a core compon
|
||||
|
||||
The setup done by the playbook is very similar to [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet). You can refer to the documentation there for many of the options here.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You may need to open the following ports to your server:
|
||||
@ -13,6 +14,7 @@ You may 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)).
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Jitsi, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -112,6 +114,7 @@ jitsi_ldap_start_tls: false
|
||||
|
||||
For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet#authentication-using-ldap) and the [saslauthd `LDAP_SASLAUTHD`](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD) documentation.
|
||||
|
||||
|
||||
## (Optional) Making your Jitsi server work on a LAN
|
||||
|
||||
By default the Jitsi Meet instance does not work with a client in LAN (Local Area Network), even if others are connected from WAN. There are no video and audio. In the case of WAN to WAN everything is ok.
|
||||
@ -169,7 +172,6 @@ By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-vid
|
||||
There is an ansible playbook that can be run with the following tag: `ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
|
||||
|
||||
For this role to work you will need an additional section in the ansible hosts file with the details of the JVB hosts, for example:
|
||||
|
||||
```INI
|
||||
[jitsi_jvb_servers]
|
||||
<your jvb hosts> ansible_host=<ip address of the jvb host>
|
||||
@ -267,17 +269,12 @@ jitsi_disable_gravatar: false
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
You can use the self-hosted Jitsi server in multiple ways:
|
||||
@ -290,6 +287,7 @@ You can use the self-hosted Jitsi server in multiple ways:
|
||||
|
||||
**Note**: Element apps on mobile devices currently [don't support joining meetings on a self-hosted Jitsi server](https://github.com/element-hq/riot-web/blob/601816862f7d84ac47547891bd53effa73d32957/docs/jitsi.md#mobile-app-support).
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Rebuilding your Jitsi installation
|
||||
|
||||
@ -21,6 +21,7 @@ matrix_synapse_ext_password_provider_ldap_bind_password: ""
|
||||
matrix_synapse_ext_password_provider_ldap_filter: ""
|
||||
```
|
||||
|
||||
|
||||
## Authenticating only using a password provider
|
||||
|
||||
If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it:
|
||||
@ -29,10 +30,12 @@ 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).
|
||||
|
||||
@ -51,6 +51,7 @@ Still, ma1sd can do much more. You can refer to the [ma1sd website](https://gith
|
||||
|
||||
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.
|
||||
|
||||
|
||||
#### 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.
|
||||
@ -71,6 +72,7 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu
|
||||
|
||||
**Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) or the `openid` APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the `openid` APIs (only!) on the federation port. Make sure the federation port (usually `https://matrix.example.com:8448`) is whitelisted in your firewall (even if you don't actually use/need federation).
|
||||
|
||||
|
||||
#### Authentication
|
||||
|
||||
[Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver.
|
||||
@ -129,16 +131,7 @@ matrix_ma1sd_configuration_extension_yaml: |
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
@ -12,6 +12,7 @@ Matrix Authentication Service is an implementation of [MSC3861: Next-generation
|
||||
|
||||
**If you've already been using Synapse** and have user accounts in its database, you can [migrate to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service).
|
||||
|
||||
|
||||
## Reasons to use Matrix Authentication Service
|
||||
|
||||
You may be wondering whether you should make the switch to Matrix Authentication Service (MAS) or keep using your existing authentication flow via Synapse (password-based or [OIDC](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)-enabled).
|
||||
@ -32,6 +33,7 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
|
||||
|
||||
- To reap some of the security benefits that Matrix Authentication Service offers, as outlined in the [Better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/) article.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- ⚠️ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
|
||||
@ -40,6 +42,7 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
|
||||
|
||||
- ❌ **disabling all password providers** for Synapse (things like [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc.) More details about this are available in the [Expectations](#expectations) section below.
|
||||
|
||||
|
||||
## Expectations
|
||||
|
||||
This section details what you can expect when switching to the Matrix Authentication Service (MAS).
|
||||
@ -81,6 +84,8 @@ This section details what you can expect when switching to the Matrix Authentica
|
||||
|
||||
- ✅ Users that are prepared by the playbook (for bots, bridges, etc.) will continue to be registered automatically as expected. The playbook automatically does the right thing regardless of homeserver implementation (Synapse, Dendrite, etc.) and whether MAS is enabled or not. When MAS is enabled, the playbook will forward user-registration requests to MAS.
|
||||
|
||||
|
||||
|
||||
## Installation flows
|
||||
|
||||
### New homeserver
|
||||
@ -97,6 +102,7 @@ For existing Synapse homeservers:
|
||||
|
||||
- then follow the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) instructions to perform the installation and migration
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Matrix Authentication Service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -117,6 +123,7 @@ In the sub-sections that follow, we'll cover some additional configuration optio
|
||||
|
||||
There are many other configuration options available. Consult the [`defaults/main.yml` file](../roles/custom/matrix-authentication-service/defaults/main.yml) in the [matrix-authentication-service role](../roles/custom/matrix-authentication-service/) to discover them.
|
||||
|
||||
|
||||
### Adjusting the Matrix Authentication Service URL
|
||||
|
||||
By default, this playbook installs the Matrix Authentication Service on the `matrix.` subdomain, at the `/auth` path (https://matrix.example.com/auth). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
|
||||
@ -137,6 +144,7 @@ The [configuration above](#adjusting-the-playbook-configuration) instructs exist
|
||||
|
||||
This is done temporarily. The migration steps are described in more detail in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) section below.
|
||||
|
||||
|
||||
### Upstream OAuth2 configuration
|
||||
|
||||
To make Matrix Authentication Service delegate to an existing upstream OAuth 2.0/OIDC provider, you can use its [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers).
|
||||
@ -268,6 +276,7 @@ matrix_authentication_service_config_upstream_oauth2_providers:
|
||||
- go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process
|
||||
- remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration
|
||||
|
||||
|
||||
## Adjusting DNS records
|
||||
|
||||
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Matrix Authentication Service domain to the Matrix server.
|
||||
@ -276,25 +285,16 @@ See [Configuring DNS](configuring-dns.md) for details about DNS changes.
|
||||
|
||||
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the [installation](installing.md) command: `just install-all`
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
- If you're in the process of migrating an existing Synapse homeserver to MAS, you should now follow the rest of the steps in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) guide.
|
||||
If you're in the process of migrating an existing Synapse homeserver to MAS, you should now follow the rest of the steps in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) guide.
|
||||
|
||||
💡 After installation, you should [verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly).
|
||||
|
||||
|
||||
## Migrating an existing Synapse homeserver to Matrix Authentication Service
|
||||
|
||||
Our migration guide is loosely based on the upstream [Migrating an existing homeserver](https://element-hq.github.io/matrix-authentication-service/setup/migration.html) guide.
|
||||
@ -333,6 +333,7 @@ The installation + migration steps are like this:
|
||||
|
||||
6. [Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly)
|
||||
|
||||
|
||||
### Migrate your data from Synapse to Matrix Authentication Service using syn2mas
|
||||
|
||||
We **don't** ask you to [run the `syn2mas` migration advisor command](https://element-hq.github.io/matrix-authentication-service/setup/migration.html#run-the-migration-advisor), because it only gives you the green light if your Synapse configuration (`homeserver.yaml`) is configured in a way that's compatible with MAS (delegating authentication to MAS; disabling Synapse's password config; etc.). Until we migrate your data with the `syn2mas` tool, we intentionally avoid doing these changes to allow existing user sessions to work.
|
||||
@ -406,6 +407,7 @@ just run-tags matrix-authentication-service-syn2mas
|
||||
|
||||
Having performed a `syn2mas` migration once, trying to do it again will report errors for users that were already migrated (e.g. "Error: Unknown upstream provider oauth-delegated").
|
||||
|
||||
|
||||
## Verify that Matrix Authentication Service is installed correctly
|
||||
|
||||
After [installation](#installing), run the `doctor` subcommand of the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) to verify that MAS is installed correctly.
|
||||
@ -440,12 +442,14 @@ This documentation page already mentions:
|
||||
|
||||
There are other sub-commands available. Run `/matrix/matrix-authentication-service/bin/mas-cli` to get an overview.
|
||||
|
||||
|
||||
## User registration
|
||||
|
||||
After Matrix Authentication Service is [installed](#installing), users need to be managed there (unless you're managing them in an [upstream OAuth2 provider](#upstream-oauth2-configuration)).
|
||||
|
||||
You can register users new users as described in the [Registering users](./registering-users.md) documentation (via `mas-cli manage register-user` or the Ansible playbook's `register-user` tag).
|
||||
|
||||
|
||||
## Working around email deliverability issues
|
||||
|
||||
Because Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user, you may need to work around email deliverability issues if [your email-sending configuration](./configuring-playbook-email.md) is not working.
|
||||
|
||||
@ -14,6 +14,7 @@ If you decide that you'd like to let this playbook install it for you, you'd nee
|
||||
- (required) [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md)
|
||||
- (optional, but encouraged) [set up the REST authentication password provider module](configuring-playbook-rest-auth.md)
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
@ -115,16 +116,8 @@ To learn more about what the policy configuration, see the matrix-corporal docum
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command (`--tags=setup-all,start` or `--tags=setup-aux-files,setup-corporal,start`).
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just run-tags setup-aux-files,setup-corporal,start` or `just setup-all`
|
||||
|
||||
`just run-tags setup-aux-files,setup-corporal,start` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Matrix Corporal files
|
||||
|
||||
|
||||
@ -34,13 +34,4 @@ matrix_ldap_registration_proxy_systemd_wanted_services_list_custom:
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -30,7 +30,6 @@ By default, the media-repo will use the local filesystem for data storage. You c
|
||||
## Configuring the media-repo
|
||||
|
||||
Additional common configuration options:
|
||||
|
||||
```yaml
|
||||
|
||||
# The postgres database pooling options
|
||||
|
||||
@ -16,6 +16,7 @@ Use matrix-registration to **create unique registration links**, which people ca
|
||||
|
||||
- **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.example.com/matrix-registration`
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable matrix-registration, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -51,16 +52,12 @@ If you've decided to use the default hostname, you won't need to do any extra DN
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
@ -70,6 +67,7 @@ It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/a
|
||||
|
||||
We make the most common APIs easy to use via the playbook (see below).
|
||||
|
||||
|
||||
### Creating registration tokens
|
||||
|
||||
To **create a new user registration token (link)**, use this command:
|
||||
@ -84,6 +82,7 @@ The above command creates and returns a **one-time use** token, which **expires*
|
||||
|
||||
Share the unique registration link (generated by the command above) with users to let them register on your Matrix server.
|
||||
|
||||
|
||||
### Listing registration tokens
|
||||
|
||||
To **list the existing user registration tokens**, use this command:
|
||||
@ -92,5 +91,3 @@ To **list the existing user registration tokens**, use this command:
|
||||
ansible-playbook -i inventory/hosts setup.yml \
|
||||
--tags=list-matrix-registration-tokens
|
||||
```
|
||||
|
||||
The shortcut command with `just` program is also available: `just run-tags list-matrix-registration-tokens`
|
||||
|
||||
@ -93,20 +93,7 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-SERVICENAME/template
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Set up Double Puppeting
|
||||
|
||||
@ -130,6 +117,7 @@ to `vars.yml` to control the logging level, where you may replace WARN with one
|
||||
|
||||
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:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
@ -138,6 +126,8 @@ Send `login` to the bridge bot to get started. You can learn more here about aut
|
||||
|
||||
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.
|
||||
|
||||
@ -8,6 +8,7 @@ This role is intended to support UnifiedPush notifications for use with the Matr
|
||||
|
||||
**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
|
||||
|
||||
To enable ntfy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -49,16 +50,12 @@ By default, you will need to create a CNAME record for `ntfy`. See [Configuring
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
@ -105,6 +102,7 @@ ntfy also has a web app to subscribe to and push to topics from the browser. Thi
|
||||
|
||||
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.
|
||||
|
||||
@ -24,6 +24,7 @@ traefik_config_certificatesResolvers_acme_email: YOUR_EMAIL_ADDRESS
|
||||
|
||||
Traefik will manage SSL certificates for all services seamlessly.
|
||||
|
||||
|
||||
### Traefik managed by you
|
||||
|
||||
```yaml
|
||||
@ -131,6 +132,7 @@ There are 2 ways to go about it:
|
||||
|
||||
- (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.).
|
||||
@ -199,6 +201,7 @@ To put it another way:
|
||||
- `curl http://127.0.0.1:81` will result in a `404 - not found` error
|
||||
- but `curl -H 'Host: matrix.example.com' 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.
|
||||
|
||||
@ -6,7 +6,7 @@ See the project's [documentation](https://github.com/matrix-org/pantalaimon) to
|
||||
|
||||
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.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
## 1. Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
|
||||
@ -16,15 +16,6 @@ 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).
|
||||
|
||||
## Installing
|
||||
## 2. Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -4,6 +4,7 @@ The playbook can install and configure [docker-postgres-backup-local](https://gi
|
||||
|
||||
For a more complete backup solution (one that includes not only Postgres, but also other configuration/data files), you may wish to look into [BorgBackup](configuring-playbook-backup-borg.md) instead.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Postgres backup, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -14,6 +15,7 @@ postgres_backup_enabled: true
|
||||
|
||||
Refer to the table below for additional configuration variables and their default values.
|
||||
|
||||
|
||||
| Name | Default value | Description |
|
||||
| :-------------------------------- | :--------------------------- | :--------------------------------------------------------------- |
|
||||
|`postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
|
||||
@ -24,15 +26,11 @@ Refer to the table below for additional configuration variables and their defaul
|
||||
|`postgres_backup_base_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Base path for postgres-backup. Also see `postgres_backup_data_path` |
|
||||
|`postgres_backup_data_path` | `"{{ postgres_backup_base_path }}/data"` | Storage path for postgres-backup database backups |
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
@ -55,16 +55,7 @@ By default, you will need to create a CNAME record for `stats`. See [Configuring
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## What does it do?
|
||||
|
||||
@ -78,12 +69,14 @@ Name | Description
|
||||
`grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
|
||||
`grafana_default_admin_user`<br>`grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
|
||||
|
||||
|
||||
## Security and privacy
|
||||
|
||||
Metrics and resulting graphs can contain a lot of information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
|
||||
|
||||
Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
|
||||
|
||||
|
||||
## Collecting metrics to an external Prometheus server
|
||||
|
||||
**If the integrated Prometheus server is enabled** (`prometheus_enabled: true`), metrics are collected by it from each service via communication that happens over the container network. Each service does not need to expose its metrics "publicly".
|
||||
@ -120,7 +113,6 @@ Name | Description
|
||||
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.example.com/metrics/synapse/worker/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`.
|
||||
|
||||
The playbook also generates an exemplary config file (`/matrix/synapse/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs. Make sure to edit the specified `password_file` path and contents and path to your `synapse-v2.rules`. It will look a bit like this:
|
||||
|
||||
```yaml
|
||||
scrape_configs:
|
||||
- job_name: 'synapse'
|
||||
@ -147,6 +139,7 @@ scrape_configs:
|
||||
index: 18111
|
||||
```
|
||||
|
||||
|
||||
## More information
|
||||
|
||||
- [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md)
|
||||
|
||||
@ -22,16 +22,7 @@ matrix_prometheus_nginxlog_exporter_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## Docker Image Compatibility
|
||||
|
||||
|
||||
@ -12,16 +12,7 @@ prometheus_postgres_exporter_enabled: true
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
## What does it do?
|
||||
|
||||
@ -32,6 +23,7 @@ Name | Description
|
||||
`prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook
|
||||
`prometheus_postgres_exporter_container_labels_traefik_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.example.com/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` on that other documentation page.
|
||||
|
||||
|
||||
## More information
|
||||
|
||||
- [The PostgresSQL dashboard](https://grafana.com/grafana/dashboards/9628) (generic postgres dashboard)
|
||||
|
||||
@ -51,16 +51,12 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -26,13 +26,4 @@ matrix_synapse_password_config_localdb_enabled: false
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -7,6 +7,7 @@ Riot has since been [renamed to Element](https://element.io/blog/welcome-to-elem
|
||||
- to learn more about Element Web and its configuration, see our dedicated [Configuring Element Web](configuring-playbook-client-element-web.md) documentation page
|
||||
- to learn how to migrate from Riot to Element Web, see [Migrating to Element Web](#migrating-to-element-web) below
|
||||
|
||||
|
||||
## Migrating to Element Web
|
||||
|
||||
### Migrating your custom settings
|
||||
@ -15,6 +16,7 @@ If you have custom `matrix_riot_web_` variables in your `inventory/host_vars/mat
|
||||
|
||||
Some other playbook variables (but not all) with `riot` in their name are also renamed. The playbook checks and warns if you are using the old name for some commonly used ones.
|
||||
|
||||
|
||||
### Domain migration
|
||||
|
||||
We used to set up Riot at the `riot.example.com` domain. The playbook now sets up Element Web at `element.example.com` by default.
|
||||
@ -25,15 +27,7 @@ There are a few options for handling this:
|
||||
|
||||
- (**embracing changes** - using only `element.example.com`) - set up the `element.example.com` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.example.com` in this case.
|
||||
|
||||
|
||||
### Re-running the playbook
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -29,6 +29,7 @@ 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-back-up-the-data-on-my-server) before migrating your local media store to an S3-backed one.
|
||||
@ -84,6 +85,7 @@ After making the backup, follow one of the guides below for a migration path fro
|
||||
|
||||
14. 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
|
||||
|
||||
1. While all Matrix services are running, run the following command on the server:
|
||||
|
||||
@ -12,6 +12,7 @@ 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 storage like [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html), [Storj](https://storj.io), [Wasabi](https://wasabi.com), [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces), etc.
|
||||
@ -31,6 +32,7 @@ Here are some of the important aspects of choosing the right provider:
|
||||
- if a provider's price model is transparent (whether it includes hidden costs like minimum charge, minimum storage term, etc.)
|
||||
- if a provider has free or cheap egress fee (in case you need to get the data out often, for some reason) - likely not too important for the common use-case
|
||||
|
||||
|
||||
## 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.
|
||||
@ -64,6 +66,7 @@ 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**.
|
||||
|
||||
|
||||
## Backblaze B2
|
||||
|
||||
To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html) you first need to sign up.
|
||||
@ -89,12 +92,14 @@ For configuring [Goofys](configuring-playbook-s3-goofys.md) or [s3-synapse-stora
|
||||
|
||||
- **Storage Class** - use `STANDARD`. Backblaze B2 does not have different storage classes, so it doesn't make sense to use any other value.
|
||||
|
||||
|
||||
## Other providers
|
||||
|
||||
For other S3-compatible providers, you may not need to configure security policies, etc. (just like for [Backblaze B2](#backblaze-b2)).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Setting up
|
||||
|
||||
To set up Synapse to store files in S3, follow the instructions for the method of your choice:
|
||||
|
||||
@ -25,13 +25,4 @@ matrix_synapse_password_config_localdb_enabled: false
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -6,6 +6,7 @@ The playbook can install and configure [sliding-sync](https://github.com/matrix-
|
||||
|
||||
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 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.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Sliding Sync proxy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -38,16 +39,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all`.
|
||||
|
||||
### External databases
|
||||
|
||||
|
||||
@ -4,6 +4,7 @@ By default, this playbook retrieves and auto-renews free SSL certificates from [
|
||||
|
||||
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).
|
||||
|
||||
|
||||
## Using staging Let's Encrypt certificates instead of real ones
|
||||
|
||||
For testing purposes, you may wish to use staging certificates provide by Let's Encrypt.
|
||||
@ -14,6 +15,7 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
|
||||
traefik_config_certificatesResolvers_acme_use_staging: true
|
||||
```
|
||||
|
||||
|
||||
## 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://`.
|
||||
@ -24,6 +26,7 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
|
||||
traefik_config_entrypoint_web_secure_enabled: false
|
||||
```
|
||||
|
||||
|
||||
## 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/)):
|
||||
@ -31,6 +34,7 @@ If you'd like to use your own SSL certificates, instead of the default (SSL cert
|
||||
- generate your self-signed certificate files
|
||||
- follow the [Using your own SSL certificates](#using-your-own-ssl-certificates) documentation below
|
||||
|
||||
|
||||
## Using your own SSL certificates
|
||||
|
||||
To use your own SSL certificates with Traefik, you need to:
|
||||
|
||||
@ -77,16 +77,12 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -6,6 +6,7 @@ synapse-admin is a web UI tool you can use to **administrate users, rooms, media
|
||||
|
||||
💡 **Note**: the latest version of synapse-admin is hosted by [etke.cc](https://etke.cc/) at [admin.etke.cc](https://admin.etke.cc/). If you only need this service occasionally and trust giving your admin credentials to a 3rd party Single Page Application, you can consider using it from there and avoiding the (small) overhead of self-hosting.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Synapse Admin, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -47,16 +48,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -6,6 +6,7 @@ See that project's [documentation](https://github.com/matrix-org/synapse-auto-ac
|
||||
|
||||
**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, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -26,6 +27,7 @@ matrix_synapse_ext_synapse_auto_accept_invite_worker_to_run_on: 'matrix-synapse-
|
||||
|
||||
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.
|
||||
|
||||
@ -6,6 +6,7 @@ It's a CLI tool that automatically compresses Synapse's `state_groups` database
|
||||
|
||||
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.example.com/vars.yml` file:
|
||||
@ -14,18 +15,15 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
|
||||
matrix_synapse_auto_compressor_enabled: true
|
||||
```
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After configuring the playbook, run the [installation](installing.md) command:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -4,6 +4,7 @@ If you'd like to store Synapse's content repository (`media_store`) files on Ama
|
||||
|
||||
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/).
|
||||
@ -21,6 +22,7 @@ You can run some scripts to delete the local files once in a while (which we do
|
||||
|
||||
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.example.com/vars.yml`):
|
||||
@ -55,6 +57,7 @@ If you have existing files in Synapse's media repository (`/matrix/synapse/media
|
||||
|
||||
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:
|
||||
|
||||
@ -50,13 +50,4 @@ If you've decided to use the default hostname, you won't need to do any extra DN
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
@ -16,6 +16,7 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you
|
||||
|
||||
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). You can find information about this in [`roles/custom/matrix-synapse/defaults/main.yml`](../roles/custom/matrix-synapse/defaults/main.yml).
|
||||
|
||||
|
||||
## Load balancing with workers
|
||||
|
||||
To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/element-hq/synapse/blob/master/docs/workers.md) and [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html).
|
||||
@ -79,10 +80,12 @@ A separate Ansible role (`matrix-synapse-reverse-proxy-companion`) and component
|
||||
|
||||
In case any problems occur, make sure to have a look at the [list of synapse issues about workers](https://github.com/element-hq/synapse/issues?q=workers+in%3Atitle) and your `journalctl --unit 'matrix-*'`.
|
||||
|
||||
|
||||
## Synapse Admin
|
||||
|
||||
Certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace, if you install [Synapse Admin](configuring-playbook-synapse-admin.md).
|
||||
|
||||
|
||||
## Synapse + OpenID Connect for Single-Sign-On
|
||||
|
||||
💡 An alternative to setting up OIDC in Synapse is to use [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS). Newer clients (like Element X) only support SSO-based authentication via MAS and not via the legacy Synapse OIDC setup described below. That said, MAS is still a new experimental service which comes with its own downsides. Consult its documentation to learn if it will be a good fit for your deployment.
|
||||
@ -114,6 +117,7 @@ matrix_synapse_oidc_providers:
|
||||
backchannel_logout_enabled: true # Optional
|
||||
```
|
||||
|
||||
|
||||
## Customizing templates
|
||||
|
||||
[Templates](https://github.com/element-hq/synapse/blob/develop/docs/templates.md) are used by Synapse for showing **certain web pages** handled by the server, as well as for **email notifications**.
|
||||
@ -152,6 +156,7 @@ matrix_synapse_container_image_customizations_templates_git_repository_ssh_priva
|
||||
|
||||
As mentioned in Synapse's Templates documentation, Synapse will fall back to its own templates if a template is not found in that directory. Due to this, it's recommended to only store and maintain template files in your repository if you need to make custom changes. Other files (which you don't need to change), should not be duplicated, so that you don't need to worry about getting out-of-sync with the original Synapse templates.
|
||||
|
||||
|
||||
## Monitoring Synapse Metrics with Prometheus and Grafana
|
||||
|
||||
This playbook allows you to enable Synapse metrics, which can provide insight into the performance and activity of Synapse.
|
||||
|
||||
@ -4,6 +4,7 @@ By default, this playbook configures your Matrix homeserver to not send any tele
|
||||
|
||||
The [matrix.org](https://matrix.org) team would really appreciate it if you could help the project out by reporting usage statistics from your homeserver. Enabling usage statistics helps track the growth of the Matrix community, and helps to make Matrix a success.
|
||||
|
||||
|
||||
## Enabling Telemetry
|
||||
|
||||
If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -14,6 +15,7 @@ matrix_synapse_report_stats: true # for synapse
|
||||
matrix_dendrite_report_stats: true # for dendrite
|
||||
```
|
||||
|
||||
|
||||
## Usage statistics being submitted
|
||||
|
||||
When enabled, your homeserver will regularly upload a few dozen statistics about your server. This data includes your homeserver's domain, the total number of users, the number of active users, the total number of rooms, and the number of messages sent per day on your homeserver.
|
||||
|
||||
@ -4,6 +4,7 @@ By default, this playbook installs and manages a [Traefik](https://doc.traefik.i
|
||||
|
||||
This Ansible role support various configuration options. Feel free to consult its `default/main.yml` variables file.
|
||||
|
||||
|
||||
## Adjusting SSL certificate retrieval
|
||||
|
||||
See the dedicated [Adjusting SSL certificate retrieval](configuring-playbook-ssl-certificates.md) documentation page.
|
||||
@ -88,6 +89,7 @@ traefik_configuration_extension_yaml: |
|
||||
insecureSkipVerify: true
|
||||
```
|
||||
|
||||
|
||||
Next, you have to add a new dynamic configuration file for Traefik that contains the actual information of the server using the `aux_file_definitions` variable. In this example, we will terminate SSL at the Traefik instance and connect to the other server via HTTPS. Traefik will now take care of managing the certificates.
|
||||
|
||||
```yaml
|
||||
@ -136,6 +138,7 @@ With these changes, all TCP traffic will be reverse-proxied to the target system
|
||||
|
||||
**WARNING**: This configuration might lead to problems or need additional steps when a [certbot](https://certbot.eff.org/) behind Traefik also tries to manage [Let's Encrypt](https://letsencrypt.org/) certificates, as Traefik captures all traffic to ```PathPrefix(`/.well-known/acme-challenge/`)```.
|
||||
|
||||
|
||||
## Traefik behind a `proxy_protocol` reverse-proxy
|
||||
|
||||
If you run a reverse-proxy which speaks `proxy_protocol`, add the following to your configuration file:
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user