diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index fff721410..985806d5b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -34,7 +34,7 @@ A clear and concise description of what you expected to happen. **Ansible:** If your problem appears to be with Ansible, tell us: -- where you run Ansible -- e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?) +- where you run Ansible — e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?) - what version of Ansible you're running (see `ansible --version`) -- [Other specialized services](configuring-playbook.md#other-specialized-services) - various services that don't fit any other categories +- [Other specialized services](configuring-playbook.md#other-specialized-services) — various services that don't fit any other categories ## 👨‍🔧 Maintenance @@ -63,7 +63,7 @@ If your server and services experience issues, feel free to come to [our support ## Other documentation pages -- ℹ️ **[FAQ](faq.md)** - various Frequently Asked Questions about Matrix, with a focus on this Ansible playbook +- ℹ️ **[FAQ](faq.md)** — various Frequently Asked Questions about Matrix, with a focus on this Ansible playbook diff --git a/docs/configuring-playbook-bot-baibot.md b/docs/configuring-playbook-bot-baibot.md index bdc29eafd..01984a4b7 100644 --- a/docs/configuring-playbook-bot-baibot.md +++ b/docs/configuring-playbook-bot-baibot.md @@ -123,7 +123,7 @@ Configuring `matrix_bot_baibot_config_initial_global_config_user_patterns` is op You are **not required** to define agents [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration) via Ansible. **To get started quickly**, you can **skip this section and define agents at runtime via chat commands** (following the bot's guidance). -Privileged users (like the [👮‍♂️ Administrator](#️-administrator-configuration), but potentially others too - see the upstream [🔒 access](https://github.com/etkecc/baibot/blob/main/docs/access.md) documentation) can **define agents dynamically at any time** via chat commands. +Privileged users (like the [👮‍♂️ Administrator](#️-administrator-configuration), but potentially others too — see the upstream [🔒 access](https://github.com/etkecc/baibot/blob/main/docs/access.md) documentation) can **define agents dynamically at any time** via chat commands. The Ansible role includes preset variables for easily enabling some [🤖 agents](https://github.com/etkecc/baibot/blob/main/docs/agents.md) on various [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md) (e.g. OpenAI, etc). @@ -250,7 +250,7 @@ You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot This provider allows you to use OpenAI-compatible API services like [OpenRouter](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openrouter), [Together AI](https://github.com/etkecc/baibot/blob/main/docs/providers.md#together-ai), etc. -Some of these popular services already have **shortcut** providers (see [supported providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md#supported-providers) leading to this one behind the scenes - this make it easier to get started. +Some of these popular services already have **shortcut** providers (see [supported providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md#supported-providers) leading to this one behind the scenes — this make it easier to get started. As of this moment, the playbook does not include presets for any of these services, so you'll need to [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset). @@ -305,7 +305,7 @@ Because these are [statically](https://github.com/etkecc/baibot/blob/main/docs/c 💡 To figure out what to put in the `config` section, refer to the [☁️ provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md) page, which contains **sample configuration YAML for each provider**. -As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md), defining them means they exist. To actually make use of them, they need to be configured as handlers globally or in a specific room - see [Mixing & matching models](https://github.com/etkecc/baibot/blob/main/docs/features.md#mixing--matching-models). +As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md), defining them means they exist. To actually make use of them, they need to be configured as handlers globally or in a specific room — see [Mixing & matching models](https://github.com/etkecc/baibot/blob/main/docs/features.md#mixing--matching-models). 💡 You may also wish to use these new agents for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers). diff --git a/docs/configuring-playbook-bridge-appservice-slack.md b/docs/configuring-playbook-bridge-appservice-slack.md index d21e1496a..4d602da35 100644 --- a/docs/configuring-playbook-bridge-appservice-slack.md +++ b/docs/configuring-playbook-bridge-appservice-slack.md @@ -100,7 +100,7 @@ To use the bridge, you need to send `/invite @slackbot:example.com` to invite th If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps: -- Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like `!qporfwt:example.com`. +- 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//details/`. - Issue a link command in the administration control room with these collected values as arguments: diff --git a/docs/configuring-playbook-bridge-heisenbridge.md b/docs/configuring-playbook-bridge-heisenbridge.md index a464a60f3..d3a08fb82 100644 --- a/docs/configuring-playbook-bridge-heisenbridge.md +++ b/docs/configuring-playbook-bridge-heisenbridge.md @@ -2,7 +2,7 @@ **Note**: bridging to [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) can also happen via the [matrix-appservice-irc](configuring-playbook-bridge-appservice-irc.md) bridge supported by the playbook. -The playbook can install and configure [Heisenbridge](https://github.com/hifi/heisenbridge) - the bouncer-style [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) bridge for you. +The playbook can install and configure [Heisenbridge](https://github.com/hifi/heisenbridge) — the bouncer-style [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) bridge for you. See the project's [documentation](https://github.com/hifi/heisenbridge/blob/master/README.md) to learn what it does and why it might be useful to you. You can also take a look at [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I). diff --git a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md index de3421147..96041c829 100644 --- a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md +++ b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md @@ -45,8 +45,8 @@ As mentioned above, the [mautrix-meta](https://github.com/mautrix/meta) bridge s The bridge can pull your Messenger messages via 3 different methods: - (`facebook`) Facebook via `facebook.com` -- (`facebook-tor`) Facebook via `facebookwkhpilnemxj7asaniu7vnjjbiltxjqhye3mhbshg7kx5tfyd.onion` ([Tor](https://www.torproject.org/)) - does not currently proxy media downloads -- (default) (`messenger`) Messenger via `messenger.com` - usable even without a Facebook account +- (`facebook-tor`) Facebook via `facebookwkhpilnemxj7asaniu7vnjjbiltxjqhye3mhbshg7kx5tfyd.onion` ([Tor](https://www.torproject.org/)) — does not currently proxy media downloads +- (default) (`messenger`) Messenger via `messenger.com` — usable even without a Facebook account You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variable. The playbook defaults to the `messenger` mode, because it's most universal (every Facebook user has a Messenger account, but the opposite is not true). diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index f6adfda36..f6b704133 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -8,9 +8,9 @@ See the project's [documentation](https://cactus.chat/docs/getting-started/intro The playbook contains 2 roles for configuring different pieces of the Cactus Comments system: -- `matrix-cactus-comments` — the backend appservice integrating with the Matrix homeserver +- `matrix-cactus-comments` — the backend appservice integrating with the Matrix homeserver -- `matrix-cactus-comments-client` — a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`) +- `matrix-cactus-comments-client` — a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`) You can enable whichever component you need (typically both). diff --git a/docs/configuring-playbook-conduit.md b/docs/configuring-playbook-conduit.md index f2fc70096..760307b22 100644 --- a/docs/configuring-playbook-conduit.md +++ b/docs/configuring-playbook-conduit.md @@ -42,7 +42,7 @@ matrix_conduit_template_conduit_config: "{{ playbook_dir }}/inventory/host_vars/ 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. Add `matrix_conduit_allow_registration: true` to your `vars.yml` the first time around, temporarily -2. Run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` - see [Installing](installing.md)) +2. Run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` — see [Installing](installing.md)) 3. Create your first user via Element Web or any other client which supports creating users 4. Get rid of `matrix_conduit_allow_registration: true` from your `vars.yml` 5. Run the playbook again (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-conduit,start` would be enough this time) diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index 64ef5e112..7b24cd335 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/docs/configuring-playbook-email2matrix.md @@ -89,14 +89,14 @@ matrix_email2matrix_matrix_mappings: where: -* MailboxName - local-part of the email address, through which emails are bridged to the room whose ID is defined with MatrixRoomId -* MatrixRoomId - internal ID of the room, to which received emails are sent as Matrix message -* MatrixHomeserverUrl - URL of your Matrix homeserver, through which to send Matrix messages. You can also set `MatrixHomeserverUrl` to the container URL where your homeserver's Client-Server API lives by using the `{{ matrix_addons_homeserver_client_api_url }}` variable -* MatrixUserId - the full ID of the sender user which sends bridged messages to the room. On this configuration it is `@email2matrix1:example.com` and `@email2matrix2:example.com` (where `example.com` is your base domain, not the `matrix.` domain) -* MatrixAccessToken - sender user's access token -* IgnoreSubject - if set to "true", the subject is not bridged to Matrix -* IgnoreBody - if set to "true", the message body is not bridged to Matrix -* SkipMarkdown - if set to "true", emails are bridged as plain text Matrix message instead of Markdown (actually HTML) +* MailboxName — local-part of the email address, through which emails are bridged to the room whose ID is defined with MatrixRoomId +* MatrixRoomId — internal ID of the room, to which received emails are sent as Matrix message +* MatrixHomeserverUrl — URL of your Matrix homeserver, through which to send Matrix messages. You can also set `MatrixHomeserverUrl` to the container URL where your homeserver's Client-Server API lives by using the `{{ matrix_addons_homeserver_client_api_url }}` variable +* MatrixUserId — the full ID of the sender user which sends bridged messages to the room. On this configuration it is `@email2matrix1:example.com` and `@email2matrix2:example.com` (where `example.com` is your base domain, not the `matrix.` domain) +* MatrixAccessToken — sender user's access token +* IgnoreSubject — if set to "true", the subject is not bridged to Matrix +* IgnoreBody — if set to "true", the message body is not bridged to Matrix +* SkipMarkdown — if set to "true", emails are bridged as plain text Matrix message instead of Markdown (actually HTML) Refer to the official documentation [here](https://github.com/devture/email2matrix/blob/master/docs/configuration.md). diff --git a/docs/configuring-playbook-external-postgres.md b/docs/configuring-playbook-external-postgres.md index e922c8299..ca49d985c 100644 --- a/docs/configuring-playbook-external-postgres.md +++ b/docs/configuring-playbook-external-postgres.md @@ -2,7 +2,7 @@ By default, this playbook would set up a PostgreSQL database server on your machine, running in a Docker container. If that's okay, you can skip this document. -**Note**: using **an external Postgres server is currently [not very seamless](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1682#issuecomment-1061461683) when it comes to enabling various other playbook services** - you will need to create a new database/credentials for each service and to point each service to its corresponding database using custom `vars.yml` configuration. **For the best experience with the playbook, stick to using the integrated Postgres server**. +**Note**: using **an external Postgres server is currently [not very seamless](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1682#issuecomment-1061461683) when it comes to enabling various other playbook services** — you will need to create a new database/credentials for each service and to point each service to its corresponding database using custom `vars.yml` configuration. **For the best experience with the playbook, stick to using the integrated Postgres server**. If you'd like to use an external Postgres server that you manage, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index 882d434e4..b9aca9819 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -12,8 +12,8 @@ See the project's [documentation](https://jitsi.github.io/handbook/) to learn wh 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 configuration, 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)). +- `4443/tcp` — RTP media fallback over TCP +- `10000/udp` — RTP media over UDP. Depending on your firewall/NAT configuration, 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 DNS records diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index c2f9d3132..7138ce3d3 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -65,15 +65,15 @@ If you'd like to change the default email templates used by ma1sd, take a look a To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) feature of ma1sd, you can make use of the following variables: -- `matrix_synapse_enable_registration` - to enable user-initiated registration in Synapse +- `matrix_synapse_enable_registration` — to enable user-initiated registration in Synapse -- `matrix_synapse_enable_registration_captcha` - to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring-captcha.md) documentation. +- `matrix_synapse_enable_registration_captcha` — to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring-captcha.md) documentation. -- `matrix_synapse_registrations_require_3pid` - a list of 3pid types (among `'email'`, `'msisdn'`) required by the Synapse server for registering +- `matrix_synapse_registrations_require_3pid` — a list of 3pid types (among `'email'`, `'msisdn'`) required by the Synapse server for registering -- variables prefixed with `matrix_ma1sd_container_labels_` (e.g. `matrix_ma1sd_container_labels_matrix_client_3pid_registration_enabled`) - to configure the Traefik reverse-proxy to capture and send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality +- variables prefixed with `matrix_ma1sd_container_labels_` (e.g. `matrix_ma1sd_container_labels_matrix_client_3pid_registration_enabled`) — to configure the Traefik reverse-proxy to capture and send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality -- `matrix_ma1sd_configuration_extension_yaml` - to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`. +- `matrix_ma1sd_configuration_extension_yaml` — to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`. **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). diff --git a/docs/configuring-playbook-matrix-authentication-service.md b/docs/configuring-playbook-matrix-authentication-service.md index 616ab54cc..ee8960352 100644 --- a/docs/configuring-playbook-matrix-authentication-service.md +++ b/docs/configuring-playbook-matrix-authentication-service.md @@ -1,6 +1,6 @@ # Setting up Matrix Authentication Service (optional) -The playbook can install and configure [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) (MAS) - a service operating alongside your existing [Synapse](./configuring-playbook-synapse.md) homeserver and providing [better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/). +The playbook can install and configure [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) (MAS) — a service operating alongside your existing [Synapse](./configuring-playbook-synapse.md) homeserver and providing [better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/). Matrix Authentication Service is an implementation of [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and still work in progress, tracked at the [areweoidcyet.com](https://areweoidcyet.com/) website. @@ -63,13 +63,13 @@ 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. -- ⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) does not currently seem to preserve the "admin" flag for users (as found in the Synapse database). All users are imported as non-admin - see [element-hq/matrix-authentication-service#3440](https://github.com/element-hq/matrix-authentication-service/issues/3440). You may need update the Matrix Authentication Service's database manually and adjust the `can_request_admin` column in the `users` table to `true` for users that need to be administrators (e.g. `UPDATE users SET can_request_admin = true WHERE username = 'someone';`) +- ⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) does not currently seem to preserve the "admin" flag for users (as found in the Synapse database). All users are imported as non-admin — see [element-hq/matrix-authentication-service#3440](https://github.com/element-hq/matrix-authentication-service/issues/3440). You may need update the Matrix Authentication Service's database manually and adjust the `can_request_admin` column in the `users` table to `true` for users that need to be administrators (e.g. `UPDATE users SET can_request_admin = true WHERE username = 'someone';`) - ⚠️ 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. - ⚠️ 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). -- ⚠️ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed - all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md). +- ⚠️ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed — all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md). - ✅ Your **existing login sessions will continue to work** (you won't get logged out). Migration will require a bit of manual work and minutes of downtime, but it's not too bad. diff --git a/docs/configuring-playbook-matrix-corporal.md b/docs/configuring-playbook-matrix-corporal.md index fea63b552..03bf7b22f 100644 --- a/docs/configuring-playbook-matrix-corporal.md +++ b/docs/configuring-playbook-matrix-corporal.md @@ -139,4 +139,4 @@ The following local filesystem paths are mounted in the `matrix-corporal` contai - `/matrix/corporal/cache` is mounted at `/var/cache/matrix-corporal` (read and write) -As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config`) needs to refer to these files via the local container paths - `/etc/matrix-corporal` (read-only), `/var/matrix-corporal` (read and write), `/var/cache/matrix-corporal` (read and write). +As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config`) needs to refer to these files via the local container paths — `/etc/matrix-corporal` (read-only), `/var/matrix-corporal` (read and write), `/var/cache/matrix-corporal` (read and write). diff --git a/docs/configuring-playbook-matrix-media-repo.md b/docs/configuring-playbook-matrix-media-repo.md index 4a9c31372..748d3aaf0 100644 --- a/docs/configuring-playbook-matrix-media-repo.md +++ b/docs/configuring-playbook-matrix-media-repo.md @@ -60,10 +60,10 @@ matrix_media_repo_admins: [] # To disable this datastore, making it readonly, specify `forKinds: []`. # # The kinds available are: -# thumbnails - Used to store thumbnails of media (local and remote). -# remote_media - Original copies of remote media (servers not configured by this repo). -# local_media - Original uploads for local media. -# archives - Archives of content (GDPR and similar requests). +# thumbnails — Used to store thumbnails of media (local and remote). +# remote_media — Original copies of remote media (servers not configured by this repo). +# local_media — Original uploads for local media. +# archives — Archives of content (GDPR and similar requests). matrix_media_repo_datastore_file_for_kinds: ["thumbnails", "remote_media", "local_media", "archives"] matrix_media_repo_datastore_s3_for_kinds: [] diff --git a/docs/configuring-playbook-matrix-registration.md b/docs/configuring-playbook-matrix-registration.md index fb5e04b31..311be8fb7 100644 --- a/docs/configuring-playbook-matrix-registration.md +++ b/docs/configuring-playbook-matrix-registration.md @@ -64,7 +64,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju **matrix-registration** gets exposed at `https://matrix.example.com/matrix-registration` -It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) - for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using `curl`. +It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) — for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using `curl`. We make the most common APIs easy to use via the playbook (see below). diff --git a/docs/configuring-playbook-own-webserver.md b/docs/configuring-playbook-own-webserver.md index 8f8f8682d..214640725 100644 --- a/docs/configuring-playbook-own-webserver.md +++ b/docs/configuring-playbook-own-webserver.md @@ -56,10 +56,10 @@ By default, the playbook configured a `default` certificate resolver and multipl You need to configure 4 entrypoints for your Traefik server: -- `web` (TCP port `80`) - used for redirecting to HTTPS (`web-secure`) -- `web-secure` (TCP port `443`) - used for exposing the Matrix Client-Server API and all other services -- `matrix-federation` (TCP port `8448`) - used for exposing the Matrix Federation API -- `matrix-internal-matrix-client-api` (TCP port `8008`) - used internally for addon services (bridges, bots) to communicate with the homserver +- `web` (TCP port `80`) — used for redirecting to HTTPS (`web-secure`) +- `web-secure` (TCP port `443`) — used for exposing the Matrix Client-Server API and all other services +- `matrix-federation` (TCP port `8448`) — used for exposing the Matrix Federation API +- `matrix-internal-matrix-client-api` (TCP port `8008`) — used internally for addon services (bridges, bots) to communicate with the homserver Below is some configuration for running Traefik yourself, although we recommend using [Traefik managed by the playbook](#traefik-managed-by-the-playbook). @@ -127,7 +127,7 @@ Doing this is possible, but requires manual work. There are 2 ways to go about it: -- (recommended) [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) - using the playbook-managed reverse-proxy (Traefik), but disabling SSL termination for it, exposing this reverse-proxy on a few local ports (e.g. `127.0.0.1:81`, etc.) and forwarding traffic from your own webserver to those few ports +- (recommended) [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) — using the playbook-managed reverse-proxy (Traefik), but disabling SSL termination for it, exposing this reverse-proxy on a few local ports (e.g. `127.0.0.1:81`, etc.) and forwarding traffic from your own webserver to those few ports - (difficult) [Using no reverse-proxy on the Matrix side at all](#using-no-reverse-proxy-on-the-matrix-side-at-all) disabling the playbook-managed reverse-proxy (Traefik), exposing services one by one using `_host_bind_port` variables and forwarding traffic from your own webserver to those ports @@ -201,7 +201,7 @@ To put it another way: ### 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. +Instead of [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy), you can also go another way — completely disabling the playbook-managed Traefik reverse-proxy. You would then need to reverse-proxy from your own webserver directly to each individual Matrix service. This is more difficult, as you would need to handle the configuration for each service manually. Enabling additional services would come with extra manual work you need to do. diff --git a/docs/configuring-playbook-prometheus-nginxlog.md b/docs/configuring-playbook-prometheus-nginxlog.md index 1683210c3..224061c07 100644 --- a/docs/configuring-playbook-prometheus-nginxlog.md +++ b/docs/configuring-playbook-prometheus-nginxlog.md @@ -8,7 +8,7 @@ It will collect access logs from various nginx reverse-proxies which may be used **Note**: nginx is only used internally by this Ansible playbook. With Traefik being our default reverse-proxy, collecting nginx metrics is less relevant. -To make use of this, you need to install [Prometheus](./configuring-playbook-prometheus-grafana.md) either via the playbook or externally. When using an external Prometheus, configuration adjustments are necessary - see [Save metrics on an external Prometheus server](#save-metrics-on-an-external-prometheus-server). +To make use of this, you need to install [Prometheus](./configuring-playbook-prometheus-grafana.md) either via the playbook or externally. When using an external Prometheus, configuration adjustments are necessary — see [Save metrics on an external Prometheus server](#save-metrics-on-an-external-prometheus-server). If your setup includes [Grafana](./configuring-playbook-prometheus-grafana.md), a dedicated `NGINX PROXY` Grafana dashboard will be created. @@ -48,7 +48,7 @@ Metrics and resulting graphs can contain a lot of information. NginX logs contai ## Save metrics on an external Prometheus server -The playbook will automatically integrate the metrics into the [Prometheus](./configuring-playbook-prometheus-grafana.md) server provided with this playbook (if enabled). In such cases, the metrics endpoint is not exposed publicly - it's only available on the container network. +The playbook will automatically integrate the metrics into the [Prometheus](./configuring-playbook-prometheus-grafana.md) server provided with this playbook (if enabled). In such cases, the metrics endpoint is not exposed publicly — it's only available on the container network. When using an external Prometheus server, you'll need to expose metrics publicly. See [Collecting metrics to an external Prometheus server](./configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server). diff --git a/docs/configuring-playbook-riot-web.md b/docs/configuring-playbook-riot-web.md index e008a3f89..b967b6b6b 100644 --- a/docs/configuring-playbook-riot-web.md +++ b/docs/configuring-playbook-riot-web.md @@ -21,9 +21,9 @@ We used to set up Riot at the `riot.example.com` domain. The playbook now sets u There are a few options for handling this: -- (**avoiding changes** - using the old `riot.example.com` domain and avoiding DNS changes) -- to keep using `riot.example.com` instead of `element.example.com`, override the domain at which the playbook serves Element Web: `matrix_server_fqn_element: "riot.{{ matrix_domain }}"` +- (**avoiding changes** — using the old `riot.example.com` domain and avoiding DNS changes) — to keep using `riot.example.com` instead of `element.example.com`, override the domain at which the playbook serves Element Web: `matrix_server_fqn_element: "riot.{{ matrix_domain }}"` -- (**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. +- (**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 diff --git a/docs/configuring-playbook-s3.md b/docs/configuring-playbook-s3.md index cb43c62fb..2f6f1ad49 100644 --- a/docs/configuring-playbook-s3.md +++ b/docs/configuring-playbook-s3.md @@ -29,7 +29,7 @@ Here are some of the important aspects of choosing the right provider: - if a provider has a data region close to your Matrix server (if it's farther away, high latency may cause slowdowns) - if a provider's infrastructure such as data center is centralized or distributed - 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 +- 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 @@ -83,11 +83,11 @@ The `keyID` value is your **Access Key** and `applicationKey` is your **Secret K For configuring [Goofys](configuring-playbook-s3-goofys.md) or [s3-synapse-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) you will need: -- **Endpoint URL** - this is the **Endpoint** value you saw above, but prefixed with `https://` +- **Endpoint URL** — this is the **Endpoint** value you saw above, but prefixed with `https://` -- **Region** - use the value you see in the Endpoint (e.g. `us-west-002`) +- **Region** — use the value you see in the Endpoint (e.g. `us-west-002`) -- **Storage Class** - use `STANDARD`. Backblaze B2 does not have different storage classes, so it doesn't make sense to use any other value. +- **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 diff --git a/docs/configuring-playbook-synapse-admin.md b/docs/configuring-playbook-synapse-admin.md index bc404b9f1..b5e8991bd 100644 --- a/docs/configuring-playbook-synapse-admin.md +++ b/docs/configuring-playbook-synapse-admin.md @@ -25,7 +25,7 @@ matrix_synapse_admin_enabled: true - for [Synapse](./configuring-playbook-synapse.md) (our default homeserver implementation): `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true` - for [Dendrite](./configuring-playbook-dendrite.md): `matrix_dendrite_container_labels_public_client_synapse_admin_api_enabled: true` -By default, synapse-admin installation will be [restricted to only work with one homeserver](https://github.com/etkecc/synapse-admin/blob/e21e44362c879ac41f47c580b04210842b6ff3d7/README.md#restricting-available-homeserver) - the one managed by the playbook. To adjust these restrictions, tweak the `matrix_synapse_admin_config_restrictBaseUrl` variable. +By default, synapse-admin installation will be [restricted to only work with one homeserver](https://github.com/etkecc/synapse-admin/blob/e21e44362c879ac41f47c580b04210842b6ff3d7/README.md#restricting-available-homeserver) — the one managed by the playbook. To adjust these restrictions, tweak the `matrix_synapse_admin_config_restrictBaseUrl` variable. > [!WARNING] > If you're using [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS) for authentication, you will be able to [log into synapse-admin with an access token](https://github.com/etkecc/synapse-admin/pull/58), but certain synapse-admin features (especially those around user management) will be limited or not work at all. diff --git a/docs/configuring-playbook-synapse-s3-storage-provider.md b/docs/configuring-playbook-synapse-s3-storage-provider.md index 02b79c240..c564e4c83 100644 --- a/docs/configuring-playbook-synapse-s3-storage-provider.md +++ b/docs/configuring-playbook-synapse-s3-storage-provider.md @@ -17,7 +17,7 @@ The way media storage providers in Synapse work has some caveats: You may be thinking **if all files are stored locally as well, what's the point**? -You can run some scripts to delete the local files once in a while (which we do automatically by default - see [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem)), thus freeing up local disk space. If these files are needed in the future (for serving them to users, etc.), Synapse will pull them from the media storage provider on demand. +You can run some scripts to delete the local files once in a while (which we do automatically by default — see [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem)), thus freeing up local disk space. If these files are needed in the future (for serving them to users, etc.), Synapse will pull them from the media storage provider on demand. While you will need some local disk space around, it's only to accommodate usage, etc., and won't grow as large as your S3 store. @@ -33,13 +33,13 @@ matrix_synapse_ext_synapse_s3_storage_provider_config_region_name: some-region-n matrix_synapse_ext_synapse_s3_storage_provider_config_endpoint_url: https://s3.REGION_NAME.amazonaws.com # adjust this matrix_synapse_ext_synapse_s3_storage_provider_config_storage_class: STANDARD # or STANDARD_IA, etc. -# Authentication Method 1 - (access key ID + secret) +# Authentication Method 1 — (access key ID + secret) # This works on all providers (AWS and other compatible systems). # Uncomment the variables below to use it. # matrix_synapse_ext_synapse_s3_storage_provider_config_access_key_id: access-key-goes-here # matrix_synapse_ext_synapse_s3_storage_provider_config_secret_access_key: secret-key-goes-here -# Authentication Method 2 - EC2 instance profile which grants permission to access S3 +# Authentication Method 2 — EC2 instance profile which grants permission to access S3 # This only works on AWS when your server is hosted on an EC2 instance with the correct instance profile set. # Uncomment the variable below to use it. # matrix_synapse_ext_synapse_s3_storage_provider_config_ec2_instance_profile: true @@ -78,13 +78,13 @@ To copy your existing files, SSH into the server and run `/matrix/synapse/ext/s3 This launches a Synapse container, which has access to the local media store, Postgres database, S3 store and has some convenient environment variables configured for you to use (`MEDIA_PATH`, `BUCKET`, `ENDPOINT`, `UPDATE_DB_DAYS`, etc). -Then use the following commands (`$` values come from environment variables - they're **not placeholders** that you need to substitute): +Then use the following commands (`$` values come from environment variables — they're **not placeholders** that you need to substitute): -1. `s3_media_upload update-db $UPDATE_DB_DURATION` - create a local SQLite database (`cache.db`) with a list of media repository files (from the `synapse` Postgres database) eligible for operating on +1. `s3_media_upload update-db $UPDATE_DB_DURATION` — create a local SQLite database (`cache.db`) with a list of media repository files (from the `synapse` Postgres database) eligible for operating on - `$UPDATE_DB_DURATION` is influenced by the `matrix_synapse_ext_synapse_s3_storage_provider_update_db_day_count` variable (defaults to `0`) - `$UPDATE_DB_DURATION` defaults to `0d` (0 days), which means **include files which haven't been accessed for more than 0 days** (that is, **all files will be included**). -2. `s3_media_upload check-deleted $MEDIA_PATH` - check whether files in the local cache still exist in the local media repository directory -3. `s3_media_upload upload $MEDIA_PATH $BUCKET --delete --storage-class $STORAGE_CLASS --endpoint-url $ENDPOINT` - uploads locally-stored files to S3 and deletes them from the local media repository directory +2. `s3_media_upload check-deleted $MEDIA_PATH` — check whether files in the local cache still exist in the local media repository directory +3. `s3_media_upload upload $MEDIA_PATH $BUCKET --delete --storage-class $STORAGE_CLASS --endpoint-url $ENDPOINT` — uploads locally-stored files to S3 and deletes them from the local media repository directory The `s3_media_upload upload` command may take a lot of time to complete. diff --git a/docs/configuring-playbook-synapse.md b/docs/configuring-playbook-synapse.md index 6b1ec9f3e..12ae0f061 100644 --- a/docs/configuring-playbook-synapse.md +++ b/docs/configuring-playbook-synapse.md @@ -22,9 +22,9 @@ By default, this enables the `one-of-each` [worker preset](#worker-presets), but We support a few configuration presets (`matrix_synapse_workers_preset: one-of-each` being the default configuration right now): -- (federation-only) `little-federation-helper` - a very minimal worker configuration to improve federation performance -- (generic) `one-of-each` - defaults to one worker of each supported type - no smart routing, just generic workers -- (specialized) `specialized-workers` - defaults to one worker of each supported type, but disables generic workers and uses [specialized workers](#specialized-workers) instead +- (federation-only) `little-federation-helper` — a very minimal worker configuration to improve federation performance +- (generic) `one-of-each` — defaults to one worker of each supported type — no smart routing, just generic workers +- (specialized) `specialized-workers` — defaults to one worker of each supported type, but disables generic workers and uses [specialized workers](#specialized-workers) instead These presets represent a few common configurations. There are many worker types which can be mixed and matched based on your needs. @@ -34,20 +34,20 @@ Previously, the playbook only supported the most basic type of load-balancing. W This is **still the default load-balancing method (preset) used by the playbook**. -To use generic load-balancing, do not specify `matrix_synapse_workers_preset` to make it use the default value (`one-of-each`), or better yet - explicitly set it as `one-of-each`. +To use generic load-balancing, do not specify `matrix_synapse_workers_preset` to make it use the default value (`one-of-each`), or better yet — explicitly set it as `one-of-each`. 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 -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 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 supports these **4 types** of specialized workers: -- Room workers - handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) & [Federation](https://spec.matrix.org/v1.9/server-server-api) APIs dedicated to handling specific rooms -- Sync workers - handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) APIs related to synchronization (most notably [the `/sync` endpoint](https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv3sync)) -- Client readers - handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) APIs which are not for specific rooms (handled by **room workers**) or for synchronization (handled by **sync workers**) -- Federation readers - handles various [Federation](https://spec.matrix.org/v1.9/server-server-api) APIs which are not for specific rooms (handled by **room workers**) +- Room workers — handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) & [Federation](https://spec.matrix.org/v1.9/server-server-api) APIs dedicated to handling specific rooms +- Sync workers — handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) APIs related to synchronization (most notably [the `/sync` endpoint](https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv3sync)) +- Client readers — handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) APIs which are not for specific rooms (handled by **room workers**) or for synchronization (handled by **sync workers**) +- Federation readers — handles various [Federation](https://spec.matrix.org/v1.9/server-server-api) APIs which are not for specific rooms (handled by **room 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). diff --git a/docs/configuring-playbook-traefik.md b/docs/configuring-playbook-traefik.md index b9f3e86e8..cab20454f 100644 --- a/docs/configuring-playbook-traefik.md +++ b/docs/configuring-playbook-traefik.md @@ -59,7 +59,7 @@ However, if your service does not run on a container or runs on another machine, If you want to host another webserver would be reachable via `my-fancy-website.example.net` from the internet and via `https://:` from inside your network, you can make the playbook's integrated Traefik instance reverse-proxy the traffic to the correct host. -Prerequisites: DNS and routing for the domain `my-fancy-website.example.net` need to be set up correctly. In this case, you'd be pointing the domain name to your Matrix server - `my-fancy-website.example.net` would be a CNAME going to `matrix.example.com`. +Prerequisites: DNS and routing for the domain `my-fancy-website.example.net` need to be set up correctly. In this case, you'd be pointing the domain name to your Matrix server — `my-fancy-website.example.net` would be a CNAME going to `matrix.example.com`. First, we have to adjust the static configuration of Traefik, so that we can add additional configuration files: diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 7836190f8..a2332f9bf 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -111,7 +111,7 @@ Use alternative file storage to the default `media_store` folder. Bridges can be used to connect your Matrix installation with third-party communication networks. -- [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) - a common guide for configuring mautrix bridges +- [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) — a common guide for configuring mautrix bridges - [Setting up Mautrix Discord bridging](configuring-playbook-bridge-mautrix-discord.md) @@ -145,7 +145,7 @@ Bridges can be used to connect your Matrix installation with third-party communi - [Setting up Beeper LinkedIn bridging](configuring-playbook-bridge-beeper-linkedin.md) -- [Setting up matrix-hookshot](configuring-playbook-bridge-hookshot.md) - a bridge between Matrix and multiple project management services, such as [GitHub](https://github.com), [GitLab](https://about.gitlab.com) and [JIRA](https://www.atlassian.com/software/jira). +- [Setting up matrix-hookshot](configuring-playbook-bridge-hookshot.md) — a bridge between Matrix and multiple project management services, such as [GitHub](https://github.com), [GitLab](https://about.gitlab.com) and [JIRA](https://www.atlassian.com/software/jira). - [Setting up MX Puppet Slack bridging](configuring-playbook-bridge-mx-puppet-slack.md) @@ -175,23 +175,23 @@ Bridges can be used to connect your Matrix installation with third-party communi Bots provide various additional functionality to your installation. -- [Setting up baibot](configuring-playbook-bot-baibot.md) - a bot through which you can talk to various [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) services ([OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/chatgpt/) and [others](https://github.com/etkecc/baibot/blob/main/docs/providers.md)) +- [Setting up baibot](configuring-playbook-bot-baibot.md) — a bot through which you can talk to various [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) services ([OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/chatgpt/) and [others](https://github.com/etkecc/baibot/blob/main/docs/providers.md)) -- [Setting up matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) - a bot to remind you about stuff +- [Setting up matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) — a bot to remind you about stuff -- [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) - a bot to create and manage registration tokens to invite users +- [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) — a bot to create and manage registration tokens to invite users -- [Setting up maubot](configuring-playbook-bot-maubot.md) - a plugin-based Matrix bot system +- [Setting up maubot](configuring-playbook-bot-maubot.md) — a plugin-based Matrix bot system -- [Setting up Honoroit](configuring-playbook-bot-honoroit.md) - a helpdesk bot +- [Setting up Honoroit](configuring-playbook-bot-honoroit.md) — a helpdesk bot -- [Setting up Mjolnir](configuring-playbook-bot-mjolnir.md) - a moderation tool/bot +- [Setting up Mjolnir](configuring-playbook-bot-mjolnir.md) — a moderation tool/bot -- [Setting up Draupnir](configuring-playbook-bot-draupnir.md) - a moderation tool/bot, forked from Mjolnir and maintained by its former leader developer +- [Setting up Draupnir](configuring-playbook-bot-draupnir.md) — a moderation tool/bot, forked from Mjolnir and maintained by its former leader developer -- [Setting up Draupnir for all/D4A](configuring-playbook-appservice-draupnir-for-all.md) - like the [Draupnir bot](configuring-playbook-bot-draupnir.md) mentioned above, but running in appservice mode and supporting multiple instances +- [Setting up Draupnir for all/D4A](configuring-playbook-appservice-draupnir-for-all.md) — like the [Draupnir bot](configuring-playbook-bot-draupnir.md) mentioned above, but running in appservice mode and supporting multiple instances -- [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 +- [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 ### Administration @@ -208,9 +208,9 @@ Services that help you in administrating and monitoring your Matrix installation - [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md) - Backups: - - [Setting up BorgBackup](configuring-playbook-backup-borg.md) - a full Matrix server backup solution, including the Postgres database + - [Setting up BorgBackup](configuring-playbook-backup-borg.md) — a full Matrix server backup solution, including the Postgres database - - [Setting up postgres backup](configuring-playbook-postgres-backup.md) - a Postgres-database backup solution (note: does not include other files) + - [Setting up postgres backup](configuring-playbook-postgres-backup.md) — a Postgres-database backup solution (note: does not include other files) ### Other specialized services @@ -226,7 +226,7 @@ Various services that don't fit any other categories. - [Setting up the Jitsi video-conferencing platform](configuring-playbook-jitsi.md) -- [Setting up Cactus Comments](configuring-playbook-cactus-comments.md) - a federated comment system built on Matrix +- [Setting up Cactus Comments](configuring-playbook-cactus-comments.md) — a federated comment system built on Matrix - [Setting up Pantalaimon (E2EE aware proxy daemon)](configuring-playbook-pantalaimon.md) (advanced) diff --git a/docs/configuring-well-known.md b/docs/configuring-well-known.md index 9c8e9bef8..e7bbc9562 100644 --- a/docs/configuring-well-known.md +++ b/docs/configuring-well-known.md @@ -6,11 +6,11 @@ This documentation page explains how to configure Service discovery via `/.well- There are 3 types of well-known service discovery mechanism that Matrix makes use of: -- (important) **Federation Server discovery** (`/.well-known/matrix/server`) -- assists other servers in the Matrix network with finding your server. With the default playbook configuration specified on the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), this is necessary for federation to work. Without a proper configuration, your server will effectively not be part of the Matrix network. +- (important) **Federation Server discovery** (`/.well-known/matrix/server`) — assists other servers in the Matrix network with finding your server. With the default playbook configuration specified on the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), this is necessary for federation to work. Without a proper configuration, your server will effectively not be part of the Matrix network. -- (less important) **Client Server discovery** (`/.well-known/matrix/client`) -- assists programs that you use to connect to your server (e.g. Element Web), so that they can make it more convenient for you by automatically configuring the "Homeserver URL" and "Identity Server URL" addresses. +- (less important) **Client Server discovery** (`/.well-known/matrix/client`) — assists programs that you use to connect to your server (e.g. Element Web), so that they can make it more convenient for you by automatically configuring the "Homeserver URL" and "Identity Server URL" addresses. -- (optional) **Support service discovery** (`/.well-known/matrix/support`) -- returns server admin contact and support page of the domain. +- (optional) **Support service discovery** (`/.well-known/matrix/support`) — returns server admin contact and support page of the domain. ### Federation Server Discovery @@ -67,7 +67,7 @@ To implement the service discovery mechanisms, your base domain's server (e.g. ` If you don't have a server for your base domain at all, you can use the Matrix server for this. If you don't need the base domain (e.g. `example.com`) for anything else (hosting a website, etc.), you can point it to the Matrix server's IP address and tell the playbook to configure it. -**This is the easiest way to set up well-known serving** -- letting the playbook handle the whole base domain for you (including SSL certificates, etc.) and take care to serve the appropriate well-known files automatically. +**This is the easiest way to set up well-known serving** — letting the playbook handle the whole base domain for you (including SSL certificates, etc.) and take care to serve the appropriate well-known files automatically. If you decide to go this route, you don't need to read ahead in this document. Instead, go to [Serving the base domain](configuring-playbook-base-domain-serving.md) to learn how the playbook can help you set it up. diff --git a/docs/container-images.md b/docs/container-images.md index 4f77a7bc6..4c43786b8 100644 --- a/docs/container-images.md +++ b/docs/container-images.md @@ -32,7 +32,7 @@ Services that run on the server to make the various parts of your installation w | ------- | --------------- | -------- | ----------- | | [PostgreSQL](configuring-playbook-external-postgres.md) | [postgres](https://hub.docker.com/_/postgres/) | ✅ | Database for Synapse. [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) is also possible. | | [coturn](configuring-playbook-turn.md) | [coturn/coturn](https://hub.docker.com/r/coturn/coturn/) | ✅ | STUN/TURN server for WebRTC audio/video calls | -| [Traefik](configuring-playbook-traefik.md) | [Traefik](https://hub.docker.com/_/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Using your own webserver [is possible](configuring-playbook-own-webserver.md) | +| [Traefik](configuring-playbook-traefik.md) | [Traefik](https://hub.docker.com/_/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 — standing in front of all the other services. Using your own webserver [is possible](configuring-playbook-own-webserver.md) | | [Let's Encrypt](configuring-playbook-ssl-certificates.md) | [certbot/certbot](https://hub.docker.com/r/certbot/certbot/) | ✅ | The [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) | | [Exim](configuring-playbook-email.md) | [devture/exim-relay](https://hub.docker.com/r/devture/exim-relay/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | | [ma1sd](configuring-playbook-ma1sd.md) | [ma1uta/ma1sd](https://hub.docker.com/r/ma1uta/ma1sd/) | ❌ | Matrix Identity Server | diff --git a/docs/faq.md b/docs/faq.md index 51e093fc7..c41c7fe11 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -32,7 +32,7 @@ If you'd like to host your own server (you being `@alice:example.com`), you'd ne In short: -- Matrix is the protocol - a set of rules about how the chat network operates +- Matrix is the protocol — a set of rules about how the chat network operates - Element is a client program you can use to participate on the Matrix chat network via some server (yours or someone else's). There are also [many other client programs](https://matrix.org/clients/). - Synapse is a server program you can use to host your very own Matrix server. @@ -48,15 +48,15 @@ Besides setting up your own bridges (preferable), you can also use some [public ### How do I get started with Matrix? -One of [Matrix](https://matrix.org/)'s distinguishing strengths (compared to other chat networks) is its decentralized nature. There's not just one entity (company, organization) controlling the servers. Rather there's thousands of servers operated by different people - one server being insecure, slow or disrespective toward its users does not affect the rest of the network. To participate in that decentralization in its fullest, consider hosting your own server or using some public server other than the largest/default one (`matrix.org`). +One of [Matrix](https://matrix.org/)'s distinguishing strengths (compared to other chat networks) is its decentralized nature. There's not just one entity (company, organization) controlling the servers. Rather there's thousands of servers operated by different people — one server being insecure, slow or disrespective toward its users does not affect the rest of the network. To participate in that decentralization in its fullest, consider hosting your own server or using some public server other than the largest/default one (`matrix.org`). There are 3 ways to get into Matrix, depending on your technical ability and needs: -- **using the existing default server** - the easiest way is to use an existing server. The largest public Matrix server is `matrix.org` and it's configured as a default server in clients such as [Element Web](https://app.element.io) and many others. Just use Element Web on the browser via that link (or [download client apps for your Desktop or smartphone](https://element.io/app-for-productivity)), create an account and start chatting. +- **using the existing default server** — the easiest way is to use an existing server. The largest public Matrix server is `matrix.org` and it's configured as a default server in clients such as [Element Web](https://app.element.io) and many others. Just use Element Web on the browser via that link (or [download client apps for your Desktop or smartphone](https://element.io/app-for-productivity)), create an account and start chatting. -- **using some other server** - instead of using the largest public server (`matrix.org`), you can use another public one. Here's a [list of public Matrix servers](https://joinmatrix.org/servers/) to choose from. Go to [Element Web](https://app.element.io) or download [some other client](https://matrix.org/clients/) of your choosing and adjust the homeserver URL during login. +- **using some other server** — instead of using the largest public server (`matrix.org`), you can use another public one. Here's a [list of public Matrix servers](https://joinmatrix.org/servers/) to choose from. Go to [Element Web](https://app.element.io) or download [some other client](https://matrix.org/clients/) of your choosing and adjust the homeserver URL during login. -- **using your own server** - running your own server puts you in ultimate control of your data. It also lets you have your own user IDs (e.g. `@bob:example.com`). See [How do I set up my own Matrix server](#how-do-i-set-up-my-own-matrix-server). +- **using your own server** — running your own server puts you in ultimate control of your data. It also lets you have your own user IDs (e.g. `@bob:example.com`). See [How do I set up my own Matrix server](#how-do-i-set-up-my-own-matrix-server). ### How do I set up my own Matrix server? @@ -117,7 +117,7 @@ All services run in Docker containers (most being officially provided by each co Reasons are similar to the reasons for not installing manually. -Besides Synapse, you'd need other things - a Postgres database, likely the [Element](https://element.io) client, etc., etc. +Besides Synapse, you'd need other things — a Postgres database, likely the [Element](https://element.io) client, etc., etc. Using the playbook, you get all these components in a way that works well together out of the box. @@ -129,7 +129,7 @@ It is the acronym of us: **m**atrix-**d**ocker-**a**nsible-**d**eploy. This is similar to the [EMnify/matrix-synapse-auto-deploy](https://github.com/EMnify/matrix-synapse-auto-deploy) Ansible deployment, but: -- this one is a complete Ansible playbook (instead of just a role), so it's **easier to run** - especially for folks not familiar with Ansible +- this one is a complete Ansible playbook (instead of just a role), so it's **easier to run** — especially for folks not familiar with Ansible - this one installs and hooks together **a lot more Matrix-related services** for you (see above) @@ -285,7 +285,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start ### I don't use the base domain for anything. How am I supposed to set up Server Delegation for Matrix services? -If you don't use your base domain for anything, then it's hard for you to "serve files over HTTPS" on it -- something we ask you to do for the [.well-known](configuring-well-known.md) setup (needed for [Server Delegation](howto-server-delegation.md)). +If you don't use your base domain for anything, then it's hard for you to "serve files over HTTPS" on it — something we ask you to do for the [.well-known](configuring-well-known.md) setup (needed for [Server Delegation](howto-server-delegation.md)). Luckily, the playbook can set up your Matrix server (at `matrix.example.com`) to also handle traffic for the base domain (`example.com`). @@ -391,7 +391,7 @@ Yes, you can. You generally need to do a playbook installation. It's recommended to follow the full installation guide (starting at the [Prerequisites](prerequisites.md) page), not the [Quick start](quick-start.md) guide. The full installation guide will tell you when it's time to import your existing data into the newly-prepared server. -This Ansible playbook guides you into installing a server for `example.com` (user IDs are like this: `@alice:example.com`), while the server is at `matrix.example.com`. If your existing setup has a server name (`server_name` configuration setting in Synapse's `homeserver.yaml` file) other than the base `example.com`, you may need to tweak some additional variables. This FAQ entry may be of use if you're dealing with a more complicated setup - [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrixexamplecom-without-involving-the-base-domain) +This Ansible playbook guides you into installing a server for `example.com` (user IDs are like this: `@alice:example.com`), while the server is at `matrix.example.com`. If your existing setup has a server name (`server_name` configuration setting in Synapse's `homeserver.yaml` file) other than the base `example.com`, you may need to tweak some additional variables. This FAQ entry may be of use if you're dealing with a more complicated setup — [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrixexamplecom-without-involving-the-base-domain) After configuring the playbook and installing and **before starting** services (done with `ansible-playbook … --tags=start`) you'd import [your SQLite](importing-synapse-sqlite.md) (or [Postgres](importing-postgres.md)) database and also [import your media store](importing-synapse-media-store.md). diff --git a/docs/howto-server-delegation.md b/docs/howto-server-delegation.md index 429e06982..602fda481 100644 --- a/docs/howto-server-delegation.md +++ b/docs/howto-server-delegation.md @@ -11,7 +11,7 @@ Both methods have their place and will continue to do so. You only need to use j For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file. However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation. -**Note**: as an alternative, it is possible to install the server such that it uses only the `matrix.example.com` domain (instead of identifying as the shorter base domain - `example.com`). This should be helpful if you are not in control of anything on the base domain (`example.com`). In this case, you would not need to configure server delegation, but you would need to add other configuration. For more information, see [How do I install on matrix.example.com without involving the base domain?](faq.md#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) on our FAQ. +**Note**: as an alternative, it is possible to install the server such that it uses only the `matrix.example.com` domain (instead of identifying as the shorter base domain — `example.com`). This should be helpful if you are not in control of anything on the base domain (`example.com`). In this case, you would not need to configure server delegation, but you would need to add other configuration. For more information, see [How do I install on matrix.example.com without involving the base domain?](faq.md#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) on our FAQ. ## Server Delegation via a well-known file diff --git a/docs/importing-postgres.md b/docs/importing-postgres.md index 44c49c7c6..d73b3c95a 100644 --- a/docs/importing-postgres.md +++ b/docs/importing-postgres.md @@ -1,7 +1,7 @@ # Importing an existing Postgres database from another installation (optional) Run this if you'd like to import your database from a previous installation. -(don't forget to import your Synapse `media_store` files as well - see [the importing-synape-media-store guide](importing-synapse-media-store.md)). +(don't forget to import your Synapse `media_store` files as well — see [the importing-synape-media-store guide](importing-synapse-media-store.md)). ## Prerequisites @@ -64,7 +64,7 @@ It can be worked around by changing the username to `synapse`, for example by us $ sed -i "s/OWNER TO synapse_user;/OWNER TO synapse;/g" homeserver.sql ``` -This uses sed to perform an 'in-place' (`-i`) replacement globally (`/g`), searching for `synapse_user` and replacing with `synapse` (`s/synapse_user/synapse`). If your database username was different, change `synapse_user` to that username instead. Expand search/replace statement as shown in example above, in case of old user name like `matrix` - replacing `matrix` only would… well - you can imagine. +This uses sed to perform an 'in-place' (`-i`) replacement globally (`/g`), searching for `synapse_user` and replacing with `synapse` (`s/synapse_user/synapse`). If your database username was different, change `synapse_user` to that username instead. Expand search/replace statement as shown in example above, in case of old user name like `matrix` — replacing `matrix` only would… well — you can imagine. Note that if the previous import failed with an error it may have made changes which are incompatible with re-running the import task right away; if you do so it may fail with an error such as: diff --git a/docs/importing-synapse-sqlite.md b/docs/importing-synapse-sqlite.md index 2453e8cfc..29fa0594a 100644 --- a/docs/importing-synapse-sqlite.md +++ b/docs/importing-synapse-sqlite.md @@ -1,6 +1,6 @@ # Importing an existing SQLite database from another Synapse installation (optional) -Run this if you'd like to import your database from a previous default installation of Synapse (don't forget to import your `media_store` files as well - see [the importing-synapse-media-store guide](importing-synapse-media-store.md)). +Run this if you'd like to import your database from a previous default installation of Synapse (don't forget to import your `media_store` files as well — see [the importing-synapse-media-store guide](importing-synapse-media-store.md)). While this playbook only supports running Synapse in combination with PostgreSQL, a Synapse instance installed manually usually defaults to using an SQLite database. diff --git a/docs/installing.md b/docs/installing.md index bcd2e2325..10bbd32bc 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -27,7 +27,7 @@ If you **don't** use SSH keys for authentication, but rather a regular password, If you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to all Ansible commands. -There 2 ways to start the installation process - depending on whether you're [Installing a brand new server (without importing data)](#installing-a-brand-new-server-without-importing-data) or [Installing a server into which you'll import old data](#installing-a-server-into-which-youll-import-old-data). +There 2 ways to start the installation process — depending on whether you're [Installing a brand new server (without importing data)](#installing-a-brand-new-server-without-importing-data) or [Installing a server into which you'll import old data](#installing-a-server-into-which-youll-import-old-data). **Note**: if you are migrating from an old server to a new one, take a look at [this guide](maintenance-migrating.md) instead. This is an easier and more straightforward way than installing a server and importing old data into it. @@ -130,7 +130,7 @@ After finilizing the installation, you can: - or learn how to [maintain your server](faq.md#maintenance) - or join some Matrix rooms: * via the *Explore rooms* feature in Element Web or some other clients, or by discovering them using this [matrix-static list](https://view.matrix.org). **Note**: joining large rooms may overload small servers. - * or come say Hi in our support room - [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting. + * or come say Hi in our support room — [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting. - or help make this playbook better by contributing (code, documentation, or [coffee/beer](https://liberapay.com/s.pantaleev/donate)) ### Maintaining your setup in the future diff --git a/docs/just.md b/docs/just.md index ecc09e495..53743a03b 100644 --- a/docs/just.md +++ b/docs/just.md @@ -2,7 +2,7 @@ We have previously used [make](https://www.gnu.org/software/make/) for easily running some playbook commands (e.g. `make roles` which triggers [`ansible-galaxy`](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html)). Our [`Makefile`](../Makefile) is still around, and you can still run these commands. -In addition, we have added support for running commands via [`just`](https://github.com/casey/just) - a more modern command-runner alternative to `make`. It can be used to invoke `ansible-playbook` commands with less typing. +In addition, we have added support for running commands via [`just`](https://github.com/casey/just) — a more modern command-runner alternative to `make`. It can be used to invoke `ansible-playbook` commands with less typing. The `just` utility executes shortcut commands (called as "recipes"), which invoke `ansible-playbook`, `ansible-galaxy` or [`agru`](https://github.com/etkecc/agru) (depending on what is available in your system). The targets of the recipes are defined in [`justfile`](../justfile). Most of the just recipes have no corresponding `Makefile` targets. diff --git a/docs/maintenance-synapse.md b/docs/maintenance-synapse.md index 3bb315fcb..bc78f28fd 100644 --- a/docs/maintenance-synapse.md +++ b/docs/maintenance-synapse.md @@ -88,9 +88,9 @@ Tuning the cache factor is useful only to a limited degree (as its crude to do i Cache autotuning is **enabled by default** and controlled via the following variables: -- `matrix_synapse_cache_autotuning_max_cache_memory_usage` - defaults to 1/8 of total RAM with a cap of 2GB; values are specified in bytes -- `matrix_synapse_cache_autotuning_target_cache_memory_usage` - defaults to 1/16 of total RAM with a cap of 1GB; values are specified in bytes -- `matrix_synapse_cache_autotuning_min_cache_ttl` - defaults to `30s` +- `matrix_synapse_cache_autotuning_max_cache_memory_usage` — defaults to 1/8 of total RAM with a cap of 2GB; values are specified in bytes +- `matrix_synapse_cache_autotuning_target_cache_memory_usage` — defaults to 1/16 of total RAM with a cap of 1GB; values are specified in bytes +- `matrix_synapse_cache_autotuning_min_cache_ttl` — defaults to `30s` You can **learn more about cache-autotuning and the global cache factor settings** in the [Synapse's documentation on caches and associated values](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#caches-and-associated-values). diff --git a/docs/obtaining-access-tokens.md b/docs/obtaining-access-tokens.md index 909d62b8f..3466f1a4e 100644 --- a/docs/obtaining-access-tokens.md +++ b/docs/obtaining-access-tokens.md @@ -9,7 +9,7 @@ When setting up some optional features like bots and bridges you will need to pr The user for whom you want to obtain an access token needs to already exist. You can use this playbook to [register a new user](registering-users.md), if you have not already. -Below, we describe 2 ways to generate an access token for a user - using [Element Web](#obtain-an-access-token-via-element-web) or [curl](#obtain-an-access-token-via-curl). For both ways you need the user's password. +Below, we describe 2 ways to generate an access token for a user — using [Element Web](#obtain-an-access-token-via-element-web) or [curl](#obtain-an-access-token-via-curl). For both ways you need the user's password. ## Obtain an access token via Element Web diff --git a/docs/playbook-tags.md b/docs/playbook-tags.md index 8e2a064ce..02da3ea7e 100644 --- a/docs/playbook-tags.md +++ b/docs/playbook-tags.md @@ -6,19 +6,19 @@ The general command syntax is: `ansible-playbook -i inventory/hosts setup.yml -- Here are some playbook tags that you should be familiar with: -- `setup-all` - runs all setup tasks (installation and uninstallation) for all components, but does not start/restart services +- `setup-all` — runs all setup tasks (installation and uninstallation) for all components, but does not start/restart services -- `install-all` - like `setup-all`, but skips uninstallation tasks. Useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove components, you'd need to run `setup-all` though, or these components will still remain installed +- `install-all` — like `setup-all`, but skips uninstallation tasks. Useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove components, you'd need to run `setup-all` though, or these components will still remain installed -- `setup-SERVICE` (e.g. `setup-postmoogle`) - runs the setup tasks only for a given role, but does not start/restart services. You can discover these additional tags in each role (`roles/**/tasks/main.yml`). Running per-component setup tasks is **not recommended**, as components sometimes depend on each other and running just the setup tasks for a given component may not be enough. For example, setting up the [mautrix-telegram bridge](configuring-playbook-bridge-mautrix-telegram.md), in addition to the `setup-mautrix-telegram` tag, requires database changes (the `setup-postgres` tag) as well as reverse-proxy changes (the `setup-nginx-proxy` tag). +- `setup-SERVICE` (e.g. `setup-postmoogle`) — runs the setup tasks only for a given role, but does not start/restart services. You can discover these additional tags in each role (`roles/**/tasks/main.yml`). Running per-component setup tasks is **not recommended**, as components sometimes depend on each other and running just the setup tasks for a given component may not be enough. For example, setting up the [mautrix-telegram bridge](configuring-playbook-bridge-mautrix-telegram.md), in addition to the `setup-mautrix-telegram` tag, requires database changes (the `setup-postgres` tag) as well as reverse-proxy changes (the `setup-nginx-proxy` tag). -- `install-SERVICE` (e.g. `install-postmoogle`) - like `setup-SERVICE`, but skips uninstallation tasks. See `install-all` above for additional information. +- `install-SERVICE` (e.g. `install-postmoogle`) — like `setup-SERVICE`, but skips uninstallation tasks. See `install-all` above for additional information. -- `start` - starts all systemd services and makes them start automatically in the future +- `start` — starts all systemd services and makes them start automatically in the future -- `stop` - stops all systemd services +- `stop` — stops all systemd services -- `ensure-matrix-users-created` - a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created +- `ensure-matrix-users-created` — a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created **Notes**: - `setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc. diff --git a/docs/quick-start.md b/docs/quick-start.md index 9f75b61f7..fbb579f61 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -193,7 +193,7 @@ You should be able to log in to it with your own [Element Web](configuring-playb **If you successfully logged in to your account, installing and configuring is complete**🎉 -Come say Hi👋 in our support room - [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting. +Come say Hi👋 in our support room — [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting. ## Things to do next diff --git a/docs/registering-users.md b/docs/registering-users.md index 1d92ce131..2972378b6 100644 --- a/docs/registering-users.md +++ b/docs/registering-users.md @@ -143,8 +143,8 @@ where: If you're using the integrated Postgres server and not an [external Postgres server](configuring-playbook-external-postgres.md), you can launch a Postgres into the `synapse` database by: -- running `/matrix/postgres/bin/cli` - to launch [`psql`](https://www.postgresql.org/docs/current/app-psql.html) -- running `\c synapse` - to change to the `synapse` database +- running `/matrix/postgres/bin/cli` — to launch [`psql`](https://www.postgresql.org/docs/current/app-psql.html) +- running `\c synapse` — to change to the `synapse` database You can then proceed to run the query above. diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 4e5f0c9b2..92a03c33b 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -249,7 +249,7 @@ matrix_homeserver_sliding_sync_url: "{{ matrix_sliding_sync_base_url if matrix_s # This list is not exhaustive and final. # Synapse workers are still injected into the list at runtime. -# Additional JVB workers (jitsi_jvb.yml -- roles/galaxy/jitsi/tasks/init_additional_jvb.yml) override this variable at runtime as well. +# Additional JVB workers (jitsi_jvb.yml — roles/galaxy/jitsi/tasks/init_additional_jvb.yml) override this variable at runtime as well. # # Priority levels are like this: # - Traefik starts first with a level of 250, so that: @@ -257,7 +257,7 @@ matrix_homeserver_sliding_sync_url: "{{ matrix_sliding_sync_base_url if matrix_s # - so that addon services (starting later) can communicte with the homeserver via Traefik's internal entrypoint # (see `matrix_playbook_internal_matrix_client_api_traefik_entrypoint_enabled`) # - core services (the homeserver) get a level of ~1000 -# - services that the homeserver depends on (database, Redis, ntfy, coturn, etc.) get a lower level - between 500 and 1000 +# - services that the homeserver depends on (database, Redis, ntfy, coturn, etc.) get a lower level — between 500 and 1000 # - coturn gets a higher level if `devture_systemd_service_manager_service_restart_mode == 'one-by-one'` to intentionally delay it, because: # - starting services one by one means that the service manager role waits for each service to fully start before proceeding to the next one # - if coturn has a lower priority than the homeserver, it would be started before it @@ -268,8 +268,8 @@ matrix_homeserver_sliding_sync_url: "{{ matrix_sliding_sync_base_url if matrix_s # - Matrix utility services (bridges, bots) get a level of 2000/2200, so that: # - they can start before the reverse-proxy # - so that, when the reverse-proxy is up (Matrix is up), all bots and bridges can be interacted with -# - monitoring services (Prometheus, Grafana, …) get a level of 4000 - they can start later than all-of-Matrix -# - services which aren't time-sensitive (various crons and timers) get a level of 5000 - they can start later than all-of-Matrix +# - monitoring services (Prometheus, Grafana, …) get a level of 4000 — they can start later than all-of-Matrix +# - services which aren't time-sensitive (various crons and timers) get a level of 5000 — they can start later than all-of-Matrix devture_systemd_service_manager_services_list_auto: | {{ ([{'name': (backup_borg_identifier + '.timer'), 'priority': 5000, 'groups': ['matrix', 'backup', 'borg']}] if backup_borg_enabled else []) @@ -5966,7 +5966,7 @@ matrix_user_verification_service_container_additional_networks: | ) | unique }} -# If Jitsi is managed by this playbook we can use the docker network - no need to expose a port. +# If Jitsi is managed by this playbook we can use the docker network — no need to expose a port. # If Jitsi is not managed by this playbook, or you otherwise have a need for it, you can expose # matrix-user-verfification-services's client-server port to port 3003. # By default Matrix-User-Verification-Service binds to port 3000, which collides with grafana, therefore this uses port 3003. diff --git a/roles/custom/matrix-client-schildichat/tasks/setup_install.yml b/roles/custom/matrix-client-schildichat/tasks/setup_install.yml index b27f5bc48..0be2563d4 100644 --- a/roles/custom/matrix-client-schildichat/tasks/setup_install.yml +++ b/roles/custom/matrix-client-schildichat/tasks/setup_install.yml @@ -38,7 +38,7 @@ # See: # - https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1357 - # - https://github.com/vector-im/schildichat-web/issues/19544 -- # Update (2023-12-15): 404 + # - https://github.com/vector-im/schildichat-web/issues/19544 — # Update (2023-12-15): 404 - name: Patch webpack.config.js to support building on low-memory (<4G RAM) devices ansible.builtin.lineinfile: path: "{{ matrix_client_schildichat_container_src_files_path }}/element-web/webpack.config.js" diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 index d278267dc..5c3560ef3 100644 --- a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 +++ b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 @@ -92,7 +92,7 @@ server { root /dev/null; {% if matrix_synapse_reverse_proxy_companion_synapse_workers_enabled %} - # Client-server overrides -- These locations must go to the main Synapse process + # Client-server overrides — These locations must go to the main Synapse process location ~ {{ matrix_synapse_reverse_proxy_companion_client_server_main_override_locations_regex }} { {# FIXME: This block was copied from the main Synapse fallback below. It would be better to have it in one place and avoid duplication. #} {# Use the embedded DNS resolver in Docker containers to discover the service #} @@ -107,7 +107,7 @@ server { proxy_max_temp_file_size 0; } - # Client-server SSO overrides -- These locations must go to the main Synapse process + # Client-server SSO overrides — These locations must go to the main Synapse process location ~ {{ matrix_synapse_reverse_proxy_companion_client_server_sso_override_locations_regex }} { {# FIXME: This block was copied from the main Synapse fallback below. It would be better to have it in one place and avoid duplication. #} {# Use the embedded DNS resolver in Docker containers to discover the service #} @@ -250,7 +250,7 @@ server { root /dev/null; {% if matrix_synapse_reverse_proxy_companion_synapse_workers_enabled %} - # Federation overrides -- These locations must go to the main Synapse process + # Federation overrides — These locations must go to the main Synapse process location ~ {{ matrix_synapse_reverse_proxy_companion_federation_override_locations_regex }} { {# FIXME: This block was copied from the fallback location below. It would be better to have it in one place and avoid duplication. #} {# Use the embedded DNS resolver in Docker containers to discover the service #} diff --git a/roles/custom/matrix-synapse/defaults/main.yml b/roles/custom/matrix-synapse/defaults/main.yml index 2c070b47d..30517311c 100644 --- a/roles/custom/matrix-synapse/defaults/main.yml +++ b/roles/custom/matrix-synapse/defaults/main.yml @@ -513,7 +513,7 @@ matrix_synapse_allow_public_rooms_without_auth: false # # For private servers, you may wish to forbid it to align yourself with upstream defaults. # However, disabling federation completely (see `matrix_synapse_federation_enabled`) is a better way to make your server private, -# instead of relying on security-by-obscurity -- federating with others, having your public rooms joinable by anyone, +# instead of relying on security-by-obscurity — federating with others, having your public rooms joinable by anyone, # but hiding them and thinking you've secured them. matrix_synapse_allow_public_rooms_over_federation: true