mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2025-01-15 20:53:12 +01:00
Update docs for homeserver implementations (Conduit, Dendrite, and Synapse) (#3926)
* Update docs for Dendrite and Synapse: adopt the common section "Extending the configuration" Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-synapse.md: move down the section "Extending the configuration" Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for Dendrite and Synapse: remove redundant descriptions Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-conduit.md: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for Conduit and Dendrite: replace "Notes" with "Warnings" plus the warning symbol The information is important and should deserve clear attention. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-synapse.md: reorganize sections for adjusting the playbook configuration As the section for Synapse Admin is not related to adjusting the configuration, it was moved out of the it Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-synapse.md: on Synapse Admin Based on docs/configuring-playbook-bot-draupnir.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update URLs of the forked Dendrite repository Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for Conduit and Dendrite: use the common descriptions for introductions - Edit the instruction for adjusting the configuration Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-synapse-admin.md: update the URL of the Dendrite documentation Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-synapse.md: add the sections "Installing" and "Usage" Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-conduit.md: copy an instruction from roles/custom/matrix-conduit/defaults/main.yml Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for Conduit and Dendrite: fix capitalization Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
This commit is contained in:
Suguru Hirahara
GitHub
parent
4b9b6bf553
commit
b017ffd853
@ -1,21 +1,40 @@
|
||||
# Configuring Conduit (optional)
|
||||
|
||||
By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Conduit](https://conduit.rs).
|
||||
The playbook can install and configure the [Conduit](https://conduit.rs) Matrix server for you.
|
||||
|
||||
**Notes**:
|
||||
See the project's [documentation](https://docs.conduit.rs/) to learn what it does and why it might be useful to you.
|
||||
|
||||
By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
|
||||
|
||||
⚠️ **Warnings**:
|
||||
|
||||
- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Conduit). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
|
||||
|
||||
- **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
|
||||
- **Homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To use Conduit, you **generally** need to add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
To use Conduit, you **generally** need to adjust the `matrix_homeserver_implementation: synapse` configuration on your `inventory/host_vars/matrix.example.com/vars.yml` file as below:
|
||||
|
||||
```yaml
|
||||
matrix_homeserver_implementation: conduit
|
||||
```
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the server.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-conduit/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
- `roles/custom/matrix-conduit/templates/conduit.toml.j2` for the server's default configuration
|
||||
|
||||
If you'd like to have your own different configuration, feel free to copy and paste the original files into your inventory (e.g. in `inventory/host_vars/matrix.example.com/`) and then change the specific host's `vars.yaml` file like this:
|
||||
|
||||
```yaml
|
||||
matrix_conduit_template_conduit_config: "{{ playbook_dir }}/inventory/host_vars/matrix.example.com/conduit.toml.j2"
|
||||
```
|
||||
|
||||
## Creating the first user account
|
||||
|
||||
Since it is difficult to create the first user account on Conduit (see [famedly/conduit#276](https://gitlab.com/famedly/conduit/-/issues/276) and [famedly/conduit#354](https://gitlab.com/famedly/conduit/-/merge_requests/354)) and it does not support [registering users](registering-users.md) (via the command line or via the playbook) like Synapse and Dendrite do, we recommend the following procedure:
|
||||
|
||||
@ -1,34 +1,54 @@
|
||||
# Configuring Dendrite (optional)
|
||||
|
||||
By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Dendrite](https://github.com/matrix-org/dendrite).
|
||||
The playbook can install and configure the [Dendrite](https://github.com/element-hq/dendrite) Matrix server for you.
|
||||
|
||||
**Notes**:
|
||||
See the project's [documentation](https://element-hq.github.io/dendrite/) to learn what it does and why it might be useful to you.
|
||||
|
||||
By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
|
||||
|
||||
⚠️ **Warnings**:
|
||||
|
||||
- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Dendrite). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
|
||||
|
||||
- **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
|
||||
- **Homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To use Dendrite, you **generally** need to add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
To use Dendrite, you **generally** need to adjust the `matrix_homeserver_implementation: synapse` configuration on your `inventory/host_vars/matrix.example.com/vars.yml` file as below:
|
||||
|
||||
```yaml
|
||||
matrix_homeserver_implementation: dendrite
|
||||
```
|
||||
|
||||
The playbook provides lots of customization variables you could use to change Dendrite's settings.
|
||||
### Extending the configuration
|
||||
|
||||
Their defaults are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite.yaml.j2) template.
|
||||
There are some additional things you may wish to configure about the server.
|
||||
|
||||
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
|
||||
Take a look at:
|
||||
|
||||
Alternatively, **if there is no pre-defined variable** for a Dendrite setting you wish to change:
|
||||
- `roles/custom/matrix-dendrite/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
- `roles/custom/matrix-dendrite/templates/dendrite.yaml.j2` for the server's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_dendrite_configuration_extension_yaml` variable
|
||||
|
||||
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Dendrite's various settings that rarely get used.
|
||||
For example, to override some Dendrite settings, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
- or, you can **extend and override the default configuration** ([`dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite.yaml.j2)) by making use of the `matrix_dendrite_configuration_extension_yaml` variable. You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
|
||||
|
||||
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_dendrite_configuration` (or `matrix_dendrite_configuration_yaml`). You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
|
||||
```yaml
|
||||
matrix_dendrite_configuration_extension_yaml: |
|
||||
# Your custom YAML configuration for Dendrite goes here.
|
||||
# This configuration extends the default starting configuration (`matrix_dendrite_configuration_yaml`).
|
||||
#
|
||||
# You can override individual variables from the default configuration, or introduce new ones.
|
||||
#
|
||||
# If you need something more special, you can take full control by
|
||||
# completely redefining `matrix_dendrite_configuration_yaml`.
|
||||
#
|
||||
# Example configuration extension follows:
|
||||
#
|
||||
server_notices:
|
||||
system_mxid_localpart: notices
|
||||
system_mxid_display_name: "Server Notices"
|
||||
system_mxid_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ"
|
||||
room_name: "Server Notices"
|
||||
```
|
||||
|
||||
## Installing
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
The playbook can install and configure [etkecc/synapse-admin](https://github.com/etkecc/synapse-admin) (a [feature-rich](https://github.com/etkecc/synapse-admin#fork-differences) fork of [Awesome-Technologies/synapse-admin](https://github.com/Awesome-Technologies/synapse-admin), community room: [#synapse-admin:etke.cc](https://matrix.to/#/#synapse-admin:etke.cc)) for you.
|
||||
|
||||
synapse-admin is a web UI tool you can use to **administrate users, rooms, media, etc. on your Matrix server**. It's designed to work with the Synapse homeserver implementation and WON'T work with Dendrite because [Dendrite Admin API](https://matrix-org.github.io/dendrite/administration/adminapi) differs from [Synapse Admin API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/).
|
||||
synapse-admin is a web UI tool you can use to **administrate users, rooms, media, etc. on your Matrix server**. It's designed to work with the Synapse homeserver implementation and WON'T work with Dendrite because [Dendrite Admin API](https://element-hq.github.io/dendrite/administration/adminapi) differs from [Synapse Admin API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/).
|
||||
|
||||
💡 **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.
|
||||
|
||||
|
||||
@ -2,21 +2,9 @@
|
||||
|
||||
By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, so that it works for the general case. If that's okay, you can skip this document.
|
||||
|
||||
The playbook provides lots of customization variables you could use to change Synapse's settings.
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Their defaults are defined in [`roles/custom/matrix-synapse/defaults/main.yml`](../roles/custom/matrix-synapse/defaults/main.yml) and they ultimately end up in the generated `/matrix/synapse/config/homeserver.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2`](../roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2) template.
|
||||
|
||||
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
|
||||
|
||||
Alternatively, **if there is no pre-defined variable** for a Synapse setting you wish to change:
|
||||
|
||||
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Synapse's various settings that rarely get used.
|
||||
|
||||
- or, you can **extend and override the default configuration** ([`homeserver.yaml.j2`](../roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2)) by making use of the `matrix_synapse_configuration_extension_yaml` variable. You can find information about this in [`roles/custom/matrix-synapse/defaults/main.yml`](../roles/custom/matrix-synapse/defaults/main.yml).
|
||||
|
||||
- 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
|
||||
### 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).
|
||||
|
||||
@ -30,7 +18,7 @@ matrix_synapse_workers_preset: one-of-each
|
||||
|
||||
By default, this enables the `one-of-each` [worker preset](#worker-presets), but you may wish to use another preset or [control the number of worker instances](#controlling-the-number-of-worker-instances).
|
||||
|
||||
### Worker presets
|
||||
#### Worker presets
|
||||
|
||||
We support a few configuration presets (`matrix_synapse_workers_preset: one-of-each` being the default configuration right now):
|
||||
|
||||
@ -40,7 +28,7 @@ We support a few configuration presets (`matrix_synapse_workers_preset: one-of-e
|
||||
|
||||
These presets represent a few common configurations. There are many worker types which can be mixed and matched based on your needs.
|
||||
|
||||
#### Generic workers
|
||||
##### Generic workers
|
||||
|
||||
Previously, the playbook only supported the most basic type of load-balancing. We call it **generic load-balancing** below, because incoming HTTP requests are sent to a generic worker. Load-balancing was done based on the requestor's IP address. This is simple, but not necessarily optimal. If you're accessing your account from multiple IP addresses (e.g. your mobile phone being on a different network than your PC), these separate requests may potentially be routed to different workers, each of which would need to cache roughly the same data.
|
||||
|
||||
@ -50,7 +38,7 @@ To use generic load-balancing, do not specify `matrix_synapse_workers_preset` to
|
||||
|
||||
You may also consider [tweaking the number of workers of each type](#controlling-the-number-of-worker-instances) from the default (one of each).
|
||||
|
||||
#### Specialized workers
|
||||
##### Specialized workers
|
||||
|
||||
The playbook now supports a smarter **specialized load-balancing** inspired by [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html). Instead of routing requests to one or more [generic workers](#generic-workers) based only on the requestor's IP adddress, specialized load-balancing routes to **4 different types of specialized workers** based on **smarter criteria** - the access token (username) of the requestor and/or on the resource (room, etc.) being requested.
|
||||
|
||||
@ -63,7 +51,7 @@ The playbook supports these **4 types** of specialized workers:
|
||||
|
||||
To use specialized load-balancing, consider enabling the `specialized-workers` [worker preset](#worker-presets) and potentially [tweaking the number of workers of each type](#controlling-the-number-of-worker-instances) from the default (one of each).
|
||||
|
||||
#### Controlling the number of worker instances
|
||||
##### Controlling the number of worker instances
|
||||
|
||||
If you'd like more customization power, you can start with one of the [worker presets](#worker-presets) and then tweak various `matrix_synapse_workers_*_count` variables manually.
|
||||
|
||||
@ -71,7 +59,7 @@ To find what variables are available for you to override in your own `vars.yml`
|
||||
|
||||
The only thing you **cannot** do is mix [generic workers](#generic-workers) and [specialized workers](#specialized-workers).
|
||||
|
||||
#### Effect of enabling workers on the rest of your server
|
||||
##### Effect of enabling workers on the rest of your server
|
||||
|
||||
When Synapse workers are enabled, the integrated [Postgres database is tuned](maintenance-postgres.md#tuning-postgresql), so that the maximum number of Postgres connections are increased from `200` to `500`. If you need to decrease or increase the number of maximum Postgres connections further, use the `postgres_max_connections` variable.
|
||||
|
||||
@ -79,11 +67,7 @@ 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
|
||||
### 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,7 +98,7 @@ matrix_synapse_oidc_providers:
|
||||
backchannel_logout_enabled: true # Optional
|
||||
```
|
||||
|
||||
## Customizing templates
|
||||
### 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,7 +136,37 @@ 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
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the server.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-synapse/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
- `roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2` for the server's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_synapse_configuration_extension_yaml` variable
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
### Synapse Admin
|
||||
|
||||
With [Synapse Admin](configuring-playbook-synapse-admin.md), certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace.
|
||||
|
||||
The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
@ -18,4 +18,4 @@ matrix_dendrite_report_stats: true # for dendrite
|
||||
|
||||
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.
|
||||
|
||||
See [Synapse's documentation](https://github.com/element-hq/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics) or [Dendrite's documentation](https://github.com/matrix-org/dendrite/blob/main/docs/FAQ.md#what-is-being-reported-when-enabling-phone-home-statistics) for the full list of statistics that are reported.
|
||||
See [Synapse's documentation](https://github.com/element-hq/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics) or [Dendrite's documentation](https://github.com/element-hq/dendrite/blob/main/docs/FAQ.md#what-is-being-reported-when-enabling-phone-home-statistics) for the full list of statistics that are reported.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user