Run codespell --write-changes
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
This commit is contained in:
committed by
Slavi Pantaleev
parent
0152758f5d
commit
3653f9f89b
@ -9,7 +9,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
# Table of Contents
|
||||
|
||||
## ⬇️ Installaton guides <!-- NOTE: the 🚀 emoji is used by "Getting started" on README.md -->
|
||||
## ⬇️ Installation guides <!-- NOTE: the 🚀 emoji is used by "Getting started" on README.md -->
|
||||
|
||||
There are two installation guides available for beginners and advanced users.
|
||||
|
||||
|
@ -117,7 +117,7 @@ Then, to be asked for the password whenever running an `ansible-playbook` comman
|
||||
|
||||
#### 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:
|
||||
Because you're `root` in the container running Ansible and this likely differs from the owner (your regular user account) of the playbook directory outside of the container, certain playbook features which use `git` locally may report warnings such as:
|
||||
|
||||
> fatal: unsafe repository ('/work' is owned by someone else)
|
||||
> To add an exception for this directory, call:
|
||||
|
@ -95,13 +95,13 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
|
||||
## Usage
|
||||
|
||||
If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com` you have succesfully installed Draupnir for All and can now start using it.
|
||||
If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com` you have successfully installed Draupnir for All and can now start using it.
|
||||
|
||||
The installation of Draupnir for all in this playbook is very much Alpha quality. Usage-wise, Draupnir for all is almost identical to Draupnir bot mode.
|
||||
|
||||
### 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.
|
||||
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` recommendation. Using the chat is recommended.
|
||||
|
||||
The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297))
|
||||
|
||||
|
@ -57,7 +57,7 @@ matrix_bot_chatgpt_openai_api_key: 'API_KEY_HERE'
|
||||
|
||||
matrix_bot_chatgpt_matrix_access_token: 'ACCESS_TOKEN_HERE'
|
||||
|
||||
# Configuring the system promt used, needed if the bot is used for special tasks.
|
||||
# Configuring the system prompt used, needed if the bot is used for special tasks.
|
||||
# More information: https://github.com/mustvlad/ChatGPT-System-Prompts
|
||||
matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a large language model trained by OpenAI.'
|
||||
```
|
||||
|
@ -242,7 +242,7 @@ For Draupnir to do its job, you need to [give it permissions](https://the-draupn
|
||||
|
||||
We recommend **subscribing to a public [policy list](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists)** using the [watch command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-policy-lists#using-draupnirs-watch-command-to-subscribe-to-policy-rooms).
|
||||
|
||||
Polcy lists are maintained in Matrix rooms. A popular policy list is maintained in the public `#community-moderation-effort-bl:neko.dev` room.
|
||||
Policy lists are maintained in Matrix rooms. A popular policy list is maintained in the public `#community-moderation-effort-bl:neko.dev` room.
|
||||
|
||||
You can tell Draupnir to subscribe to it by sending the following command to the Management Room: `!draupnir watch #community-moderation-effort-bl:neko.dev`
|
||||
|
||||
|
@ -77,7 +77,7 @@ Send `help` to the bot to see the available commands.
|
||||
|
||||
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).
|
||||
If you have any questions, or if you need help setting it up, read the [troubleshooting 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:
|
||||
|
||||
|
@ -167,7 +167,7 @@ To `matrix_hookshot_container_labels_metrics_middleware_basic_auth_users`, set t
|
||||
|
||||
#### Enable Grafana (optional)
|
||||
|
||||
Probably you wish to enable Grafana along with Prometheus for generating graphs of the metics.
|
||||
Probably you wish to enable Grafana along with Prometheus for generating graphs of the metrics.
|
||||
|
||||
To enable Grafana, see [this section](configuring-playbook-prometheus-grafana.md#adjusting-the-playbook-configuration-grafana) for instructions.
|
||||
|
||||
|
@ -70,7 +70,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
|
||||
## Usage
|
||||
|
||||
Follow the [mautrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).
|
||||
Follow the [mautrix-imessage documentation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
@ -30,7 +30,7 @@ These **clients will use their own embedded Element Call frontend**, so **self-h
|
||||
|
||||
💡 A reason you may wish to continue installing the Element Call frontend (despite Matrix clients not making use of it), is if you need to use it standalone - directly via a browser (without a Matrix client). Note that unless you [allow guest accounts to use Element Call](#allowing-guests-to-use-element-call-optional), you will still need a Matrix user account **on the same homeserver** to be able to use Element Call.
|
||||
|
||||
The playbook makes a distiction between enabling Element Call (`matrix_element_call_enabled`) and enabling the Matrix RTC Stack (`matrix_rtc_enabled`). Enabling Element Call automatically enables the Matrix RTC stack. Because installing the Element Call frontend is now unnecessary, **we recommend only installing the Matrix RTC stack, without the Element Call frontend**.
|
||||
The playbook makes a distinction between enabling Element Call (`matrix_element_call_enabled`) and enabling the Matrix RTC Stack (`matrix_rtc_enabled`). Enabling Element Call automatically enables the Matrix RTC stack. Because installing the Element Call frontend is now unnecessary, **we recommend only installing the Matrix RTC stack, without the Element Call frontend**.
|
||||
|
||||
| Description / Variable | Element Call frontend | [LiveKit Server](configuring-playbook-livekit-server.md) | [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) |
|
||||
|------------------------|-----------------------|----------------|---------------------|
|
||||
|
@ -41,7 +41,7 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
|
||||
|
||||
## 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.
|
||||
- ⚠️ 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 with Matrix Authentication Service yet.
|
||||
|
||||
- ❌ **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.
|
||||
|
||||
@ -61,7 +61,7 @@ This section details what you can expect when switching to the Matrix Authentica
|
||||
|
||||
- ⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) is **possible**, but requires **some playbook-assisted manual work**. Migration is **reversible with no or minor issues if done quickly enough**, but as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.
|
||||
|
||||
- ⚠️ Delegating user authentication to MAS causes **your Synapse server to be completely dependant on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch.
|
||||
- ⚠️ Delegating user authentication to MAS causes **your Synapse server to be completely dependent on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch.
|
||||
|
||||
- ⚠️ If you've got [OIDC configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to migrate your OIDC configuration to MAS by adding an [Upstream OAuth2 configuration](#upstream-oauth2-configuration).
|
||||
|
||||
@ -85,7 +85,7 @@ For new homeservers (which don't have any users in their Synapse database yet),
|
||||
|
||||
### Existing homeserver
|
||||
|
||||
Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
|
||||
Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating with Matrix Authentication Service yet.
|
||||
|
||||
For existing Synapse homeservers:
|
||||
|
||||
|
@ -13,7 +13,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
The playbook can install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you.
|
||||
|
||||
In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment.
|
||||
In short, it's a sort of automation and firewalling service, which is helpful if you're installing Matrix services in a controlled corporate environment.
|
||||
|
||||
See the project's [documentation](https://github.com/devture/matrix-corporal/blob/main/README.md) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
@ -60,7 +60,7 @@ To `matrix_media_repo_container_labels_traefik_metrics_middleware_basic_auth_use
|
||||
|
||||
#### Enable Grafana (optional)
|
||||
|
||||
Probably you wish to enable Grafana along with Prometheus for generating graphs of the metics.
|
||||
Probably you wish to enable Grafana along with Prometheus for generating graphs of the metrics.
|
||||
|
||||
To enable Grafana, see [this section](configuring-playbook-prometheus-grafana.md#adjusting-the-playbook-configuration-grafana) for instructions.
|
||||
|
||||
|
@ -115,7 +115,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
|
||||
## Usage
|
||||
|
||||
To receive push notifications with UnifiedPush from the ntfy server, you need to **install [the ntfy Android app](https://docs.ntfy.sh/subscribe/phone/)** which works as the Distrubutor, **log in to the account on the ntfy app** if you have enabled the access control, and then **configure a UnifiedPush-compatible Matrix client**. After setting up the ntfy Android app, the Matrix client listens to it, and push notitications are "distributed" from it.
|
||||
To receive push notifications with UnifiedPush from the ntfy server, you need to **install [the ntfy Android app](https://docs.ntfy.sh/subscribe/phone/)** which works as the Distributor, **log in to the account on the ntfy app** if you have enabled the access control, and then **configure a UnifiedPush-compatible Matrix client**. After setting up the ntfy Android app, the Matrix client listens to it, and push notifications are "distributed" from it.
|
||||
|
||||
For details about installing and configuring the ntfy Android app, take a look at [this section](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#install-the-ntfy-androidios-app) on the role's documentation.
|
||||
|
||||
|
@ -15,7 +15,7 @@ By default, the playbook retrieves and automatically renews free SSL certificate
|
||||
|
||||
**Notes**:
|
||||
- This guide is intended to be referred for configuring the integrated Traefik server with regard to SSL certificates retrieval. If you're using [your own webserver](configuring-playbook-own-webserver.md), consult its documentation about how to configure it.
|
||||
- Let's Encrypt ends the expiration notification email service on June 4, 2025 (see: [the official announcement](https://letsencrypt.org/2025/01/22/ending-expiration-emails/)), and it recommends using a third party service for those who want to receive expiriation notifications. If you are looking for a self-hosting service, you may be interested in a monitoring tool such as [Update Kuma](https://github.com/louislam/uptime-kuma/).
|
||||
- Let's Encrypt ends the expiration notification email service on June 4, 2025 (see: [the official announcement](https://letsencrypt.org/2025/01/22/ending-expiration-emails/)), and it recommends using a third party service for those who want to receive expiration notifications. If you are looking for a self-hosting service, you may be interested in a monitoring tool such as [Update Kuma](https://github.com/louislam/uptime-kuma/).
|
||||
|
||||
The [Mother-of-All-Self-Hosting (MASH)](https://github.com/mother-of-all-self-hosting/mash-playbook) Ansible playbook can be used to install and manage an Uptime Kuma instance. See [this page](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/uptime-kuma.md) for the instruction to install it with the MASH playbook. If you are wondering how to use the MASH playbook for your Matrix server, refer [this page](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/setting-up-services-on-mdad-server.md).
|
||||
|
||||
|
@ -53,7 +53,7 @@ You may also consider [tweaking the number of workers of each type](#controlling
|
||||
|
||||
##### 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.
|
||||
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 requester's IP address, specialized load-balancing routes to **4 different types of specialized workers** based on **smarter criteria** — the access token (username) of the requester and/or on the resource (room, etc.) being requested.
|
||||
|
||||
The playbook supports these **4 types** of specialized workers:
|
||||
|
||||
|
@ -235,7 +235,7 @@ Running Matrix on a server with 1GB of memory is possible (especially if you dis
|
||||
|
||||
**We recommend starting with a server having at least 2GB of memory** and even then using it sparingly. If you know for sure you'll be joining various large rooms, etc., then going for 4GB of memory or more is a good idea.
|
||||
|
||||
Besides the regular Matrix stuff, we also support things like video-conferencing using [Jitsi](configuring-playbook-jitsi.md) and other additional services which (when installed) may use up a lot of memory. Things do add up. Besides the Synapse Matrix server, Jitsi is especially notorious for consuming a lot of resources. If you plan on running Jitsi, we recommend a server with at least 2GB of memory (preferrably more). See our [Jitsi documentation page](configuring-playbook-jitsi.md) to learn how to optimize its memory/CPU usage.
|
||||
Besides the regular Matrix stuff, we also support things like video-conferencing using [Jitsi](configuring-playbook-jitsi.md) and other additional services which (when installed) may use up a lot of memory. Things do add up. Besides the Synapse Matrix server, Jitsi is especially notorious for consuming a lot of resources. If you plan on running Jitsi, we recommend a server with at least 2GB of memory (preferably more). See our [Jitsi documentation page](configuring-playbook-jitsi.md) to learn how to optimize its memory/CPU usage.
|
||||
|
||||
### Can I run this in an LXC container?
|
||||
|
||||
@ -362,7 +362,7 @@ Configuration variables are defined in multiple places in this playbook and are
|
||||
|
||||
You can discover the variables you can override in each role (`roles/*/*/defaults/main.yml`).
|
||||
|
||||
As described in [How is the effective configuration determined?](#how-is-the-effective-configuration-determined), these role-defaults may be overriden by values defined in `group_vars/matrix_servers`.
|
||||
As described in [How is the effective configuration determined?](#how-is-the-effective-configuration-determined), these role-defaults may be overridden by values defined in `group_vars/matrix_servers`.
|
||||
|
||||
Refer to both of these for inspiration. Still, as mentioned in [Configuring the playbook](configuring-playbook.md), you're only ever supposed to edit your own `inventory/host_vars/matrix.example.com/vars.yml` file and nothing else inside the playbook (unless you're meaning to contribute new features).
|
||||
|
||||
|
@ -42,7 +42,7 @@ This is because with SRV federation, some servers / tools (one of which being th
|
||||
|
||||
### Tell Traefik which certificate to serve for the federation endpoint
|
||||
|
||||
Now that the federation endpoint is not bound to a domain anymore we need to explicitely tell Traefik to use a wildcard certificate in addition to one containing the base name.
|
||||
Now that the federation endpoint is not bound to a domain anymore we need to explicitly tell Traefik to use a wildcard certificate in addition to one containing the base name.
|
||||
|
||||
This is because the Matrix specification expects the federation endpoint to be served using a certificate compatible with the base domain, however, the other resources on the endpoint still need a valid certificate to work.
|
||||
|
||||
|
Reference in New Issue
Block a user