Commit cf1b9f14 authored by nono's avatar nono 💻
Browse files
parents 1d6fc656 6184ed2d
# 2022-04-25
## buscarron bot support
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up [the Buscarron bot](https://gitlab.com/etke.cc/buscarron). It's a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) Matrix room
See our [Setting up Buscarron](docs/configuring-playbook-bot-buscarron.md) documentation to get started.
# 2022-04-21
## matrix-registration-bot support
Thanks to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s), the playbook can now help you set up [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) - a bot that is used to create and manage registration tokens for a Matrix server.
See our [Setting up matrix-registration-bot](docs/configuring-playbook-bot-matrix-registration-bot.md) documentation to get started.
# 2022-04-19
## Borg backup support
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up [Borg](https://www.borgbackup.org/) backups with [borgmatic](https://torsion.org/borgmatic/) of your Matrix server.
See our [Setting up borg backup](docs/configuring-playbook-backup-borg.md) documentation to get started.
## (Compatibility Break) Upgrading to Synapse v1.57 on setups using workers may require manual action
If you're running a worker setup for Synapse (`matrix_synapse_workers_enabled: true`), the [Synapse v1.57 upgrade notes](https://github.com/matrix-org/synapse/blob/v1.57.0rc1/docs/upgrade.md#changes-to-database-schema-for-application-services) say that you may need to take special care when upgrading:
> Synapse v1.57.0 includes a change to the way transaction IDs are managed for application services. If your deployment uses a dedicated worker for application service traffic, **it must be stopped** when the database is upgraded (which normally happens when the main process is upgraded), to ensure the change is made safely without any risk of reusing transaction IDs.
If you're not running an `appservice` worker (`matrix_synapse_workers_preset: little-federation-helper` or `matrix_synapse_workers_appservice_workers_count: 0`), you are probably safe to upgrade as per normal, without taking any special care.
If you are running a setup with an `appservice` worker, or otherwise want to be on the safe side, we recommend the following upgrade path:
0. Pull the latest playbook changes
1. Stop all services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
2. Re-run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all`)
3. Start Postgres (`systemctl start matrix-postgres` on the server)
4. Start the main Synapse process (`systemctl start matrix-synapse` on the server)
5. Wait a while so that Synapse can start and complete the database migrations. You can use `journalctl -fu matrix-synapse` on the server to get a clue. Waiting a few minutes should also be enough.
6. It should now be safe to start all other services. `ansible-playbook -i inventory/hosts setup.yml --tags=start` will do it for you
# 2022-04-14
## (Compatibility Break) Changes to `docker-src` permissions necessitating manual action
Users who build container images from source will need to manually correct file permissions of some directories on the server.
When self-building, the playbook used to `git clone` repositories (into `/matrix/SERVICE/docker-src`) using the `root` user, but now uses `matrix` instead to work around [the following issue with git 2.35.2](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1749).
If you're on a non-`amd64` architecture (that is, you're overriding `matrix_architecture` in your `vars.yml` file) or you have enabled self-building for some service (e.g. `matrix_*_self_build: true`), you're certainly building some container images from source and have `docker-src` directories with mixed permissions lying around in various `/matrix/SERVICE` directories.
The playbook *could* correct these permissions automatically, but that requires additional Ansible tasks in some ~45 different places - something that takes considerable effort. So we ask users observing errors related to `docker-src` directories to correct the problem manually by **running this command on the Matrix server** (which deletes all `/matrix/*/docker-src` directories): `find /matrix -maxdepth 2 -name 'docker-src' | xargs rm -rf`
# 2022-03-17
## (Compatibility Break) ma1sd identity server no longer installed by default
The playbook no longer installs the [ma1sd](https://github.com/ma1uta/ma1sd) identity server by default. The next time you run the playbook, ma1sd will be uninstalled from your server, unless you explicitly enable the ma1sd service (see how below).
The main reason we used to install ma1sd by default in the past was to prevent Element from talking to the `matrix.org` / `vector.im` identity servers, by forcing it to talk to our own self-hosted (but otherwise useless) identity server instead, thus preventing contact list leaks.
Since Element no longer defaults to using a public identity server if another one is not provided, we can stop installing ma1sd.
If you need to install the ma1sd identity server for some reason, you can explicitly enable it by adding this to your `vars.yml` file:
```yaml
matrix_ma1sd_enabled: true
```
# 2022-02-12
## matrix_encryption_disabler support
......
......@@ -31,7 +31,7 @@ Using this playbook, you can get the following services configured on your serve
- (optional, default) an [Element](https://app.element.io/) ([formerly Riot](https://element.io/previously-riot)) web UI, which is configured to connect to your own Synapse server by default
- (optional, default) a [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server
- (optional) a [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server
- (optional, default) an [Exim](https://www.exim.org/) mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server)
......@@ -121,6 +121,10 @@ Using this playbook, you can get the following services configured on your serve
- (optional) the [Cinny](https://github.com/ajbura/cinny) web client - see [docs/configuring-playbook-client-cinny.md](docs/configuring-playbook-client-cinny.md) for setup documentation
- (optional) the [Borg](https://borgbackup.org) backup - see [docs/configuring-playbook-backup-borg.md](docs/configuring-playbook-backup-borg.md) for setup documentation
- (optional) the [Buscarron](https://gitlab.com/etke.cc/buscarron) bot - see [docs/configuring-playbook-bot-buscarron.md](docs/configuring-playbook-bot-buscarron.md) for setup documentation
Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
**Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need.
......
......@@ -2,7 +2,7 @@
As stated in the [Prerequisites](prerequisites.md), currently only `x86_64` is fully supported. However, it is possible to set the target architecture, and some tools can be built on the host or other measures can be used.
To that end add the following variable to your `vars.yaml` file:
To that end add the following variable to your `vars.yml` file (see [Configuring playbook](configuring-playbook.md)):
```yaml
matrix_architecture: <your-matrix-server-architecture>
......@@ -13,7 +13,7 @@ Currently supported architectures are the following:
- `arm64`
- `arm32`
so for the Raspberry Pi, the following should be in your `vars.yaml` file:
so for the Raspberry Pi, the following should be in your `vars.yml` file:
```yaml
matrix_architecture: "arm32"
......
# Configuring AWX System (optional)
An AWX setup for managing multiple Matrix servers.
This section is used in an AWX system that can create and manage multiple [Matrix](http://matrix.org/) servers. You can issue members an AWX login to their own 'organisation', which they can use to manage/configure 1 to N servers.
Members can be assigned a server from Digitalocean, or they can connect their own on-premises server. These playbooks are free to use in a commercial context with the 'MemberPress Plus' plugin. They can also be run in a non-commercial context.
The AWX system is arranged into 'members' each with their own 'subscriptions'. After creating a subscription the user enters the 'provision stage' where they defined the URLs they will use, the servers location and whether or not there's already a website at the base domain. They then proceed onto the 'deploy stage' where they can configure their Matrix server.
This system can manage the updates, configuration, import and export, backups and monitoring on its own. It is an extension of the popular deploy script [spantaleev/matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy).
Warning: This system is about to undergo heavy revision, **we do not recommend using it at this time.**
## Other Required Playbooks
The following repositories allow you to copy and use this setup:
[Create AWX System](https://gitlab.com/GoMatrixHosting/create-awx-system) - Creates and configures the AWX system for you.
[Ansible Create Delete Subscription Membership](https://gitlab.com/GoMatrixHosting/ansible-create-delete-subscription-membership) - Used by the AWX system to create memberships and subscriptions. Also includes other administrative playbooks for updates, backups and restoring servers.
[Ansible Provision Server](https://gitlab.com/GoMatrixHosting/ansible-provision-server) - Used by AWX members to perform initial configuration of their DigitalOcean or On-Premises server.
[GMHosting External Tools](https://gitlab.com/GoMatrixHosting/gmhosting-external-tools) - Extra tools we run outside of AWX, some of which are experimental.
## Does I need an AWX setup to use this? How do I configure it?
Yes, you'll need to configure an AWX instance, the [Create AWX System](https://gitlab.com/GoMatrixHosting/create-awx-system) repository makes it easy to do. Just follow the steps listed in ['/docs/Installation_AWX.md' of that repository](https://gitlab.com/GoMatrixHosting/create-awx-system/-/blob/master/docs/Installation_AWX.md).
For simpler installation steps you can use to get started with this system, check out our minimal installation guide at ['/doc/Installation_Minimal_AWX.md of that repository'](https://gitlab.com/GoMatrixHosting/create-awx-system/-/blob/master/docs/Installation_Minimal_AWX.md).
## Does I need a front-end WordPress site? And a DigitalOcean account?
You do not need a front-end WordPress site or the MemberPress plugin to use this setup. It can be run on it's own in a non-commercial context.
You also don't need a DigitalOcean account, although this will limit you to only being able to connect 'On-Premises' servers.
......@@ -38,6 +38,7 @@ If you are using Cloudflare DNS, make sure to disable the proxy and set all reco
| CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
| CNAME | `cinny` | - | - | - | `matrix.<your-domain>` |
| CNAME | `buscarron` | - | - | - | `matrix.<your-domain>` |
## Subdomains setup
......@@ -60,13 +61,15 @@ The `hydrogen.<your-domain>` subdomain may be necessary, because this playbook c
The `cinny.<your-domain>` subdomain may be necessary, because this playbook could install the [Cinny](https://github.com/ajbura/cinny) web client. The installation of cinny is disabled by default, it is not a core required component. To learn how to install it, see our [configuring cinny guide](configuring-playbook-client-cinny.md). If you do not wish to set up cinny, feel free to skip the `cinny.<your-domain>` DNS record.
The `buscarron.<your-domain>` subdomain may be necessary, because this playbook could install the [buscarron](https://github.com/etke.cc/buscarron) bot. The installation of buscarron is disabled by default, it is not a core required component. To learn how to install it, see our [configuring buscarron guide](configuring-playbook-bot-buscarron.md). If you do not wish to set up buscarron, feel free to skip the `buscarron.<your-domain>` DNS record.
## `_matrix-identity._tcp` SRV record setup
To make the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server (which this playbook installs for you) enable its federation features, set up an SRV record that looks like this:
To make the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server (which this playbook may optionally install for you) enable its federation features, set up an SRV record that looks like this:
- Name: `_matrix-identity._tcp` (use this text as-is)
- Content: `10 0 443 matrix.<your-domain>` (replace `<your-domain>` with your own)
This is an optional feature. See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.
This is an optional feature for the optionally-installed [ma1sd service](configuring-playbook-ma1sd.md). See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.
Note: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
......
# Setting up borg backup (optional)
The playbook can install and configure [borgbackup](https://www.borgbackup.org/) with [borgmatic](https://torsion.org/borgmatic/) for you.
BorgBackup is a deduplicating backup program with optional compression and encryption.
That means your daily incremental backups can be stored in a fraction of the space and is safe whether you store it at home or on a cloud service.
You will need a remote server where borg will store the backups. There are hosted, borg compatible solutions available, such as [BorgBase](https://www.borgbase.com).
The backup will run based on `matrix_backup_borg_schedule` var (systemd timer calendar), default: 4am every day.
By default, if you're using the integrated Postgres database server (as opposed to [an external Postgres server](configuring-playbook-external-postgres.md)), Borg backups will also include dumps of your Postgres database. An alternative solution for backing up the Postgres database is [postgres backup](configuring-playbook-postgres-backup.md). If you decide to go with another solution, you can disable Postgres-backup support for Borg using the `matrix_backup_borg_postgresql_enabled` variable.
## Prerequisites
1. Create a new SSH key:
```bash
ssh-keygen -t ed25519 -N '' -f matrix-borg-backup -C matrix
```
This can be done on any machine and you don't need to place the key in the `.ssh` folder. It will be added to the Ansible config later.
2. Add the **public** part of this SSH key (the `matrix-borg-backup.pub` file) to your borg provider/server:
If you plan to use a hosted solution, follow their instructions. If you have your own server, copy the key over:
```bash
# example to append the new PUBKEY contents, where:
# PUBKEY is path to the public key,
# USER is a ssh user on a provider / server
# HOST is a ssh host of a provider / server
cat PUBKEY | ssh USER@HOST 'dd of=.ssh/authorized_keys oflag=append conv=notrunc'
```
## Adjusting the playbook configuration
Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable borg backup:
```yaml
matrix_backup_borg_enabled: true
matrix_backup_borg_location_repositories:
- USER@HOST:REPO
matrix_backup_borg_storage_encryption_passphrase: "PASSPHRASE"
matrix_backup_borg_ssh_key_private: |
PRIVATE KEY
```
where:
* USER - SSH user of a provider/server
* HOST - SSH host of a provider/server
* REPO - borg repository name, it will be initialized on backup start, eg: `matrix`
* PASSPHRASE - passphrase used for encrypting backups, you may generate it with `pwgen -s 64 1` or use any password manager
* PRIVATE KEY - the content of the **private** part of the SSH key you created before
To backup without encryption, add `matrix_backup_borg_encryption: 'none'` to your vars. This will also enable the `matrix_backup_borg_unknown_unencrypted_repo_access_is_ok` variable.
`matrix_backup_borg_location_source_directories` defines the list of directories to back up: it's set to `{{ matrix_base_data_path }}` by default, which is the base directory for every service's data, such as Synapse, Postgres and the bridges. You might want to exclude certain directories or file patterns from the backup using the `matrix_backup_borg_location_exclude_patterns` variable.
Check the `roles/matrix-backup-borg/defaults/main.yml` file for the full list of available options.
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
# Setting up Buscarron (optional)
The playbook can install and configure [buscarron](https://gitlab.com/etke.cc/buscarron) for you.
It's a bot you can use to setup **your own helpdesk on matrix**
It's a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) matrix room
## Registering the bot user
By default, the playbook will set up the bot with a username like this: `@bot.buscarron:DOMAIN`.
(to use a different username, adjust the `matrix_bot_buscarron_login` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.buscarron password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_buscarron_enabled: true
# Adjust this to whatever password you chose when registering the bot user
matrix_bot_buscarron_password: PASSWORD_FOR_THE_BOT
# Adjust accepted forms
matrix_bot_buscarron_forms:
- name: contact # (mandatory) Your form name, will be used as endpoint, eg: buscarron.DOMAIN/contact
room: "!yourRoomID:DOMAIN" # (mandatory) Room ID where form submission will be posted
redirect: https://DOMAIN # (mandatory) To what page user will be redirected after the form submission
ratelimit: 1r/m # (optional) rate limit of the form, format: <max requests>r/<interval:s,m>, eg: 1r/s or 54r/m
extensions: [] # (optional) list of form extensions (not used yet)
matrix_bot_buscarron_spam_hosts: [] # (optional) list of email domains/hosts that should be rejected automatically
matrix_bot_buscarron_spam_emails: [] # (optional) list of email addresses that should be rejected automatically
```
You will also need to add a DNS record so that buscarron can be accessed.
By default buscarron will use https://buscarron.DOMAIN so you will need to create an CNAME record for `buscarron`.
See [Configuring DNS](configuring-dns.md).
If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):
```yaml
matrix_server_fqn_buscarron: "form.{{ matrix_domain }}"
```
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
To use the bot, invite the `@bot.buscarron:DOMAIN` to the room you specified in a config, after that any point your form to the form url, example for the `contact` form:
```html
<form method="POST" action="https://buscarron.DOMAIN/contact">
<!--your fields-->
</form>
```
You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/buscarron).
# Setting up matrix-registration-bot (optional)
The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
The bot allows you to easily **create and manage registration tokens**. It can be used for an invitation-based server,
where you invite someone by sending them a registration token. They can register as normal but have to provide a valid
registration token in a final step of the registration.
See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it
does and why it might be useful to you.
## Registering the bot user
By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:DOMAIN`.
(to use a different username, adjust the `matrix_bot_matrix_registration_bot_matrix_user_id_localpart` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-registration-bot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Obtaining an admin access token
In order to use the bot you need to add an admin user's access token token to the configuration. As you created an admin user for the
bot, it is recommended to obtain an access token by logging into Element/Schildichat with the bot account
(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
You can expand "Access token" to copy it.
![Obatining an admin access token with Element](assets/obtain_admin_access_token_element.png)
**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_matrix_registration_bot_enabled: true
# Token obtained via logging into the bot account (see above)
matrix_bot_matrix_registration_bot_bot_access_token: "syt_bW9hbm9z_XXXXXXXXXXXXXr_2kuzbE"
# Enables registration
matrix_synapse_enable_registration: true
# Restrict registration to users with a token
matrix_synapse_registration_requires_token: true
```
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
To use the bot, create a **non-encrypted** room and invite `@bot.matrix-registration-bot:DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
In this room send `help` and the bot will reply with all options.
You can also refer to the upstream [Usage documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands).
If you have any questions, or if you need help setting it up, read the [troublshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md)
or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).
......@@ -16,10 +16,29 @@ Refer to the [official instructions](https://matrix-org.github.io/matrix-hooksho
2. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
3. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-matrix-aux-role) explained below.
4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
5. Refer to [Hookshot's official instructions](https://matrix-org.github.io/matrix-hookshot/usage.html) to start using the bridge. Note that the different listeners are bound to certain paths (see `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/matrix-bridge-hookshot/tasks/init.yml)): by default webhooks root is `/hookshot/webhooks/`.
5. Refer to [Hookshot's official instructions](https://matrix-org.github.io/matrix-hookshot/usage.html) to start using the bridge. **Important:** Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](urls-for-bridges-setup) below.
Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
### URLs for bridges setup
Unless indicated otherwise, the following endpoints are reachable on your `matrix.` subdomain (if the feature is enabled).
| listener | default path | variable | used as |
|---|---|---|---|
| webhooks | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | generics, GitHub "Webhook URL", etc. |
| github oauth | `/hookshot/webhooks/oauth` | `matrix_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | JIRA OAuth |
| figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |
| provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) |
| appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
| widgets | `/hookshot/widgetapi/` | `/matrix_hookshot_widgets_endpoint` | Widgets |
| metrics | `/hookshot/metrics/` (on `stats.` subdomain) | `matrix_hookshot_metrics_endpoint` | Prometheus |
See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/matrix-bridge-hookshot/tasks/init.yml).
The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
### Manage GitHub Private Key with matrix-aux role
The GitHub bridge requires you to install a private key file. This can be done in multiple ways:
......
......@@ -49,4 +49,19 @@ If you want to use the relay-bot feature ([relay bot documentation](https://docs
```yaml
matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN
matrix_mautrix_telegram_configuration_extension_yaml: |
bridge:
permissions:
'*': relaybot
```
You might also want to give permissions to administrate the bot:
```yaml
matrix_mautrix_telegram_configuration_extension_yaml: |
bridge:
permissions:
'@user:DOMAIN': admin
```
More details about permissions in this example:
https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
......@@ -4,8 +4,8 @@
[matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md)
bridge supported by the playbook.
The playbook can install and configure
[mx-puppet-slack](https://github.com/Sorunome/mx-puppet-slack) for you.
The playbook can install and configure [Beeper](https://www.beeper.com/)-maintained fork of
[mx-puppet-slack](https://gitlab.com/beeper/mx-puppet-monorepo) for you.
See the project page to learn what it does and why it might be useful to you.
......
......@@ -31,7 +31,7 @@ matrix_dimension_admins:
- "@user2:{{ matrix_domain }}"
```
Admin interface is accessible at `https://dimension.<your-domain>/riot-app/admin` after logging in to element and opening it in any room via "Edit widgets, bridges & bots" and then clicking the "settings"-icon in the upper right corner.
The admin interface is accessible within Element by accessing it in any room and clicking the cog wheel/settings icon in the top right. Currently, Dimension can be opened in Element by the "Add widgets, bridges, & bots" link in the room information.
## Access token
......
# Adjusting ma1sd Identity Server configuration (optional)
By default, this playbook configures an [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you.
The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you.
ma1sd, being an Identity Server, is not strictly needed. It is only used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some [enhanced features](https://github.com/ma1uta/ma1sd/#features).
This server is private by default, potentially at the expense of user discoverability.
*ma1sd is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.*
**Note**: enabling ma1sd (which is also the default), means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
**Note**: enabling ma1sd, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
## Disabling ma1sd
ma1sd, being an Identity Server, is not strictly needed. It is only used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some [enhanced features](https://github.com/ma1uta/ma1sd/#features).
If you'd like for the playbook to not install ma1sd (or to uninstall it if it was previously installed), you can disable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
To enable ma1sd, use the following additional configuration in your `vars.yml` file:
```yaml
matrix_ma1sd_enabled: false
matrix_ma1sd_enabled: true
```
## Matrix.org lookup forwarding
To ensure maximum discovery, you can make your identity server also forward lookups to the central matrix.org Identity server (at the cost of potentially leaking all your contacts information).
......
......@@ -2,6 +2,9 @@
The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you.
For a more complete backup solution (one that includes not only Postgres, but also other configuration/data files), you may wish to look into [borg backup](configuring-playbook-backup-borg.md) instead.
## Adjusting the playbook configuration
Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable Postgres backup:
......
......@@ -25,6 +25,8 @@ matrix_grafana_default_admin_password: "some_strong_password_chosen_by_you"
By default, a [Grafana](https://grafana.com/) web user-interface will be available at `https://stats.<your-domain>`.
The retention policy of Prometheus metrics is [15 days by default](https://prometheus.io/docs/prometheus/latest/storage/#operational-aspects). Older data gets deleted automatically.
## What does it do?
......
......@@ -47,8 +47,6 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) (optional)
- [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md) (optional)
- [Adjusting SSL certificate retrieval](configuring-playbook-ssl-certificates.md) (optional, advanced)
- [Serving your base domain using this playbook's nginx server](configuring-playbook-base-domain-serving.md) (optional)
......@@ -69,11 +67,14 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Adjusting email-sending settings](configuring-playbook-email.md) (optional)
- [Setting up Hydrogen](configuring-playbook-client-hydrogen.md) - a new lightweight matrix client with legacy and mobile browser support (optional)
- [Setting up Cinny](configuring-playbook-client-cinny.md) - a web client focusing primarily on simple, elegant and secure interface (optional)
### Authentication and user-related
- [Setting up an ma1sd Identity Server](configuring-playbook-ma1sd.md) (optional)
- [Setting up Synapse Admin](configuring-playbook-synapse-admin.md) (optional)
- [Setting up matrix-registration](configuring-playbook-matrix-registration.md) (optional)
......@@ -144,12 +145,23 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Setting up matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) - a bot to remind you about stuff (optional)
- [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) - a bot to create and manage registration tokens to invite users (optional)
- [Setting up honoroit](configuring-playbook-bot-honoroit.md) - a helpdesk bot (optional)
- [Setting up Go-NEB](configuring-playbook-bot-go-neb.md) - an extensible multifunctional bot (optional)
- [Setting up Mjolnir](configuring-playbook-bot-mjolnir.md) - a moderation tool/bot (optional)
- [Setting up Buscarron](configuring-playbook-bot-buscarron.md) - a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) Matrix room (optional)
### Backups
- [Setting up borg backup](configuring-playbook-backup-borg.md) - a full Matrix server backup solution, including the Postgres database (optional)
- [Setting up postgres backup](configuring-playbook-postgres-backup.md) - a Postgres-database backup solution (note: does not include other files) (optional)
### Other specialized services
......
......@@ -46,7 +46,7 @@ If you decide to go this route, you don't need to read ahead in this document. W
If you're managing the base domain by yourself somehow, you'll need to set up serving of some `/.well-known/matrix/*` files from it via HTTPS.
To make things easy for you to set up, this playbook generates and hosts 2 well-known files on the Matrix domain's server (e.g. `https://matrix.example.com/.well-known/matrix/server` and `https://matrix.example.com/.well-known/matrix/client`), even though this is the wrong place to host them.
To make things easy for you to set up, this playbook generates and hosts 2 well-known files on the Matrix domain's server. The files are generated at `/matrix/static-files/.well-known/matrix/` and hosted at `https://matrix.example.com/.well-known/matrix/server` and `https://matrix.example.com/.well-known/matrix/client`, even though this is the wrong place to host them.
You have 3 options when it comes to installing the files on the base domain's server:
......@@ -116,8 +116,22 @@ server {
**For Caddy 2**, it would be something like this:
```caddy
reverse_proxy /.well-known/matrix/* https://matrix.DOMAIN {
header_up Host {http.reverse_proxy.upstream.hostport}
DOMAIN.com {
@wellknown {
path /.well-known/matrix/*:x
}
handle @wellknown {
reverse_proxy https://matrix.DOMAIN.com {
header_up Host {http.reverse_proxy.upstream.hostport}
}
}
# Configration for the base domain goes here
# handle {