From 90cfdabb2b227e2c613c3eb9d337cb04aa22bd17 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 17 Oct 2024 22:17:56 +0900 Subject: [PATCH] Replace DOMAIN with example.com Signed-off-by: Suguru Hirahara --- CHANGELOG.md | 38 +++++++------- docs/configuring-captcha.md | 2 +- ...figuring-playbook-alertmanager-receiver.md | 8 +-- ...uring-playbook-appservice-double-puppet.md | 2 +- ...ng-playbook-appservice-draupnir-for-all.md | 4 +- docs/configuring-playbook-backup-borg.md | 2 +- ...onfiguring-playbook-base-domain-serving.md | 12 ++--- docs/configuring-playbook-bot-baibot.md | 8 +-- docs/configuring-playbook-bot-buscarron.md | 14 +++--- docs/configuring-playbook-bot-chatgpt.md | 4 +- docs/configuring-playbook-bot-draupnir.md | 16 +++--- docs/configuring-playbook-bot-go-neb.md | 6 +-- docs/configuring-playbook-bot-honoroit.md | 4 +- ...ng-playbook-bot-matrix-registration-bot.md | 6 +-- ...guring-playbook-bot-matrix-reminder-bot.md | 6 +-- docs/configuring-playbook-bot-maubot.md | 2 +- docs/configuring-playbook-bot-mjolnir.md | 12 ++--- docs/configuring-playbook-bot-postmoogle.md | 4 +- ...figuring-playbook-bridge-appservice-irc.md | 2 +- ...ng-playbook-bridge-appservice-kakaotalk.md | 2 +- ...guring-playbook-bridge-appservice-slack.md | 8 +-- ...iguring-playbook-bridge-beeper-linkedin.md | 2 +- ...iguring-playbook-bridge-go-skype-bridge.md | 2 +- ...onfiguring-playbook-bridge-heisenbridge.md | 4 +- docs/configuring-playbook-bridge-hookshot.md | 4 +- ...uring-playbook-bridge-matrix-bridge-sms.md | 2 +- ...iguring-playbook-bridge-mautrix-discord.md | 2 +- ...guring-playbook-bridge-mautrix-facebook.md | 4 +- ...uring-playbook-bridge-mautrix-gmessages.md | 2 +- ...ring-playbook-bridge-mautrix-googlechat.md | 2 +- ...guring-playbook-bridge-mautrix-hangouts.md | 2 +- ...uring-playbook-bridge-mautrix-instagram.md | 2 +- ...-playbook-bridge-mautrix-meta-instagram.md | 2 +- ...-playbook-bridge-mautrix-meta-messenger.md | 2 +- ...figuring-playbook-bridge-mautrix-signal.md | 2 +- ...nfiguring-playbook-bridge-mautrix-slack.md | 2 +- ...guring-playbook-bridge-mautrix-telegram.md | 6 +-- ...iguring-playbook-bridge-mautrix-twitter.md | 2 +- ...guring-playbook-bridge-mautrix-whatsapp.md | 2 +- ...iguring-playbook-bridge-mautrix-wsproxy.md | 4 +- ...uring-playbook-bridge-mx-puppet-discord.md | 2 +- ...uring-playbook-bridge-mx-puppet-groupme.md | 2 +- ...ing-playbook-bridge-mx-puppet-instagram.md | 2 +- ...iguring-playbook-bridge-mx-puppet-slack.md | 4 +- ...iguring-playbook-bridge-mx-puppet-steam.md | 2 +- ...uring-playbook-bridge-mx-puppet-twitter.md | 2 +- docs/configuring-playbook-bridge-wechat.md | 2 +- docs/configuring-playbook-cactus-comments.md | 2 +- docs/configuring-playbook-client-cinny.md | 8 +-- docs/configuring-playbook-client-hydrogen.md | 8 +-- ...configuring-playbook-client-schildichat.md | 8 +-- docs/configuring-playbook-dimension.md | 2 +- docs/configuring-playbook-dynamic-dns.md | 2 +- docs/configuring-playbook-email.md | 2 +- docs/configuring-playbook-email2matrix.md | 6 +-- docs/configuring-playbook-etherpad.md | 10 ++-- .../configuring-playbook-external-postgres.md | 2 +- docs/configuring-playbook-federation.md | 2 +- docs/configuring-playbook-jitsi.md | 20 ++++---- docs/configuring-playbook-ldap-auth.md | 2 +- docs/configuring-playbook-ma1sd.md | 6 +-- docs/configuring-playbook-matrix-corporal.md | 2 +- ...playbook-matrix-ldap-registration-proxy.md | 2 +- .../configuring-playbook-matrix-media-repo.md | 4 +- ...onfiguring-playbook-matrix-registration.md | 6 +-- docs/configuring-playbook-mautrix-bridges.md | 8 +-- docs/configuring-playbook-ntfy.md | 4 +- docs/configuring-playbook-own-webserver.md | 4 +- docs/configuring-playbook-pantalaimon.md | 2 +- docs/configuring-playbook-postgres-backup.md | 2 +- ...configuring-playbook-prometheus-grafana.md | 22 ++++---- ...onfiguring-playbook-prometheus-nginxlog.md | 4 +- ...onfiguring-playbook-prometheus-postgres.md | 4 +- docs/configuring-playbook-rageshake.md | 6 +-- docs/configuring-playbook-rest-auth.md | 2 +- docs/configuring-playbook-riot-web.md | 8 +-- docs/configuring-playbook-s3-goofys.md | 2 +- docs/configuring-playbook-s3.md | 4 +- ...configuring-playbook-shared-secret-auth.md | 2 +- ...configuring-playbook-sliding-sync-proxy.md | 6 +-- docs/configuring-playbook-ssl-certificates.md | 4 +- docs/configuring-playbook-sygnal.md | 8 +-- docs/configuring-playbook-synapse-admin.md | 4 +- ...ing-playbook-synapse-auto-accept-invite.md | 2 +- ...guring-playbook-synapse-auto-compressor.md | 2 +- ...guring-playbook-synapse-simple-antispam.md | 2 +- ...iguring-playbook-synapse-usage-exporter.md | 4 +- docs/configuring-playbook-synapse.md | 4 +- docs/configuring-playbook-telemetry.md | 2 +- docs/configuring-playbook-traefik.md | 2 +- docs/configuring-playbook-turn.md | 2 +- ...ring-playbook-user-verification-service.md | 2 +- docs/faq.md | 50 +++++++++---------- docs/maintenance-and-troubleshooting.md | 2 +- docs/maintenance-migrating.md | 2 +- docs/maintenance-synapse.md | 2 +- docs/obtaining-access-tokens.md | 8 +-- docs/registering-users.md | 4 +- examples/reverse-proxies/apache/README.md | 4 +- .../apache/matrix-client-element.conf | 16 +++--- .../reverse-proxies/apache/matrix-domain.conf | 26 +++++----- .../nginx-proxy-manager/README.md | 10 ++-- examples/reverse-proxies/nginx/README.md | 2 +- group_vars/matrix_servers | 2 +- .../defaults/main.yml | 2 +- roles/custom/matrix-base/defaults/main.yml | 2 +- .../matrix-base/tasks/validate_config.yml | 2 +- .../matrix-bot-chatgpt/defaults/main.yml | 2 +- .../matrix-bot-chatgpt/templates/env.j2 | 2 +- .../tasks/validate_config.yml | 2 +- .../defaults/main.yml | 6 +-- .../defaults/main.yml | 6 +-- .../matrix-media-repo/defaults/main.yml | 2 +- .../matrix-registration/defaults/main.yml | 2 +- .../matrix-sliding-sync/defaults/main.yml | 2 +- .../matrix-static-files/defaults/main.yml | 4 +- .../defaults/main.yml | 2 +- roles/custom/matrix-synapse/defaults/main.yml | 4 +- 118 files changed, 304 insertions(+), 304 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 54535161d..8085178f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -195,7 +195,7 @@ matrix_synapse_admin_config_restrictBaseUrl: [] ## The URL-prefix for Hookshot generic webhooks has changed -Until now, generic Hookshot webhook URLs looked like this: `https://matrix.DOMAIN/hookshot/webhooks/:hookId`. +Until now, generic Hookshot webhook URLs looked like this: `https://matrix.example.com/hookshot/webhooks/:hookId`. The `/hookshot/webhooks` common prefix gets stripped by Traefik automatically, so Hookshot only sees the part that comes after (`/:hookId`). @@ -331,7 +331,7 @@ Refer to our new [Tuning caches and cache autotuning](docs/maintenance-synapse.m This only affects people who are [Serving a static website at the base domain](./docs/configuring-playbook-base-domain-serving.md#serving-a-static-website-at-the-base-domain), but not managing its `index.html` through the playbook. -That is, for people who have `matrix_static_files_file_index_html_enabled: false` in their `vars.yml` configuration, the playbook has a new default behavior. Since the playbook is not managing the `index.html` file, it will default to a more sensible way of handling the base domain - redirecting `https://DOMAIN/` to `https://matrix.DOMAIN/`, instead of serving a 404 page. +That is, for people who have `matrix_static_files_file_index_html_enabled: false` in their `vars.yml` configuration, the playbook has a new default behavior. Since the playbook is not managing the `index.html` file, it will default to a more sensible way of handling the base domain - redirecting `https://example.com/` to `https://matrix.example.com/`, instead of serving a 404 page. If you are managing your static website by yourself (by dropping files into `/matrix/static-files/public` somehow), then you probably don't wish for such redirection to happen. You can disable it by adding `matrix_static_files_container_labels_base_domain_root_path_redirection_enabled: false` to your `vars.yml` configuration file. @@ -448,7 +448,7 @@ To perform this new role, Traefik now has a new internal [entrypoint](https://do Doing so, services can contact Traefik on this entrypoint's dedicated port (the URL defaults to `http://matrix-traefik:8008`) and reach the homeserver Client-Server API as they expect. Internally, Traefik takes care of the routing to the correct service. -We've also considered keeping it simple and having services talk to the homeserver over the public internet (e.g. `https://matrix.DOMAIN`) thus reusing all existing Traefik routing labels. In this scenario, performance was incredibly poor (e.g. 70 rps, instead of 1400 rps) due to TLS and networking overhead. The need for fast internal communication (via the new internal non-TLS-enabled Traefik entrypoint) is definitely there. In our benchmarks, Traefik even proved more efficient than nginx at doing this: ~1200 rps for Traefik compared to ~900 rps for nginx (out of ~1400 rps when talking to the Synapse homeserver directly). +We've also considered keeping it simple and having services talk to the homeserver over the public internet (e.g. `https://matrix.example.com`) thus reusing all existing Traefik routing labels. In this scenario, performance was incredibly poor (e.g. 70 rps, instead of 1400 rps) due to TLS and networking overhead. The need for fast internal communication (via the new internal non-TLS-enabled Traefik entrypoint) is definitely there. In our benchmarks, Traefik even proved more efficient than nginx at doing this: ~1200 rps for Traefik compared to ~900 rps for nginx (out of ~1400 rps when talking to the Synapse homeserver directly). Traefik serving this second purpose has a few downsides: @@ -1378,15 +1378,15 @@ Various services (like Dimension, etc.) still talk to Synapse via `matrix-nginx- ## (Backward Compatibility Break) A new default standalone mode for Etherpad -Until now, [Etherpad](https://etherpad.org/) (which [the playbook could install for you](docs/configuring-playbook-etherpad.md)) required the [Dimension integration manager](docs/configuring-playbook-dimension.md) to also be installed, because Etherpad was hosted on the Dimension domain (at `dimension.DOMAIN/etherpad`). +Until now, [Etherpad](https://etherpad.org/) (which [the playbook could install for you](docs/configuring-playbook-etherpad.md)) required the [Dimension integration manager](docs/configuring-playbook-dimension.md) to also be installed, because Etherpad was hosted on the Dimension domain (at `dimension.example.com/etherpad`). -From now on, Etherpad can be installed in `standalone` mode on `etherpad.DOMAIN` and used even without Dimension. This is much more versatile, so the playbook now defaults to this new mode (`etherpad_mode: standalone`). +From now on, Etherpad can be installed in `standalone` mode on `etherpad.example.com` and used even without Dimension. This is much more versatile, so the playbook now defaults to this new mode (`etherpad_mode: standalone`). If you've already got both Etherpad and Dimension in use you could: - **either** keep hosting Etherpad under the Dimension domain by adding `etherpad_mode: dimension` to your `vars.yml` file. All your existing room widgets will continue working at the same URLs and no other changes will be necessary. -- **or**, you could change to hosting Etherpad separately on `etherpad.DOMAIN`. You will need to [configure a DNS record](docs/configuring-dns.md) for this new domain. You will also need to reconfigure Dimension to use the new pad URLs (`https://etherpad.DOMAIN/...`) going forward (refer to our [configuring Etherpad documentation](docs/configuring-playbook-etherpad.md)). All your existing room widgets (which still use `https://dimension.DOMAIN/etherpad/...`) will break as Etherpad is not hosted there anymore. You will need to re-add them or to consider not using `standalone` mode +- **or**, you could change to hosting Etherpad separately on `etherpad.example.com`. You will need to [configure a DNS record](docs/configuring-dns.md) for this new domain. You will also need to reconfigure Dimension to use the new pad URLs (`https://etherpad.example.com/...`) going forward (refer to our [configuring Etherpad documentation](docs/configuring-playbook-etherpad.md)). All your existing room widgets (which still use `https://dimension.example.com/etherpad/...`) will break as Etherpad is not hosted there anymore. You will need to re-add them or to consider not using `standalone` mode # 2022-11-04 @@ -1665,26 +1665,26 @@ See our [Setting up the ntfy push notifications server](docs/configuring-playboo **TLDR**: we've made extensive **changes to metrics exposure/collection, which concern people using an external Prometheus server**. If you don't know what that is, you don't need to read below. -**Why do major changes to metrics**? Because various services were exposing metrics in different, hacky, ways. Synapse was exposing metrics at `/_synapse/metrics` and `/_synapse-worker-.../metrics` on the `matrix.DOMAIN`. The Hookshot role was **repurposing** the Granana web UI domain (`stats.DOMAIN`) for exposing its metrics on `stats.DOMAIN/hookshot/metrics`, while protecting these routes using Basic Authentication **normally used for Synapse** (`/_synapse/metrics`). Node-exporter and Postgres-exporter roles were advising for more `stats.DOMAIN` usage in manual ways. Each role was doing things differently and mixing variables from other roles. Each metrics endpoint was ending up in a different place, protected by who knows what Basic Authentication credentials (if protected at all). +**Why do major changes to metrics**? Because various services were exposing metrics in different, hacky, ways. Synapse was exposing metrics at `/_synapse/metrics` and `/_synapse-worker-.../metrics` on the `matrix.example.com`. The Hookshot role was **repurposing** the Granana web UI domain (`stats.example.com`) for exposing its metrics on `stats.example.com/hookshot/metrics`, while protecting these routes using Basic Authentication **normally used for Synapse** (`/_synapse/metrics`). Node-exporter and Postgres-exporter roles were advising for more `stats.example.com` usage in manual ways. Each role was doing things differently and mixing variables from other roles. Each metrics endpoint was ending up in a different place, protected by who knows what Basic Authentication credentials (if protected at all). -**The solution**: a completely revamped way to expose metrics to an external Prometheus server. We are **introducing new `https://matrix.DOMAIN/metrics/*` endpoints**, where various services *can* expose their metrics, for collection by external Prometheus servers. To enable the `/metrics/*` endpoints, use `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`. There's also a way to protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). See the `matrix-nginx-proxy` role or our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation for additional variables around `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. +**The solution**: a completely revamped way to expose metrics to an external Prometheus server. We are **introducing new `https://matrix.example.com/metrics/*` endpoints**, where various services *can* expose their metrics, for collection by external Prometheus servers. To enable the `/metrics/*` endpoints, use `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`. There's also a way to protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). See the `matrix-nginx-proxy` role or our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation for additional variables around `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. **If you are using the [Hookshot bridge](docs/configuring-playbook-bridge-hookshot.md)**, you may find that: 1. **Metrics may not be enabled by default anymore**: - If Prometheus is enabled (`prometheus_enabled: true`), then Hookshot metrics will be enabled automatically (`matrix_hookshot_metrics_enabled: true`). These metrics will be collected from the local (in-container) Prometheus over the container network. - **If Prometheus is not enabled** (you are either not using Prometheus or are using an external one), **Hookshot metrics will not be enabled by default anymore**. Feel free to enable them by setting `matrix_hookshot_metrics_enabled: true`. Also, see below. -2. When metrics are meant to be **consumed by an external Prometheus server**, `matrix_hookshot_metrics_proxying_enabled` needs to be set to `true`, so that metrics would be exposed (proxied) "publicly" on `https://matrix.DOMAIN/metrics/hookshot`. To make use of this, you'll also need to enable the new `https://matrix.DOMAIN/metrics/*` endpoints mentioned above, using `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. Learn more in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. -3. **We've changed the URL we're exposing Hookshot metrics at** for external Prometheus servers. Until now, you were advised to consume Hookshot metrics from `https://stats.DOMAIN/hookshot/metrics` (working in conjunction with `matrix_nginx_proxy_proxy_synapse_metrics`). From now on, **this no longer works**. As described above, you need to start consuming metrics from `https://matrix.DOMAIN/metrics/hookshot`. +2. When metrics are meant to be **consumed by an external Prometheus server**, `matrix_hookshot_metrics_proxying_enabled` needs to be set to `true`, so that metrics would be exposed (proxied) "publicly" on `https://matrix.example.com/metrics/hookshot`. To make use of this, you'll also need to enable the new `https://matrix.example.com/metrics/*` endpoints mentioned above, using `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. Learn more in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. +3. **We've changed the URL we're exposing Hookshot metrics at** for external Prometheus servers. Until now, you were advised to consume Hookshot metrics from `https://stats.example.com/hookshot/metrics` (working in conjunction with `matrix_nginx_proxy_proxy_synapse_metrics`). From now on, **this no longer works**. As described above, you need to start consuming metrics from `https://matrix.example.com/metrics/hookshot`. -**If you're using node-exporter** (`matrix_prometheus_node_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_node_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.DOMAIN/metrics/node-exporter`. +**If you're using node-exporter** (`matrix_prometheus_node_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_node_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.example.com/metrics/node-exporter`. -**If you're using [postgres-exporter](docs/configuring-playbook-prometheus-postgres.md)** (`prometheus_postgres_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_services_proxy_connect_prometheus_postgres_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.DOMAIN/metrics/postgres-exporter`. +**If you're using [postgres-exporter](docs/configuring-playbook-prometheus-postgres.md)** (`prometheus_postgres_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_services_proxy_connect_prometheus_postgres_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.example.com/metrics/postgres-exporter`. **If you're using Synapse** and would like to collect its metrics from an external Prometheus server, you may find that: 1. Exposing metrics is now done using `matrix_synapse_metrics_proxying_enabled`, not `matrix_nginx_proxy_proxy_synapse_metrics: true`. You may still need to enable metrics using `matrix_synapse_metrics_enabled: true` before exposing them. 2. Protecting metrics endpoints using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) is now done in another way. See our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation -3. If Synapse metrics are exposed, they will be made available at `https://matrix.DOMAIN/metrics/synapse/main-process` or `https://matrix.DOMAIN/metrics/synapse/worker/TYPE-ID` (when workers are enabled), not at `https://matrix.DOMAIN/_synapse/metrics` and `https://matrix.DOMAIN/_synapse-worker-.../metrics` +3. If Synapse metrics are exposed, they will be made available at `https://matrix.example.com/metrics/synapse/main-process` or `https://matrix.example.com/metrics/synapse/worker/TYPE-ID` (when workers are enabled), not at `https://matrix.example.com/_synapse/metrics` and `https://matrix.example.com/_synapse-worker-.../metrics` 4. The playbook still generates an `external_prometheus.yml.example` sample file for scraping Synapse from Prometheus as described in [Collecting Synapse worker metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-synapse-worker-metrics-to-an-external-prometheus-server), but it's now saved under `/matrix/synapse` (not `/matrix`). **If you where already using a external Prometheus server** before this change, and you gave a hashed version of the password as a variable, the playbook will now take care of hashing the password for you. Thus, you need to provide the non-hashed version now. @@ -2074,7 +2074,7 @@ Thanks to [@Peetz0r](https://github.com/Peetz0r), the playbook can now install a To get get these installed, follow our [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) docs page. -This update comes with a **potential breaking change** for people who were already exposing Synapse metrics (for consumption via another Prometheus installation). From now on, `matrix_synapse_metrics_enabled: true` no longer exposes metrics publicly via matrix-nginx-proxy (at `https://matrix.DOMAIN/_synapse/metrics`). To do so, you'd need to explicitly set `matrix_nginx_proxy_proxy_synapse_metrics: true`. +This update comes with a **potential breaking change** for people who were already exposing Synapse metrics (for consumption via another Prometheus installation). From now on, `matrix_synapse_metrics_enabled: true` no longer exposes metrics publicly via matrix-nginx-proxy (at `https://matrix.example.com/_synapse/metrics`). To do so, you'd need to explicitly set `matrix_nginx_proxy_proxy_synapse_metrics: true`. # 2021-01-31 @@ -2122,7 +2122,7 @@ To migrate to the new setup, expect a few minutes of downtime, while you follow 2. Generate a strong password to be used for your superuser Postgres user (called `matrix`). You can use `pwgen -s 64 1` to generate it, or some other tool. The **maximum length** for a Postgres password is 100 bytes (characters). Don't go crazy! -3. Update your playbook's `inventory/host_vars/matrix.DOMAIN/vars.yml` file, adding a line like this: +3. Update your playbook's `inventory/host_vars/matrix.example.com/vars.yml` file, adding a line like this: ```yaml matrix_postgres_connection_password: 'YOUR_POSTGRES_PASSWORD_HERE' ``` @@ -2404,11 +2404,11 @@ To learn more, follow our [Dynamic DNS docs page](docs/configuring-playbook-dyna # 2020-10-28 -## (Compatibility Break) https://matrix.DOMAIN/ now redirects to https://element.DOMAIN/ +## (Compatibility Break) https://matrix.example.com/ now redirects to https://element.example.com/ -Until now, we used to serve a static page coming from Synapse at `https://matrix.DOMAIN/`. This page was not very useful to anyone. +Until now, we used to serve a static page coming from Synapse at `https://matrix.example.com/`. This page was not very useful to anyone. -Since `matrix.DOMAIN` may be accessed by regular users in certain conditions, it's probably better to redirect them to a better place (e.g. to the [Element](docs/configuring-playbook-client-element.md) client). +Since `matrix.example.com` may be accessed by regular users in certain conditions, it's probably better to redirect them to a better place (e.g. to the [Element](docs/configuring-playbook-client-element.md) client). If Element is installed (`matrix_client_element_enabled: true`, which it is by default), we now redirect people to it, instead of showing them a Synapse static page. @@ -2420,7 +2420,7 @@ To restore the old behavior of not redirecting anywhere and serving the Synapse ## (Compatibility Break) /_synapse/admin is no longer publicly exposed by default -We used to expose the Synapse Admin APIs publicly (at `https://matrix.DOMAIN/_synapse/admin`). +We used to expose the Synapse Admin APIs publicly (at `https://matrix.example.com/_synapse/admin`). These APIs require authentication with a valid access token, so it's not that big a deal to expose them. However, following [official Synapse's reverse-proxying recommendations](https://github.com/element-hq/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints), we're no longer exposing `/_synapse/admin` by default. diff --git a/docs/configuring-captcha.md b/docs/configuring-captcha.md index 1989d66ee..8d46891d0 100644 --- a/docs/configuring-captcha.md +++ b/docs/configuring-captcha.md @@ -16,7 +16,7 @@ Must be a reCAPTCHA **v2** key using the "I'm not a robot" Checkbox option ### Setting ReCaptcha keys -Once registered as above, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Once registered as above, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml # for Synapse diff --git a/docs/configuring-playbook-alertmanager-receiver.md b/docs/configuring-playbook-alertmanager-receiver.md index fbd50e85f..b7952c3bc 100644 --- a/docs/configuring-playbook-alertmanager-receiver.md +++ b/docs/configuring-playbook-alertmanager-receiver.md @@ -10,7 +10,7 @@ This service is meant to be used with an external [Alertmanager](https://prometh ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yml matrix_alertmanager_receiver_enabled: true @@ -33,10 +33,10 @@ matrix_alertmanager_receiver_config_matrix_access_token: '' # Optionally, configure some mappings (URL-friendly room name -> actual Matrix room ID). # # If you don't configure mappings, you can still deliver alerts using URLs like this: -# https://matrix.DOMAIN/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!some-room-id:example.com +# https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!some-room-id:example.com # # If a mapping like the one below is configured, you can deliver alerts using friendlier URLs like this: -# https://matrix.DOMAIN/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name +# https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name matrix_alertmanager_receiver_config_matrix_room_mapping: some-room-name: "!some-room-id:{{ matrix_domain }}" ``` @@ -89,6 +89,6 @@ route: - receiver: matrix ``` -.. where `URL_HERE` looks like `https://matrix.DOMAIN/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name` or `https://matrix.DOMAIN/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!some-room-id:DOMAIN`. +.. where `URL_HERE` looks like `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name` or `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!some-room-id:example.com`. This bot does **not** accept room invitations automatically (like many other bots do). To deliver messages to rooms, **the bot must be joined to all rooms manually** - see Step 5 of the [Account and room preparation](#account-and-room-preparation) section. diff --git a/docs/configuring-playbook-appservice-double-puppet.md b/docs/configuring-playbook-appservice-double-puppet.md index 5e0886a30..814f34b9a 100644 --- a/docs/configuring-playbook-appservice-double-puppet.md +++ b/docs/configuring-playbook-appservice-double-puppet.md @@ -8,7 +8,7 @@ Previously, bridges supported performing [double-puppeting](https://docs.mau.fi/ ## Adjusting the playbook configuration -To enable the Appservice Double Puppet service, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the Appservice Double Puppet service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yml matrix_appservice_double_puppet_enabled: true diff --git a/docs/configuring-playbook-appservice-draupnir-for-all.md b/docs/configuring-playbook-appservice-draupnir-for-all.md index 6205fd872..760c3e751 100644 --- a/docs/configuring-playbook-appservice-draupnir-for-all.md +++ b/docs/configuring-playbook-appservice-draupnir-for-all.md @@ -38,7 +38,7 @@ Give the room from step 1 an alias. This alias can be anything you want and its ### 3. Adjusting the playbook configuration. -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): You must replace `ALIAS_FROM_STEP_2_GOES_HERE` with the alias you created in step 2. @@ -83,7 +83,7 @@ You can refer to the upstream [documentation](https://github.com/the-draupnir-pr Please note that Config extension does not affect the appservices config as this config is not extensible in current Draupnir anyways. Config extension instead touches the config passed to the Draupnirs that your Appservice creates. So for example below makes all provisioned Draupnirs protect all joined rooms. -You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file. +You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file. For example to change draupnir's `protectAllJoinedRooms` option to `true` you would add the following to your `vars.yml` file. diff --git a/docs/configuring-playbook-backup-borg.md b/docs/configuring-playbook-backup-borg.md index a1158b5e5..cf5f66482 100644 --- a/docs/configuring-playbook-backup-borg.md +++ b/docs/configuring-playbook-backup-borg.md @@ -35,7 +35,7 @@ cat PUBKEY | ssh USER@HOST 'dd of=.ssh/authorized_keys oflag=append conv=notrunc ## Adjusting the playbook configuration -Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable borg backup: +Minimal working configuration (`inventory/host_vars/matrix.example.com/vars.yml`) to enable borg backup: ```yaml backup_borg_enabled: true diff --git a/docs/configuring-playbook-base-domain-serving.md b/docs/configuring-playbook-base-domain-serving.md index e294a672c..f999d50fc 100644 --- a/docs/configuring-playbook-base-domain-serving.md +++ b/docs/configuring-playbook-base-domain-serving.md @@ -1,7 +1,7 @@ # Serving the base domain -This playbook sets up services on your Matrix server (`matrix.DOMAIN`). -To have this server officially be responsible for Matrix services for the base domain (`DOMAIN`), you need to set up [Server Delegation](howto-server-delegation.md). +This playbook sets up services on your Matrix server (`matrix.example.com`). +To have this server officially be responsible for Matrix services for the base domain (`example.com`), you need to set up [Server Delegation](howto-server-delegation.md). This is normally done by [configuring well-known](configuring-well-known.md) files on the base domain. People who don't have a separate server to dedicate to the base domain have trouble arranging this. @@ -14,7 +14,7 @@ Usually, there are 2 options: This documentation page tells you how to do the latter. With some easy changes, we make it possible to serve the base domain from the Matrix server via the integrated webserver. -Just **adjust your DNS records**, so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then add the following configuration** to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Just **adjust your DNS records**, so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then add the following configuration** to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_static_files_container_labels_base_domain_enabled: true @@ -26,7 +26,7 @@ Doing this, the playbook will: - serve the `/.well-known/matrix/*` files which are necessary for [Federation Server Discovery](configuring-well-known.md#introduction-to-client-server-discovery) (also see [Server Delegation](howto-server-delegation.md)) and [Client-Server discovery](configuring-well-known.md#introduction-to-client-server-discovery) -- serve a simple homepage at `https://DOMAIN` with content `Hello from DOMAIN` (configurable via the `matrix_static_files_file_index_html_template` variable). You can also [serve a more complicated static website](#serving-a-static-website-at-the-base-domain). +- serve a simple homepage at `https://example.com` with content `Hello from example.com` (configurable via the `matrix_static_files_file_index_html_template` variable). You can also [serve a more complicated static website](#serving-a-static-website-at-the-base-domain). ## Serving a static website at the base domain @@ -43,7 +43,7 @@ matrix_static_files_container_labels_base_domain_enabled: true # Prevent the default index.html file from being installed matrix_static_files_file_index_html_enabled: false -# Disable the automatic redirectin of `https://DOMAIN/` to `https://matrix.DOMAIN/`. +# Disable the automatic redirectin of `https://example.com/` to `https://matrix.example.com/`. # This gets automatically enabled when you disable `matrix_static_files_file_index_html_enabled`, as we're doing above. matrix_static_files_container_labels_base_domain_root_path_redirection_enabled: false ``` @@ -65,7 +65,7 @@ You have 2 options. - [configuring Matrix Delegation via well-known](./configuring-well-known.md) **Another way is to serve the base domain from another (your own) container on the Matrix server**. This involves: -- telling the playbook to only serve `BASE_DOMAIN/.well-known/matrix` files by adjusting your `vars.yml` configuration like this: +- telling the playbook to only serve `example.com/.well-known/matrix` files by adjusting your `vars.yml` configuration like this: - keep `matrix_static_files_container_labels_base_domain_enabled: true` - add an extra: `matrix_static_files_container_labels_base_domain_traefik_path_prefix: /.well-known/matrix` - building and running a new container on the Matrix server: diff --git a/docs/configuring-playbook-bot-baibot.md b/docs/configuring-playbook-bot-baibot.md index 86785d3c3..5b3c5af4d 100644 --- a/docs/configuring-playbook-bot-baibot.md +++ b/docs/configuring-playbook-bot-baibot.md @@ -33,7 +33,7 @@ Depending on your current `vars.yml` file and desired configuration, **you may r ### Base configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_baibot_enabled: true @@ -82,7 +82,7 @@ To specify who is considered a bot [👮‍♂️ Administrator](https://github. If `matrix_admin` is already configured in your `vars.yml` configuration, you can skip this section. -**If necessary**, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +**If necessary**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yml # Uncomment to add one or more admins to this bridge: @@ -111,7 +111,7 @@ Configuring `matrix_bot_baibot_config_initial_global_config_user_patterns` is op **Note**: Once initially configured, the allowed users list **cannot be managed via Ansible anymore**. It can only be managed subsequently via bot commands. -**If necessary**, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +**If necessary**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yml # Uncomment and adjust the bot users if necessary: @@ -391,7 +391,7 @@ just run-tags install-all,ensure-matrix-users-created,start ## Usage -To use the bot, invite the `@baibot:DOMAIN` bot user into a room. +To use the bot, invite the `@baibot:example.com` bot user into a room. If you're an allowed bot [👥 user](https://github.com/etkecc/baibot/blob/main/docs/access.md#user) (see [👥 Initial users configuration](#-initial-users-configuration)), the bot will accept your invitation and join the room. diff --git a/docs/configuring-playbook-bot-buscarron.md b/docs/configuring-playbook-bot-buscarron.md index e04ce58e2..fb01bb2ae 100644 --- a/docs/configuring-playbook-bot-buscarron.md +++ b/docs/configuring-playbook-bot-buscarron.md @@ -7,12 +7,12 @@ Buscarron is bot that receives HTTP POST submissions of web forms and forwards t ## Decide on a domain and path -By default, Buscarron is configured to use its own dedicated domain (`buscarron.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records). +By default, Buscarron is configured to use its own dedicated domain (`buscarron.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records). You can override the domain and path like this: ```yaml -# Switch to the domain used for Matrix services (`matrix.DOMAIN`), +# Switch to the domain used for Matrix services (`matrix.example.com`), # so we won't need to add additional DNS records for Buscarron. matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}" @@ -30,7 +30,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_buscarron_enabled: true @@ -43,9 +43,9 @@ matrix_bot_buscarron_password: PASSWORD_FOR_THE_BOT # Adjust accepted forms matrix_bot_buscarron_forms: - - name: contact # (mandatory) Your form name, will be used as endpoint, eg: buscarron.DOMAIN/contact + - name: contact # (mandatory) Your form name, will be used as endpoint, eg: buscarron.example.com/contact room: "!yourRoomID:{{ matrix_domain }}" # (mandatory) Room ID where form submission will be posted - redirect: https://DOMAIN # (mandatory) To what page user will be redirected after the form submission + redirect: https://example.com # (mandatory) To what page user will be redirected after the form submission ratelimit: 1r/m # (optional) rate limit of the form, format: r/, eg: 1r/s or 54r/m hasemail: 1 # (optional) form has "email" field that should be validated extensions: [] # (optional) list of form extensions (not used yet) @@ -71,10 +71,10 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage -To use the bot, invite the `@bot.buscarron:DOMAIN` to the room you specified in a config, after that any point your form to the form url, example for the `contact` form: +To use the bot, invite the `@bot.buscarron:example.com` to the room you specified in a config, after that any point your form to the form url, example for the `contact` form: ```html -
+
``` diff --git a/docs/configuring-playbook-bot-chatgpt.md b/docs/configuring-playbook-bot-chatgpt.md index eace08d66..100b1060c 100644 --- a/docs/configuring-playbook-bot-chatgpt.md +++ b/docs/configuring-playbook-bot-chatgpt.md @@ -31,7 +31,7 @@ To make sure the bot can read encrypted messages, it will need an encryption key ## 3. Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_bot_chatgpt_enabled: true @@ -66,6 +66,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start ## Usage -To use the bot, invite the `@bot.chatgpt:DOMAIN` to the room you specified in a config, after that start speaking to it, use the prefix if you configured one or mention the bot. +To use the bot, invite the `@bot.chatgpt:example.com` to the room you specified in a config, after that start speaking to it, use the prefix if you configured one or mention the bot. You can also refer to the upstream [documentation](https://github.com/matrixgpt/matrix-chatgpt-bot). diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 95540ffe9..a591f96ed 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -47,9 +47,9 @@ Using your own account, create a new invite only room that you will use to manag If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below). -Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:DOMAIN`. +Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:example.com`. -Finally invite the `@bot.draupnir:DOMAIN` account you created earlier into the room. +Finally invite the `@bot.draupnir:example.com` account you created earlier into the room. ## 5. Adjusting the playbook configuration @@ -60,7 +60,7 @@ Decide whether you want Draupnir to be capable of operating in end-to-end encryp When using Pantalaimon, Draupnir will log in to its bot account itself through Pantalaimon, so configure its username and password. -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml # Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md @@ -95,7 +95,7 @@ matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_ When NOT using Pantalaimon, Draupnir does not log in by itself and you must give it an access token for its bot account. -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with the your own values. @@ -135,7 +135,7 @@ Draupnir can be told to self-join public rooms, but it's better to follow this f 2. [Give the bot permissions to do its job](#giving-draupnir-permissions-to-do-its-job) -3. Tell it to protect the room (using the [rooms command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#using-the-draupnir-rooms-command)) by sending the following command to the Management Room: `!draupnir rooms add !ROOM_ID:DOMAIN` +3. Tell it to protect the room (using the [rooms command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#using-the-draupnir-rooms-command)) by sending the following command to the Management Room: `!draupnir rooms add !ROOM_ID:example.com` To have Draupnir provide useful room protection, you need do to a bit more work (at least the first time around). You may wish to [Subscribe to a public policy list](#subscribing-to-a-public-policy-list), [Create your own own policy and rules](#creating-your-own-policy-lists-and-rules) and [Enabling built-in protections](#enabling-built-in-protections). @@ -158,7 +158,7 @@ You can tell Draupnir to subscribe to it by sending the following command to the We also recommend **creating your own policy lists** with the [list create](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-policy-lists#using-draupnirs-list-create-command-to-create-a-policy-room) command. -You can do so by sending the following command to the Management Room: `!draupnir list create my-bans my-bans-bl`. This will create a policy list having a name (shortcode) of `my-bans` and stored in a public `#my-bans-bl:DOMAIN` room on your server. As soon as you run this command, the bot will invite you to the policy list room. +You can do so by sending the following command to the Management Room: `!draupnir list create my-bans my-bans-bl`. This will create a policy list having a name (shortcode) of `my-bans` and stored in a public `#my-bans-bl:example.com` room on your server. As soon as you run this command, the bot will invite you to the policy list room. A policy list does nothing by itself, so the next step is **adding some rules to your policy list**. Policies target a so-called `entity` (one of: `user`, `room` or `server`). These entities are mentioned on the [policy lists](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists) documentation page and in the Matrix Spec [here](https://spec.matrix.org/v1.11/client-server-api/#mban-recommendation). @@ -171,7 +171,7 @@ To create rules, you run commands in the Management Room (**not** in the policy As a result of running these commands, you may observe: -- Draupnir creating `m.policy.rule.user` state events in the `#my-bans-bl:DOMAIN` room on your server +- Draupnir creating `m.policy.rule.user` state events in the `#my-bans-bl:example.com` room on your server - applying these rules against all rooms that Draupnir is an Administrator in You can undo bans with the [unban command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#the-unban-command). @@ -193,7 +193,7 @@ To **disable a given protection**, send a command like this: `!draupnir disable ## Extending the configuration -You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file. +You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file. For example to change draupnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file. diff --git a/docs/configuring-playbook-bot-go-neb.md b/docs/configuring-playbook-bot-go-neb.md index 5e01d83dd..8e5e08a5f 100644 --- a/docs/configuring-playbook-bot-go-neb.md +++ b/docs/configuring-playbook-bot-go-neb.md @@ -26,12 +26,12 @@ Once the user is created you can [obtain an access token](obtaining-access-token ## Decide on a domain and path -By default, Go-NEB is configured to use its own dedicated domain (`goneb.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records). +By default, Go-NEB is configured to use its own dedicated domain (`goneb.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records). You can override the domain and path like this: ```yaml -# Switch to the domain used for Matrix services (`matrix.DOMAIN`), +# Switch to the domain used for Matrix services (`matrix.example.com`), # so we won't need to add additional DNS records for Go-NEB. matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}" @@ -49,7 +49,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_bot_go_neb_enabled: true diff --git a/docs/configuring-playbook-bot-honoroit.md b/docs/configuring-playbook-bot-honoroit.md index 9f88ee8dd..496dc1b16 100644 --- a/docs/configuring-playbook-bot-honoroit.md +++ b/docs/configuring-playbook-bot-honoroit.md @@ -9,7 +9,7 @@ See the project's [documentation](https://github.com/etkecc/honoroit#how-it-look ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_honoroit_enabled: true @@ -46,7 +46,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage -To use the bot, invite the `@honoroit:DOMAIN` to the room you specified in config, after that any matrix user can send a message to the `@honoroit:DOMAIN` to start a new thread in that room. +To use the bot, invite the `@honoroit:example.com` to the room you specified in config, after that any matrix user can send a message to the `@honoroit:example.com` to start a new thread in that room. Send `!ho help` to the room to see the bot's help menu for additional commands. diff --git a/docs/configuring-playbook-bot-matrix-registration-bot.md b/docs/configuring-playbook-bot-matrix-registration-bot.md index 5ce317ed6..17c12e8e2 100644 --- a/docs/configuring-playbook-bot-matrix-registration-bot.md +++ b/docs/configuring-playbook-bot-matrix-registration-bot.md @@ -11,12 +11,12 @@ does and why it might be useful to you. ## Configuration -To enable the bot, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_matrix_registration_bot_enabled: true -# By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:DOMAIN`. +# By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:example.com`. # Uncomment and adjust this part if you'd like to use a username different than the default # matrix_bot_matrix_registration_bot_matrix_user_id_localpart: bot.matrix-registration-bot @@ -38,7 +38,7 @@ After configuring the playbook, run the [installation](installing.md) command: ` ## Usage -To use the bot, start a chat with `@bot.matrix-registration-bot:DOMAIN` (where `DOMAIN` is your base domain, not the `matrix.` domain). +To use the bot, start a chat with `@bot.matrix-registration-bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). In this room send `help` and the bot will reply with all options. diff --git a/docs/configuring-playbook-bot-matrix-reminder-bot.md b/docs/configuring-playbook-bot-matrix-reminder-bot.md index 3336d191a..2bce34765 100644 --- a/docs/configuring-playbook-bot-matrix-reminder-bot.md +++ b/docs/configuring-playbook-bot-matrix-reminder-bot.md @@ -9,7 +9,7 @@ See the project's [documentation](https://github.com/anoadragon453/matrix-remind ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_matrix_reminder_bot_enabled: true @@ -42,9 +42,9 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage -To use the bot, start a chat with `@bot.matrix-reminder-bot:DOMAIN` (where `example.com` is your base domain, not the `matrix.` domain). +To use the bot, start a chat with `@bot.matrix-reminder-bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -You can also add the bot to any existing Matrix room (`/invite @bot.matrix-reminder-bot:DOMAIN`). +You can also add the bot to any existing Matrix room (`/invite @bot.matrix-reminder-bot:example.com`). Basic usage is like this: `!remindme in 2 minutes; This is a test` diff --git a/docs/configuring-playbook-bot-maubot.md b/docs/configuring-playbook-bot-maubot.md index f90dd6bf3..f435492c3 100644 --- a/docs/configuring-playbook-bot-maubot.md +++ b/docs/configuring-playbook-bot-maubot.md @@ -10,7 +10,7 @@ does and why it might be useful to you. ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_maubot_enabled: true diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index dd7681d06..589850ee4 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -41,9 +41,9 @@ Using your own account, create a new invite only room that you will use to manag If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below). -Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:DOMAIN`. +Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:example.com`. -Finally invite the `@bot.mjolnir:DOMAIN` account you created earlier into the room. +Finally invite the `@bot.mjolnir:example.com` account you created earlier into the room. ## 5. Adjusting the playbook configuration @@ -54,7 +54,7 @@ Decide whether you want Mjolnir to be capable of operating in end-to-end encrypt When using Pantalaimon, Mjolnir will log in to its bot account itself through Pantalaimon, so configure its username and password. -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml # Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md @@ -89,7 +89,7 @@ matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_u When NOT using Pantalaimon, Mjolnir does not log in by itself and you must give it an access token for its bot account. -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with the your own values. @@ -103,7 +103,7 @@ matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE" ## 6. Adding Mjolnir synapse antispam module (optional) -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml @@ -128,7 +128,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start You can refer to the upstream [documentation](https://github.com/matrix-org/mjolnir) for additional ways to use and configure Mjolnir. Check out their [quickstart guide](https://github.com/matrix-org/mjolnir#quickstart-guide) for some basic commands you can give to the bot. -You can configure additional options by adding the `matrix_bot_mjolnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file. +You can configure additional options by adding the `matrix_bot_mjolnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file. For example to change Mjolnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file. diff --git a/docs/configuring-playbook-bot-postmoogle.md b/docs/configuring-playbook-bot-postmoogle.md index 35f141a4d..4af99aba9 100644 --- a/docs/configuring-playbook-bot-postmoogle.md +++ b/docs/configuring-playbook-bot-postmoogle.md @@ -25,7 +25,7 @@ These port numbers are configurable via the `matrix_bot_postmoogle_smtp_host_bin ### Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_postmoogle_enabled: true @@ -69,7 +69,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage -To use the bot, invite the `@postmoogle:DOMAIN` bot user into a room you want to use as a mailbox. +To use the bot, invite the `@postmoogle:example.com` bot user into a room you want to use as a mailbox. Then send `!pm mailbox NAME` to expose this Matrix room as an inbox with the email address `NAME@matrix.domain`. Emails sent to that email address will be forwarded to the room. diff --git a/docs/configuring-playbook-bridge-appservice-irc.md b/docs/configuring-playbook-bridge-appservice-irc.md index 4da559790..82623b998 100644 --- a/docs/configuring-playbook-bridge-appservice-irc.md +++ b/docs/configuring-playbook-bridge-appservice-irc.md @@ -8,7 +8,7 @@ See the project's [documentation](https://github.com/matrix-org/matrix-appservic ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_appservice_irc_enabled: true diff --git a/docs/configuring-playbook-bridge-appservice-kakaotalk.md b/docs/configuring-playbook-bridge-appservice-kakaotalk.md index 4a004eb1a..cbc52a6cc 100644 --- a/docs/configuring-playbook-bridge-appservice-kakaotalk.md +++ b/docs/configuring-playbook-bridge-appservice-kakaotalk.md @@ -9,7 +9,7 @@ See the project's [documentation](https://src.miscworks.net/fair/matrix-appservi ## Installing -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_appservice_kakaotalk_enabled: true diff --git a/docs/configuring-playbook-bridge-appservice-slack.md b/docs/configuring-playbook-bridge-appservice-slack.md index 5c970dcc5..4e1619b66 100644 --- a/docs/configuring-playbook-bridge-appservice-slack.md +++ b/docs/configuring-playbook-bridge-appservice-slack.md @@ -12,7 +12,7 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se 1. Create a new Matrix room to act as the administration control room. Note its internal room ID. This can be done in Element by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top. -2. Enable the bridge by adding the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +2. Enable the bridge by adding the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_appservice_slack_enabled: true @@ -40,7 +40,7 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se 6. Invite the bridge bot user into the admin room: ``` - /invite @slackbot:MY.DOMAIN + /invite @slackbot:MY.example.com ``` Note that the bot's domain is your server's domain **without the `matrix.` prefix.** @@ -53,7 +53,7 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se Click on bot users and add a new bot user. We will use this account to bridge the the rooms. -8. Click on Event Subscriptions and enable them and use the request url `https://matrix.DOMAIN/appservice-slack`. Then add the following events and save: +8. Click on Event Subscriptions and enable them and use the request url `https://matrix.example.com/appservice-slack`. Then add the following events and save: Bot User Events: @@ -81,7 +81,7 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se * Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like !aBcDeF: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:MY.DOMAIN` for Matrix. + * Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:MY.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/`. diff --git a/docs/configuring-playbook-bridge-beeper-linkedin.md b/docs/configuring-playbook-bridge-beeper-linkedin.md index 3aaa01520..5ba0233ec 100644 --- a/docs/configuring-playbook-bridge-beeper-linkedin.md +++ b/docs/configuring-playbook-bridge-beeper-linkedin.md @@ -6,7 +6,7 @@ See the project's [documentation](https://github.com/beeper/linkedin/blob/master ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_beeper_linkedin_enabled: true diff --git a/docs/configuring-playbook-bridge-go-skype-bridge.md b/docs/configuring-playbook-bridge-go-skype-bridge.md index c9001636a..10a244aa0 100644 --- a/docs/configuring-playbook-bridge-go-skype-bridge.md +++ b/docs/configuring-playbook-bridge-go-skype-bridge.md @@ -7,7 +7,7 @@ See the project page to learn what it does and why it might be useful to you. ## Adjusting the playbook configuration -To enable the [Skype](https://www.skype.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the [Skype](https://www.skype.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_go_skype_bridge_enabled: true diff --git a/docs/configuring-playbook-bridge-heisenbridge.md b/docs/configuring-playbook-bridge-heisenbridge.md index b6eb23634..75c6b1315 100644 --- a/docs/configuring-playbook-bridge-heisenbridge.md +++ b/docs/configuring-playbook-bridge-heisenbridge.md @@ -10,7 +10,7 @@ See the project's [README](https://github.com/hifi/heisenbridge/blob/master/READ Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/custom/matrix-bridge-heisenbridge/defaults/main.yml). -At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.DOMAIN/vars.yml`): +At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.example.com/vars.yml`): ```yaml matrix_heisenbridge_enabled: true @@ -22,7 +22,7 @@ matrix_heisenbridge_owner: "@you:your-homeserver" matrix_heisenbridge_identd_enabled: true ``` -By default, Heisenbrdige would be exposed on the Matrix domain (`matrix.DOMAIN`, as specified in `matrix_server_fqn_matrix`) under the `/heisenbridge` path prefix. It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)). +By default, Heisenbrdige would be exposed on the Matrix domain (`matrix.example.com`, as specified in `matrix_server_fqn_matrix`) under the `/heisenbridge` path prefix. It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)). That's it! A registration file is automatically generated during the setup phase. diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md index 812697b9c..3bb1ba0ab 100644 --- a/docs/configuring-playbook-bridge-hookshot.md +++ b/docs/configuring-playbook-bridge-hookshot.md @@ -31,7 +31,7 @@ Should the crypto store be corrupted, you can reset it by executing this Ansible ## Usage -Create a room and invite the Hookshot bot (`@hookshot:DOMAIN`) to it. +Create a room and invite the Hookshot bot (`@hookshot:example.com`) to it. Make sure the bot is able to send state events (usually the Moderator power level in clients). @@ -92,7 +92,7 @@ Metrics are **only enabled by default** if the builtin [Prometheus](configuring- To explicitly enable metrics, use `matrix_hookshot_metrics_enabled: true`. This only exposes metrics over the container network, however. -**To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to enable metrics exposure on `https://matrix.DOMAIN/metrics/hookshot` by: +**To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to enable metrics exposure on `https://matrix.example.com/metrics/hookshot` by: - either enabling metrics exposure for Hookshot via `matrix_hookshot_metrics_proxying_enabled: true` - or enabling metrics exposure for all services via `matrix_metrics_exposure_enabled: true` diff --git a/docs/configuring-playbook-bridge-matrix-bridge-sms.md b/docs/configuring-playbook-bridge-matrix-bridge-sms.md index fe883abb5..f698ad986 100644 --- a/docs/configuring-playbook-bridge-matrix-bridge-sms.md +++ b/docs/configuring-playbook-bridge-matrix-bridge-sms.md @@ -8,7 +8,7 @@ See the project page to learn what it does and why it might be useful to you. ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_sms_bridge_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-discord.md b/docs/configuring-playbook-bridge-mautrix-discord.md index 184addf6b..d7da7878b 100644 --- a/docs/configuring-playbook-bridge-mautrix-discord.md +++ b/docs/configuring-playbook-bridge-mautrix-discord.md @@ -17,7 +17,7 @@ If this is a dealbreaker for you, consider using one of the other Discord bridge ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_discord_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-facebook.md b/docs/configuring-playbook-bridge-mautrix-facebook.md index e20d1e2e6..50d23a0fd 100644 --- a/docs/configuring-playbook-bridge-mautrix-facebook.md +++ b/docs/configuring-playbook-bridge-mautrix-facebook.md @@ -8,7 +8,7 @@ See the project's [documentation](https://github.com/mautrix/facebook/blob/maste ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_facebook_enabled: true @@ -98,7 +98,7 @@ The easiest way to do this may be to use [sshuttle](https://sshuttle.readthedocs Example command for proxying your traffic through the Matrix server: ``` -sshuttle -r root@matrix.DOMAIN:22 0/0 +sshuttle -r root@matrix.example.com:22 0/0 ``` Once connected, you should be able to verify that you're browsing the web through the Matrix server's IP by checking [icanhazip](https://icanhazip.com/). diff --git a/docs/configuring-playbook-bridge-mautrix-gmessages.md b/docs/configuring-playbook-bridge-mautrix-gmessages.md index e07646743..6b44eeeee 100644 --- a/docs/configuring-playbook-bridge-mautrix-gmessages.md +++ b/docs/configuring-playbook-bridge-mautrix-gmessages.md @@ -6,7 +6,7 @@ See the project's [documentation](https://docs.mau.fi/bridges/go/gmessages/index ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_gmessages_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-googlechat.md b/docs/configuring-playbook-bridge-mautrix-googlechat.md index ed6270c8a..a62003cb2 100644 --- a/docs/configuring-playbook-bridge-mautrix-googlechat.md +++ b/docs/configuring-playbook-bridge-mautrix-googlechat.md @@ -6,7 +6,7 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/googlechat/ ## Adjusting the playbook configuration -To enable the [Google Chat](https://chat.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the [Google Chat](https://chat.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_googlechat_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-hangouts.md b/docs/configuring-playbook-bridge-mautrix-hangouts.md index 62770fe0b..198d4c923 100644 --- a/docs/configuring-playbook-bridge-mautrix-hangouts.md +++ b/docs/configuring-playbook-bridge-mautrix-hangouts.md @@ -8,7 +8,7 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/hangouts/in ## Adjusting the playbook configuration -To enable the [Google Hangouts](https://hangouts.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the [Google Hangouts](https://hangouts.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_hangouts_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-instagram.md b/docs/configuring-playbook-bridge-mautrix-instagram.md index 14d25f52f..ffafa25db 100644 --- a/docs/configuring-playbook-bridge-mautrix-instagram.md +++ b/docs/configuring-playbook-bridge-mautrix-instagram.md @@ -8,7 +8,7 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/instagram/i ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_instagram_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-meta-instagram.md b/docs/configuring-playbook-bridge-mautrix-meta-instagram.md index 0a644d049..f7809090d 100644 --- a/docs/configuring-playbook-bridge-mautrix-meta-instagram.md +++ b/docs/configuring-playbook-bridge-mautrix-meta-instagram.md @@ -23,7 +23,7 @@ Then, consider disabling the old bridge in your configuration, so it won't recre ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_meta_instagram_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md index ded925ce5..81aebfade 100644 --- a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md +++ b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md @@ -19,7 +19,7 @@ Then, consider disabling the old bridge in your configuration, so it won't recre ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_meta_messenger_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-signal.md b/docs/configuring-playbook-bridge-mautrix-signal.md index 16227a186..ec9d18024 100644 --- a/docs/configuring-playbook-bridge-mautrix-signal.md +++ b/docs/configuring-playbook-bridge-mautrix-signal.md @@ -10,7 +10,7 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/signal/inde ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_signal_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-slack.md b/docs/configuring-playbook-bridge-mautrix-slack.md index e2f00d467..43eaf274b 100644 --- a/docs/configuring-playbook-bridge-mautrix-slack.md +++ b/docs/configuring-playbook-bridge-mautrix-slack.md @@ -20,7 +20,7 @@ Note that neither of these methods are officially supported by Slack. [matrix-ap ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_slack_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-telegram.md b/docs/configuring-playbook-bridge-mautrix-telegram.md index a556dcffa..3fc98eda6 100644 --- a/docs/configuring-playbook-bridge-mautrix-telegram.md +++ b/docs/configuring-playbook-bridge-mautrix-telegram.md @@ -6,7 +6,7 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/in ## Adjusting the playbook configuration -You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_telegram_enabled: true @@ -47,7 +47,7 @@ When using this method, **each user** that wishes to enable Double Puppeting nee You then need to start a chat with `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN @@ -62,7 +62,7 @@ You might also want to give permissions to administrate the bot: matrix_mautrix_telegram_configuration_extension_yaml: | bridge: permissions: - '@user:DOMAIN': admin + '@user:example.com': admin ``` More details about permissions in this example: diff --git a/docs/configuring-playbook-bridge-mautrix-twitter.md b/docs/configuring-playbook-bridge-mautrix-twitter.md index 60c1a745f..fe08c77bf 100644 --- a/docs/configuring-playbook-bridge-mautrix-twitter.md +++ b/docs/configuring-playbook-bridge-mautrix-twitter.md @@ -8,7 +8,7 @@ See the project's [documentation](https://github.com/mautrix/twitter) to learn w ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_twitter_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-whatsapp.md b/docs/configuring-playbook-bridge-mautrix-whatsapp.md index ae1d2ea3a..d65075c83 100644 --- a/docs/configuring-playbook-bridge-mautrix-whatsapp.md +++ b/docs/configuring-playbook-bridge-mautrix-whatsapp.md @@ -6,7 +6,7 @@ See the project's [documentation](https://docs.mau.fi/bridges/go/whatsapp/index. ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_whatsapp_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-wsproxy.md b/docs/configuring-playbook-bridge-mautrix-wsproxy.md index 93ed9a5ad..2bff1ecda 100644 --- a/docs/configuring-playbook-bridge-mautrix-wsproxy.md +++ b/docs/configuring-playbook-bridge-mautrix-wsproxy.md @@ -7,12 +7,12 @@ See the project's [documentation](https://github.com/mautrix/wsproxy#readme) to ## DNS -You need to create a `wsproxy.DOMAIN` DNS record pointing to your Matrix server (a `CNAME` pointing to `matrix.DOMAIN`) to use wsproxy. +You need to create a `wsproxy.example.com` DNS record pointing to your Matrix server (a `CNAME` pointing to `matrix.example.com`) to use wsproxy. The hostname is configurable via a `matrix_mautrix_wsproxy_hostname` variable. ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_wsproxy_enabled: true diff --git a/docs/configuring-playbook-bridge-mx-puppet-discord.md b/docs/configuring-playbook-bridge-mx-puppet-discord.md index da987bf2e..56f05f307 100644 --- a/docs/configuring-playbook-bridge-mx-puppet-discord.md +++ b/docs/configuring-playbook-bridge-mx-puppet-discord.md @@ -13,7 +13,7 @@ See the project page to learn what it does and why it might be useful to you. ## Adjusting the playbook configuration -To enable the [Discord](https://discordapp.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the [Discord](https://discordapp.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mx_puppet_discord_enabled: true diff --git a/docs/configuring-playbook-bridge-mx-puppet-groupme.md b/docs/configuring-playbook-bridge-mx-puppet-groupme.md index ed38600e4..c10e386fc 100644 --- a/docs/configuring-playbook-bridge-mx-puppet-groupme.md +++ b/docs/configuring-playbook-bridge-mx-puppet-groupme.md @@ -7,7 +7,7 @@ See the project page to learn what it does and why it might be useful to you. ## Adjusting the playbook configuration -To enable the [GroupMe](https://groupme.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the [GroupMe](https://groupme.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mx_puppet_groupme_enabled: true diff --git a/docs/configuring-playbook-bridge-mx-puppet-instagram.md b/docs/configuring-playbook-bridge-mx-puppet-instagram.md index 0a61d561f..b2546cb0a 100644 --- a/docs/configuring-playbook-bridge-mx-puppet-instagram.md +++ b/docs/configuring-playbook-bridge-mx-puppet-instagram.md @@ -7,7 +7,7 @@ This allows you to bridge Instagram DirectMessages into Matrix. ## Adjusting the playbook configuration -To enable the [Instagram](https://www.instagram.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the [Instagram](https://www.instagram.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mx_puppet_instagram_enabled: true diff --git a/docs/configuring-playbook-bridge-mx-puppet-slack.md b/docs/configuring-playbook-bridge-mx-puppet-slack.md index a2e2fa3c3..d5f784cc5 100644 --- a/docs/configuring-playbook-bridge-mx-puppet-slack.md +++ b/docs/configuring-playbook-bridge-mx-puppet-slack.md @@ -10,11 +10,11 @@ See the project page to learn what it does and why it might be useful to you. ## Prerequisite -Follow the [OAuth credentials](https://github.com/Sorunome/mx-puppet-slack#option-2-oauth) instructions to create a new Slack app, setting the redirect URL to `https://matrix.DOMAIN/slack/oauth`. +Follow the [OAuth credentials](https://github.com/Sorunome/mx-puppet-slack#option-2-oauth) instructions to create a new Slack app, setting the redirect URL to `https://matrix.example.com/slack/oauth`. ## Adjusting the playbook configuration -To enable the [Slack](https://slack.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the [Slack](https://slack.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mx_puppet_slack_enabled: true diff --git a/docs/configuring-playbook-bridge-mx-puppet-steam.md b/docs/configuring-playbook-bridge-mx-puppet-steam.md index 08b254259..60475929c 100644 --- a/docs/configuring-playbook-bridge-mx-puppet-steam.md +++ b/docs/configuring-playbook-bridge-mx-puppet-steam.md @@ -7,7 +7,7 @@ See the project page to learn what it does and why it might be useful to you. ## Adjusting the playbook configuration -To enable the [Steam](https://steampowered.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the [Steam](https://steampowered.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mx_puppet_steam_enabled: true diff --git a/docs/configuring-playbook-bridge-mx-puppet-twitter.md b/docs/configuring-playbook-bridge-mx-puppet-twitter.md index 0d567c56e..783999ff8 100644 --- a/docs/configuring-playbook-bridge-mx-puppet-twitter.md +++ b/docs/configuring-playbook-bridge-mx-puppet-twitter.md @@ -13,7 +13,7 @@ Make an app on [developer.twitter.com](https://developer.twitter.com/en/apps). ## Adjusting the playbook configuration -To enable the [Twitter](https://twitter.com) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the [Twitter](https://twitter.com) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mx_puppet_twitter_enabled: true diff --git a/docs/configuring-playbook-bridge-wechat.md b/docs/configuring-playbook-bridge-wechat.md index c00b9a7fc..e5a1546c7 100644 --- a/docs/configuring-playbook-bridge-wechat.md +++ b/docs/configuring-playbook-bridge-wechat.md @@ -6,7 +6,7 @@ See the project page to learn what it does and why it might be useful to you. ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_wechat_enabled: true diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index 98ec896e8..f5e124c08 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -33,7 +33,7 @@ matrix_cactus_comments_enabled: true # matrix_synapse_allow_guest_access: true # matrix_dendrite_allow_guest_access: true -# This enables client assets static files serving on `https://matrix.DOMAIN/cactus-comments`. +# This enables client assets static files serving on `https://matrix.example.com/cactus-comments`. # When the backend (appservice) is enabled, this is also enabled automatically, # but we explicitly enable it here. matrix_cactus_comments_client_enabled: true diff --git a/docs/configuring-playbook-client-cinny.md b/docs/configuring-playbook-client-cinny.md index bcecff2d7..701d13fb6 100644 --- a/docs/configuring-playbook-client-cinny.md +++ b/docs/configuring-playbook-client-cinny.md @@ -6,11 +6,11 @@ Cinny can be installed alongside or instead of Element. ## DNS -You need to add a `cinny.DOMAIN` DNS record so that Cinny can be accessed. -By default Cinny will use https://cinny.DOMAIN so you will need to create an CNAME record +You need to add a `cinny.example.com` DNS record so that Cinny can be accessed. +By default Cinny will use https://cinny.example.com so you will need to create an CNAME record for `cinny`. See [Configuring DNS](configuring-dns.md). -If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (changing it to use your preferred domain): +If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain): ```yaml matrix_server_fqn_cinny: "app.{{ matrix_domain }}" @@ -18,7 +18,7 @@ matrix_server_fqn_cinny: "app.{{ matrix_domain }}" ## Adjusting the playbook configuration -To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_client_cinny_enabled: true diff --git a/docs/configuring-playbook-client-hydrogen.md b/docs/configuring-playbook-client-hydrogen.md index 28ddb900a..2099299d5 100644 --- a/docs/configuring-playbook-client-hydrogen.md +++ b/docs/configuring-playbook-client-hydrogen.md @@ -6,11 +6,11 @@ Hydrogen can be installed alongside or instead of Element. ## DNS -You need to add a `hydrogen.DOMAIN` DNS record so that Hydrogen can be accessed. -By default Hydrogen will use https://hydrogen.DOMAIN so you will need to create an CNAME record +You need to add a `hydrogen.example.com` DNS record so that Hydrogen can be accessed. +By default Hydrogen will use https://hydrogen.example.com so you will need to create an CNAME record for `hydrogen`. See [Configuring DNS](configuring-dns.md). -If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (changing it to use your preferred domain): +If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain): ```yaml matrix_server_fqn_hydrogen: "helium.{{ matrix_domain }}" @@ -18,7 +18,7 @@ matrix_server_fqn_hydrogen: "helium.{{ matrix_domain }}" ## Adjusting the playbook configuration -To enable Hydrogen, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable Hydrogen, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_client_hydrogen_enabled: true diff --git a/docs/configuring-playbook-client-schildichat.md b/docs/configuring-playbook-client-schildichat.md index 81fe411d1..5272723cf 100644 --- a/docs/configuring-playbook-client-schildichat.md +++ b/docs/configuring-playbook-client-schildichat.md @@ -8,11 +8,11 @@ SchildiChat can be installed alongside or instead of Element. ## DNS -You need to add a `schildichat.DOMAIN` DNS record so that SchildiChat can be accessed. -By default SchildiChat will use https://schildichat.DOMAIN so you will need to create an CNAME record +You need to add a `schildichat.example.com` DNS record so that SchildiChat can be accessed. +By default SchildiChat will use https://schildichat.example.com so you will need to create an CNAME record for `schildichat`. See [Configuring DNS](configuring-dns.md). -If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (changing it to use your preferred domain): +If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain): ```yaml matrix_server_fqn_schildichat: "sc.{{ matrix_domain }}" @@ -20,7 +20,7 @@ matrix_server_fqn_schildichat: "sc.{{ matrix_domain }}" ## Adjusting the playbook configuration -To enable SchildiChat, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable SchildiChat, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_client_schildichat_enabled: true diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md index 045be3616..9deb41f27 100644 --- a/docs/configuring-playbook-dimension.md +++ b/docs/configuring-playbook-dimension.md @@ -10,7 +10,7 @@ If you're just installing Matrix services for the first time, please continue wi ## Decide on a domain and path -By default, Dimension is configured to use its own dedicated domain (`dimension.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records). +By default, Dimension is configured to use its own dedicated domain (`dimension.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records). You can override the domain and path like this: diff --git a/docs/configuring-playbook-dynamic-dns.md b/docs/configuring-playbook-dynamic-dns.md index bc58c2736..6d468a3c5 100644 --- a/docs/configuring-playbook-dynamic-dns.md +++ b/docs/configuring-playbook-dynamic-dns.md @@ -6,7 +6,7 @@ Most cloud providers / ISPs will charge you extra for a static IP address. If yo not hosting a highly reliable homeserver you can workaround this via dynamic DNS. To set this up, you'll need to get the username/password from your DNS provider. For google domains, this process is described [here](https://support.google.com/domains/answer/6147083). -After you've gotten the proper credentials you can add the following config to your `inventory/host_vars/matrix.DOMAIN/vars.yml`: +After you've gotten the proper credentials you can add the following config to your `inventory/host_vars/matrix.example.com/vars.yml`: ```yaml matrix_dynamic_dns_enabled: true diff --git a/docs/configuring-playbook-email.md b/docs/configuring-playbook-email.md index a7c500250..ab850e933 100644 --- a/docs/configuring-playbook-email.md +++ b/docs/configuring-playbook-email.md @@ -17,7 +17,7 @@ No matter whether you send email directly (the default) or you relay email throu ## Relaying email through another SMTP server -If you'd like to relay email through another SMTP server, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +If you'd like to relay email through another SMTP server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml exim_relay_sender_address: "another.sender@example.com" diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index c410de559..ec9b78b6a 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/docs/configuring-playbook-email2matrix.md @@ -11,7 +11,7 @@ See the project's [documentation](https://github.com/devture/email2matrix/blob/m ### DNS configuration -It's not strictly necessary, but you may increase the chances that incoming emails reach your server by adding an `MX` record for `matrix.DOMAIN`, as described in the [Configuring DNS](configuring-dns.md) documentation page. +It's not strictly necessary, but you may increase the chances that incoming emails reach your server by adding an `MX` record for `matrix.example.com`, as described in the [Configuring DNS](configuring-dns.md) documentation page. ### Port availability @@ -43,7 +43,7 @@ In order for the sender user created above to be able to send messages to the ro ## Adjusting the playbook configuration -After doing the preparation steps above, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +After doing the preparation steps above, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_email2matrix_enabled: true @@ -85,4 +85,4 @@ Refer to the official documentation [here](https://github.com/devture/email2matr To enable Email2Matrix, run the [installation](installing.md) command (`--tags=setup-email2matrix,start`). -After installation, you may wish to send a test email to the email address assigned to `mailbox1` (default: `mailbox1@matrix.DOMAIN`) to make sure that Email2Matrix works as expected. +After installation, you may wish to send a test email to the email address assigned to `mailbox1` (default: `mailbox1@matrix.example.com`) to make sure that Email2Matrix works as expected. diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md index 08ec29243..a33976623 100644 --- a/docs/configuring-playbook-etherpad.md +++ b/docs/configuring-playbook-etherpad.md @@ -7,12 +7,12 @@ When enabled together with the Jitsi audio/video conferencing system (see [our d ## Decide on a domain and path -By default, Etherpad is configured to use its own dedicated domain (`etherpad.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records). +By default, Etherpad is configured to use its own dedicated domain (`etherpad.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records). You can override the domain and path like this: ```yaml -# Switch to the domain used for Matrix services (`matrix.DOMAIN`), +# Switch to the domain used for Matrix services (`matrix.example.com`), # so we won't need to add additional DNS records for Etherpad. etherpad_hostname: "{{ matrix_server_fqn_matrix }}" @@ -30,7 +30,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## Adjusting the playbook configuration -[Etherpad](https://etherpad.org) installation is disabled by default. To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +[Etherpad](https://etherpad.org) installation is disabled by default. To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml etherpad_enabled: true @@ -48,7 +48,7 @@ After configuring the playbook, run the [installation](installing.md) command: ` The Etherpad UI should be available at `https://etherpad.`, while the admin UI (if enabled) should then be available at `https://etherpad./admin`. -If you've [decided on another hostname or path-prefix](#decide-on-a-domain-and-path) (e.g. `https://matrix.DOMAIN/etherpad`), adjust these URLs accordingly before usage. +If you've [decided on another hostname or path-prefix](#decide-on-a-domain-and-path) (e.g. `https://matrix.example.com/etherpad`), adjust these URLs accordingly before usage. ### Managing / Deleting old pads @@ -62,7 +62,7 @@ Then from the plugin manager page (`https://etherpad./admin/plugins This is how it works in Element, it might work quite similar with other clients: -To integrate a standalone Etherpad in a room, create your pad by visiting `https://etherpad.DOMAIN`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` section. +To integrate a standalone Etherpad in a room, create your pad by visiting `https://etherpad.example.com`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` section. ### Set Dimension default to the self-hosted Etherpad (optional) diff --git a/docs/configuring-playbook-external-postgres.md b/docs/configuring-playbook-external-postgres.md index b8c8f8eb9..e922c8299 100644 --- a/docs/configuring-playbook-external-postgres.md +++ b/docs/configuring-playbook-external-postgres.md @@ -4,7 +4,7 @@ By default, this playbook would set up a PostgreSQL database server on your mach **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.DOMAIN/vars.yml` file (adapt to your needs): +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): ```yaml postgres_enabled: false diff --git a/docs/configuring-playbook-federation.md b/docs/configuring-playbook-federation.md index 548c55bef..6ebe32bbd 100644 --- a/docs/configuring-playbook-federation.md +++ b/docs/configuring-playbook-federation.md @@ -6,7 +6,7 @@ That is, people on your server can communicate with people on any other Matrix s ## Federating only with select servers -To make your server only federate with servers of your choosing, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +To make your server only federate with servers of your choosing, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_synapse_federation_domain_whitelist: diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index ce2280914..8d75cd29b 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -9,7 +9,7 @@ The setup done by the playbook is very similar to [docker-jitsi-meet](https://gi ## Prerequisites -Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record (unless you've changed `jitsi_hostname`, as described below). See [Configuring DNS](configuring-dns.md) for details about DNS changes. +Before installing Jitsi, make sure you've created the `jitsi.example.com` DNS record (unless you've changed `jitsi_hostname`, as described below). See [Configuring DNS](configuring-dns.md) for details about DNS changes. You may also need to open the following ports to your server: @@ -19,7 +19,7 @@ You may also need to open the following ports to your server: ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml jitsi_enabled: true @@ -42,14 +42,14 @@ Currently, there are three supported authentication modes: 'internal' (default), **Note**: Authentication is not tested via the playbook's self-checks. We therefore recommend that you manually verify if authentication is required by jitsi. -For this, try to manually create a conference on jitsi.DOMAIN in your browser. +For this, try to manually create a conference on jitsi.example.com in your browser. ### Authenticate using Jitsi accounts (Auth-Type 'internal') The default authentication mechanism is 'internal' auth, which requires jitsi-accounts to be setup and is the recommended setup, as it also works in federated rooms. With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join. If a registered host is not yet present, guests are put on hold in individual waiting rooms. -Add these lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration: +Add these lines to your `inventory/host_vars/matrix.example.com/vars.yml` configuration: ```yaml jitsi_enable_auth: true @@ -89,8 +89,8 @@ An example LDAP configuration could be: ```yaml jitsi_enable_auth: true jitsi_auth_type: ldap -jitsi_ldap_url: "ldap://ldap.DOMAIN" -jitsi_ldap_base: "OU=People,DC=DOMAIN" +jitsi_ldap_url: "ldap://ldap.example.com" +jitsi_ldap_base: "OU=People,DC=example.com" #jitsi_ldap_binddn: "" #jitsi_ldap_bindpw: "" jitsi_ldap_filter: "uid=%u" @@ -115,7 +115,7 @@ The reason is the Jitsi VideoBridge git to LAN client the IP address of the dock Here is how to do it in the playbook. -Add these two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration: +Add these two lines to your `inventory/host_vars/matrix.example.com/vars.yml` configuration: ```yaml jitsi_jvb_container_extra_arguments: @@ -124,7 +124,7 @@ jitsi_jvb_container_extra_arguments: ## (Optional) Fine tune Jitsi -Sample **additional** `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration to save up resources (explained below): +Sample **additional** `inventory/host_vars/matrix.example.com/vars.yml` configuration to save up resources (explained below): ```yaml jitsi_web_custom_config_extension: | @@ -283,11 +283,11 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start You can use the self-hosted Jitsi server in multiple ways: -- **by adding a widget to a room via Element** (the one configured by the playbook at `https://element.DOMAIN`). Just start a voice or a video call in a room containing more than 2 members and that would create a Jitsi widget which utilizes your self-hosted Jitsi server. +- **by adding a widget to a room via Element** (the one configured by the playbook at `https://element.example.com`). Just start a voice or a video call in a room containing more than 2 members and that would create a Jitsi widget which utilizes your self-hosted Jitsi server. - **by adding a widget to a room via the Dimension Integration Manager**. You'll have to point the widget to your own Jitsi server manually. See our [Dimension](./configuring-playbook-dimension.md) documentation page for more details. Naturally, Dimension would need to be installed first (the playbook doesn't install it by default). -- **directly (without any Matrix integration)**. Just go to `https://jitsi.DOMAIN` +- **directly (without any Matrix integration)**. Just go to `https://jitsi.example.com` **Note**: Element apps on mobile devices currently [don't support joining meetings on a self-hosted Jitsi server](https://github.com/element-hq/riot-web/blob/601816862f7d84ac47547891bd53effa73d32957/docs/jitsi.md#mobile-app-support). diff --git a/docs/configuring-playbook-ldap-auth.md b/docs/configuring-playbook-ldap-auth.md index cc07f396f..451d386ba 100644 --- a/docs/configuring-playbook-ldap-auth.md +++ b/docs/configuring-playbook-ldap-auth.md @@ -4,7 +4,7 @@ The playbook can install and configure the [matrix-synapse-ldap3](https://github See that project's documentation to learn what it does and why it might be useful to you. -If you decide that you'd like to let this playbook install it for you, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +If you decide that you'd like to let this playbook install it for you, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_synapse_ext_password_provider_ldap_enabled: true diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index c7d163dca..fd65679e1 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -12,7 +12,7 @@ This server is private by default, potentially at the expense of user discoverab ## Adjusting the playbook configuration -To enable ma1sd, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable ma1sd, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_ma1sd_enabled: true @@ -53,7 +53,7 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu - `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.DOMAIN:8448`) is whitelisted in your firewall (even if you don't actually use/need federation). +**Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) or the `openid` APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the `openid` APIs (only!) on the federation port. Make sure the federation port (usually `https://matrix.example.com:8448`) is whitelisted in your firewall (even if you don't actually use/need federation). ## Authentication @@ -129,7 +129,7 @@ If email address validation emails sent by ma1sd are not reaching you, you shoul If you'd like additional logging information, temporarily enable verbose logging for ma1sd. -Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`): +Example configuration (`inventory/host_vars/matrix.example.com/vars.yml`): ```yaml matrix_ma1sd_verbose_logging: true diff --git a/docs/configuring-playbook-matrix-corporal.md b/docs/configuring-playbook-matrix-corporal.md index ff762310e..220c6d8ef 100644 --- a/docs/configuring-playbook-matrix-corporal.md +++ b/docs/configuring-playbook-matrix-corporal.md @@ -18,7 +18,7 @@ If you decide that you'd like to let this playbook install it for you, you'd nee ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml # The Shared Secret Auth password provider module is required for Corporal to work. diff --git a/docs/configuring-playbook-matrix-ldap-registration-proxy.md b/docs/configuring-playbook-matrix-ldap-registration-proxy.md index 6ddcc0417..3e1b047be 100644 --- a/docs/configuring-playbook-matrix-ldap-registration-proxy.md +++ b/docs/configuring-playbook-matrix-ldap-registration-proxy.md @@ -9,7 +9,7 @@ implementation of a basic password registration. ## Quickstart -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_ldap_registration_proxy_enabled: true diff --git a/docs/configuring-playbook-matrix-media-repo.md b/docs/configuring-playbook-matrix-media-repo.md index a91f3e444..a935bcbea 100644 --- a/docs/configuring-playbook-matrix-media-repo.md +++ b/docs/configuring-playbook-matrix-media-repo.md @@ -14,7 +14,7 @@ For a simpler alternative (which allows you to offload your media repository sto ## Quickstart -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file and [re-run the installation process](./installing.md) for the playbook: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file and [re-run the installation process](./installing.md) for the playbook: ```yaml matrix_media_repo_enabled: true @@ -105,7 +105,7 @@ If you wish to manually generate the signing key and merge it with your homeserv ### Key backup and revoking -Since your homeserver signing key file is modified by the playbook, a backup will be created in `HOMESERVER_DIR/config/DOMAIN.signing.key.backup`. If you need to remove/revoke old keys, you can restore from this backup or remove the MMR key ID from your `DOMAIN.signing.key` file. +Since your homeserver signing key file is modified by the playbook, a backup will be created in `HOMESERVER_DIR/config/example.com.signing.key.backup`. If you need to remove/revoke old keys, you can restore from this backup or remove the MMR key ID from your `example.com.signing.key` file. Additionally, its recommended after revoking a signing key to update your homeserver config file (`old_signing_keys` field for Synapse and `old_private_keys` for Dendrite). See your homeserver config file for further documentation on how to populate the field. diff --git a/docs/configuring-playbook-matrix-registration.md b/docs/configuring-playbook-matrix-registration.md index 890c23273..cfd0b61c8 100644 --- a/docs/configuring-playbook-matrix-registration.md +++ b/docs/configuring-playbook-matrix-registration.md @@ -14,12 +14,12 @@ Use matrix-registration to **create unique registration links**, which people ca - **an API for creating registration tokens** (unique registration links). This API can be used via `curl` or via the playbook (see [Usage](#usage) below) -- **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.DOMAIN/matrix-registration` +- **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.example.com/matrix-registration` ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_registration_enabled: true @@ -39,7 +39,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start ## Usage -**matrix-registration** gets exposed at `https://matrix.DOMAIN/matrix-registration` +**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`. diff --git a/docs/configuring-playbook-mautrix-bridges.md b/docs/configuring-playbook-mautrix-bridges.md index ddb935809..04fda5b01 100644 --- a/docs/configuring-playbook-mautrix-bridges.md +++ b/docs/configuring-playbook-mautrix-bridges.md @@ -7,7 +7,7 @@ You can see each bridge's features at in the `ROADMAP.md` file in its correspond ## Adjusting the playbook configuration -To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml # Replace SERVICENAME with one of: twitter, facebook, instagram, .. @@ -16,7 +16,7 @@ matrix_mautrix_SERVICENAME_enabled: true There are some additional things you may wish to configure about the bridge before you continue. Each bridge may have additional requirements besides `_enabled: true`. For example, the mautrix-telegram bridge (our documentation page about it is [here](configuring-playbook-bridge-mautrix-telegram.md)) requires the `matrix_mautrix_telegram_api_id` and `matrix_mautrix_telegram_api_hash` variables to be defined. Refer to each bridge's individual documentation page for details about enabling bridges. -To **configure a user as an administrator for all bridges**, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To **configure a user as an administrator for all bridges**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}" @@ -33,7 +33,7 @@ matrix_mautrix_SERVICENAME_configuration_extension_yaml: | ## encryption -Encryption support is off by default. If you would like to enable encryption, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Encryption support is off by default. If you would like to enable encryption, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: **for all bridges with encryption support**: @@ -51,7 +51,7 @@ matrix_mautrix_SERVICENAME_bridge_encryption_default: true ## relay mode -Relay mode is off by default. If you would like to enable relay mode, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Relay mode is off by default. If you would like to enable relay mode, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: **for all bridges with relay mode support**: diff --git a/docs/configuring-playbook-ntfy.md b/docs/configuring-playbook-ntfy.md index 7f5252cc1..17977cf98 100644 --- a/docs/configuring-playbook-ntfy.md +++ b/docs/configuring-playbook-ntfy.md @@ -11,7 +11,7 @@ This role is intended to support UnifiedPush notifications for use with the Matr ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml # Enabling it is the only required setting @@ -56,7 +56,7 @@ You need to install the `ntfy` app on each device on which you want to receive p ### Setting up the `ntfy` Android app 1. Install the [ntfy Android app](https://ntfy.sh/docs/subscribe/phone/) from F-droid or Google Play. -2. In its Settings -> `General: Default server`, enter your ntfy server URL, such as `https://ntfy.DOMAIN`. +2. In its Settings -> `General: Default server`, enter your ntfy server URL, such as `https://ntfy.example.com`. 3. In its Settings -> `Advanced: Connection protocol`, choose `WebSockets`. That is all you need to do in the ntfy app. It has many other features, but for our purposes you can ignore them. In particular you do not need to follow any instructions about subscribing to a notification topic as UnifiedPush will do that automatically. diff --git a/docs/configuring-playbook-own-webserver.md b/docs/configuring-playbook-own-webserver.md index f7d1ab9d8..092128287 100644 --- a/docs/configuring-playbook-own-webserver.md +++ b/docs/configuring-playbook-own-webserver.md @@ -14,7 +14,7 @@ There are 2 ways to use Traefik with this playbook, as described below. ### Traefik managed by the playbook -To have the playbook install and use Traefik, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To have the playbook install and use Traefik, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_playbook_reverse_proxy_type: playbook-managed-traefik @@ -192,7 +192,7 @@ Your reverse-proxy configuration needs to send traffic to these ports. The [`exa It's important that these webservers proxy-pass requests to the correct place and also set the `Host` HTTP header appropriately. If you don't pass the `Host` header correctly, you would get a 404 not found error from Traefik. -To put it another way, `curl http://127.0.0.1:81` would give you a 404, but `curl -H 'Host: matrix.DOMAIN' http://127.0.0.1:81` should work. +To put it another way, `curl http://127.0.0.1:81` would give you a 404, but `curl -H 'Host: matrix.example.com' http://127.0.0.1:81` should work. ### Using no reverse-proxy on the Matrix side at all diff --git a/docs/configuring-playbook-pantalaimon.md b/docs/configuring-playbook-pantalaimon.md index 2663e2e27..4c2ad39ec 100644 --- a/docs/configuring-playbook-pantalaimon.md +++ b/docs/configuring-playbook-pantalaimon.md @@ -8,7 +8,7 @@ This role exposes Pantalaimon's API only within the container network, so bots a ## 1. Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_pantalaimon_enabled: true diff --git a/docs/configuring-playbook-postgres-backup.md b/docs/configuring-playbook-postgres-backup.md index c40e4d0c5..dfb31ba13 100644 --- a/docs/configuring-playbook-postgres-backup.md +++ b/docs/configuring-playbook-postgres-backup.md @@ -7,7 +7,7 @@ For a more complete backup solution (one that includes not only Postgres, but al ## Adjusting the playbook configuration -To enable Postgres backup, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable Postgres backup, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml postgres_backup_enabled: true diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md index 6f096da43..c984c86f7 100644 --- a/docs/configuring-playbook-prometheus-grafana.md +++ b/docs/configuring-playbook-prometheus-grafana.md @@ -61,7 +61,7 @@ Most of our docker containers run with limited system access, but the `prometheu When you'd like **to collect metrics from an external Prometheus server**, you need to expose service metrics outside of the container network. -The playbook provides a single endpoint (`https://matrix.DOMAIN/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/hookshot`, etc). To expose all services on this `/metrics/*` feature, use `matrix_metrics_exposure_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` below. +The playbook provides a single endpoint (`https://matrix.example.com/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/hookshot`, etc). To expose all services on this `/metrics/*` feature, use `matrix_metrics_exposure_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` below. When using `matrix_metrics_exposure_enabled`, you don't need to expose metrics for individual services one by one. @@ -69,26 +69,26 @@ The following variables may be of interest: Name | Description -----|---------- -`matrix_metrics_exposure_enabled`|Set this to `true` to **enable metrics exposure for all services** on `https://matrix.DOMAIN/metrics/*`. If you think this is too much, refer to the helpful (but nonexhaustive) list of individual `matrix_SERVICE_metrics_proxying_enabled` (or similar) variables below for exposing metrics on a per-service basis. -`matrix_metrics_exposure_http_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.DOMAIN/metrics/*` endpoints with [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) (see the other variables below for supplying the actual credentials). When enabled, all endpoints beneath `/metrics` will be protected with the same credentials +`matrix_metrics_exposure_enabled`|Set this to `true` to **enable metrics exposure for all services** on `https://matrix.example.com/metrics/*`. If you think this is too much, refer to the helpful (but nonexhaustive) list of individual `matrix_SERVICE_metrics_proxying_enabled` (or similar) variables below for exposing metrics on a per-service basis. +`matrix_metrics_exposure_http_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.example.com/metrics/*` endpoints with [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) (see the other variables below for supplying the actual credentials). When enabled, all endpoints beneath `/metrics` will be protected with the same credentials `matrix_metrics_exposure_http_basic_auth_users`|Set this to the Basic Authentication credentials (raw `htpasswd` file content) used to protect `/metrics/*`. This htpasswd-file needs to be generated with the `htpasswd` tool and can include multiple username/password pairs. `matrix_synapse_metrics_enabled`|Set this to `true` to make Synapse expose metrics (locally, on the container network) -`matrix_synapse_metrics_proxying_enabled`|Set this to `true` to expose Synapse's metrics on `https://matrix.DOMAIN/metrics/synapse/main-process` and `https://matrix.DOMAIN/metrics/synapse/worker/TYPE-ID`. Read [below](#collecting-synapse-worker-metrics-to-an-external-prometheus-server) if you're running a Synapse worker setup (`matrix_synapse_workers_enabled: true`). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. +`matrix_synapse_metrics_proxying_enabled`|Set this to `true` to expose Synapse's metrics on `https://matrix.example.com/metrics/synapse/main-process` and `https://matrix.example.com/metrics/synapse/worker/TYPE-ID`. Read [below](#collecting-synapse-worker-metrics-to-an-external-prometheus-server) if you're running a Synapse worker setup (`matrix_synapse_workers_enabled: true`). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. `prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network) -`prometheus_node_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.DOMAIN/metrics/node-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. +`prometheus_node_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.example.com/metrics/node-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. `prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](configuring-playbook-prometheus-postgres.md) (locally, on the container network) -`prometheus_postgres_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.DOMAIN/metrics/postgres-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. +`prometheus_postgres_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.example.com/metrics/postgres-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. `matrix_prometheus_nginxlog_exporter_enabled`|Set this to `true` to enable the [NGINX Log exporter](configuring-playbook-prometheus-nginxlog.md) (locally, on the container network) `matrix_sliding_sync_metrics_enabled`|Set this to `true` to make [Sliding Sync](configuring-playbook-sliding-sync-proxy.md) expose metrics (locally, on the container network) -`matrix_sliding_sync_metrics_proxying_enabled`|Set this to `true` to expose the [Sliding Sync](configuring-playbook-sliding-sync-proxy.md) metrics on `https://matrix.DOMAIN/metrics/sliding-sync`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. +`matrix_sliding_sync_metrics_proxying_enabled`|Set this to `true` to expose the [Sliding Sync](configuring-playbook-sliding-sync-proxy.md) metrics on `https://matrix.example.com/metrics/sliding-sync`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. `matrix_bridge_hookshot_metrics_enabled`|Set this to `true` to make [Hookshot](configuring-playbook-bridge-hookshot.md) expose metrics (locally, on the container network) -`matrix_bridge_hookshot_metrics_proxying_enabled`|Set this to `true` to expose the [Hookshot](configuring-playbook-bridge-hookshot.md) metrics on `https://matrix.DOMAIN/metrics/hookshot`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. +`matrix_bridge_hookshot_metrics_proxying_enabled`|Set this to `true` to expose the [Hookshot](configuring-playbook-bridge-hookshot.md) metrics on `https://matrix.example.com/metrics/hookshot`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above. `matrix_SERVICE_metrics_proxying_enabled`|Various other services/roles may provide similar `_metrics_enabled` and `_metrics_proxying_enabled` variables for exposing their metrics. Refer to each role for details. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above or `matrix_SERVICE_container_labels_metrics_middleware_basic_auth_enabled`/`matrix_SERVICE_container_labels_metrics_middleware_basic_auth_users` variables provided by each role. `matrix_media_repo_metrics_enabled`|Set this to `true` to make media-repo expose metrics (locally, on the container network) ### Collecting Synapse worker metrics to an external Prometheus server -If you are using workers (`matrix_synapse_workers_enabled: true`) and have enabled `matrix_synapse_metrics_proxying_enabled` as described above, the playbook will also automatically expose all Synapse worker threads' metrics to `https://matrix.DOMAIN/metrics/synapse/worker/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`. +If you are using workers (`matrix_synapse_workers_enabled: true`) and have enabled `matrix_synapse_metrics_proxying_enabled` as described above, the playbook will also automatically expose all Synapse worker threads' metrics to `https://matrix.example.com/metrics/synapse/worker/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`. The playbook also generates an exemplary config file (`/matrix/synapse/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs. Make sure to edit the specified `password_file` path and contents and path to your `synapse-v2.rules`. It will look a bit like this: @@ -101,7 +101,7 @@ scrape_configs: username: prometheus password_file: /etc/prometheus/password.pwd static_configs: - - targets: ['matrix.DOMAIN:443'] + - targets: ['matrix.example.com:443'] labels: job: "master" index: 1 @@ -112,7 +112,7 @@ scrape_configs: username: prometheus password_file: /etc/prometheus/password.pwd static_configs: - - targets: ['matrix.DOMAIN:443'] + - targets: ['matrix.example.com:443'] labels: job: "generic_worker" index: 18111 diff --git a/docs/configuring-playbook-prometheus-nginxlog.md b/docs/configuring-playbook-prometheus-nginxlog.md index 3923fb685..d7b4ca3bb 100644 --- a/docs/configuring-playbook-prometheus-nginxlog.md +++ b/docs/configuring-playbook-prometheus-nginxlog.md @@ -14,7 +14,7 @@ If your setup includes [Grafana](./configuring-playbook-prometheus-grafana.md), ## Configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_prometheus_nginxlog_exporter_enabled: true @@ -49,6 +49,6 @@ When using an external Prometheus server, you'll need to expose metrics publicly You can either use `matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled: true` to expose just this one service, or `matrix_metrics_exposure_enabled: true` to expose all services. -Whichever way you go with, this service will expose its metrics endpoint **without password-protection** at `https://matrix.DOMAIN/metrics/nginxlog` by default. +Whichever way you go with, this service will expose its metrics endpoint **without password-protection** at `https://matrix.example.com/metrics/nginxlog` by default. For password-protection, use (`matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`) or (`matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_enabled` and `matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_users`). diff --git a/docs/configuring-playbook-prometheus-postgres.md b/docs/configuring-playbook-prometheus-postgres.md index 51ed9bbd1..f24bc0818 100644 --- a/docs/configuring-playbook-prometheus-postgres.md +++ b/docs/configuring-playbook-prometheus-postgres.md @@ -4,7 +4,7 @@ Expanding on the metrics exposed by the [synapse exporter and the node exporter] ## Adjusting the playbook configuration -To enable the postgres exporter, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable the postgres exporter, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml prometheus_postgres_exporter_enabled: true @@ -21,7 +21,7 @@ Name | Description `prometheus_postgres_exporter_enabled`|Enable the postgres prometheus exporter. This sets up the docker container, connects it to the database and adds a 'job' to the prometheus config which tells prometheus about this new exporter. The default is 'false' `prometheus_postgres_exporter_database_username`| The 'username' for the user that the exporter uses to connect to the database. The default is 'matrix_prometheus_postgres_exporter' `prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook -`prometheus_postgres_exporter_container_labels_traefik_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` on that other documentation page. +`prometheus_postgres_exporter_container_labels_traefik_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.example.com/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` on that other documentation page. ## More information diff --git a/docs/configuring-playbook-rageshake.md b/docs/configuring-playbook-rageshake.md index ae33a0817..34fd08633 100644 --- a/docs/configuring-playbook-rageshake.md +++ b/docs/configuring-playbook-rageshake.md @@ -7,12 +7,12 @@ This is useful if you're developing your own applications and would like to coll ## Decide on a domain and path -By default, Rageshake is configured to use its own dedicated domain (`rageshake.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records). +By default, Rageshake is configured to use its own dedicated domain (`rageshake.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records). You can override the domain and path like this: ```yaml -# Switch to the domain used for Matrix services (`matrix.DOMAIN`), +# Switch to the domain used for Matrix services (`matrix.example.com`), # so we won't need to add additional DNS records for Rageshake. matrix_rageshake_hostname: "{{ matrix_server_fqn_matrix }}" @@ -30,7 +30,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## Enabling the Rageshake service -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_rageshake_enabled: true diff --git a/docs/configuring-playbook-rest-auth.md b/docs/configuring-playbook-rest-auth.md index d1dce0e51..c9352c6c6 100644 --- a/docs/configuring-playbook-rest-auth.md +++ b/docs/configuring-playbook-rest-auth.md @@ -6,7 +6,7 @@ See that project's documentation to learn what it does and why it might be usefu ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_synapse_ext_password_provider_rest_auth_enabled: true diff --git a/docs/configuring-playbook-riot-web.md b/docs/configuring-playbook-riot-web.md index 5ce3a7a2b..f2ffb869a 100644 --- a/docs/configuring-playbook-riot-web.md +++ b/docs/configuring-playbook-riot-web.md @@ -12,20 +12,20 @@ Riot has since been [renamed to Element](https://element.io/blog/welcome-to-elem ### Migrating your custom settings -If you have custom `matrix_riot_web_` variables in your `inventory/host_vars/matrix.DOMAIN/vars.yml` file, you'll need to rename them (`matrix_riot_web_` -> `matrix_client_element_`). +If you have custom `matrix_riot_web_` variables in your `inventory/host_vars/matrix.example.com/vars.yml` file, you'll need to rename them (`matrix_riot_web_` -> `matrix_client_element_`). Some other playbook variables (but not all) with `riot` in their name are also renamed. The playbook checks and warns if you are using the old name for some commonly used ones. ### Domain migration -We used to set up Riot at the `riot.DOMAIN` domain. The playbook now sets up Element at `element.DOMAIN` by default. +We used to set up Riot at the `riot.example.com` domain. The playbook now sets up Element at `element.example.com` by default. There are a few options for handling this: -- (**avoiding changes** - using the old `riot.DOMAIN` domain and avoiding DNS changes) -- to keep using `riot.DOMAIN` instead of `element.DOMAIN`, override the domain at which the playbook serves Element: `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: `matrix_server_fqn_element: "riot.{{ matrix_domain }}"` -- (**embracing changes** - using only `element.DOMAIN`) - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.DOMAIN` 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-goofys.md b/docs/configuring-playbook-s3-goofys.md index 4181cecea..ac32c698c 100644 --- a/docs/configuring-playbook-s3-goofys.md +++ b/docs/configuring-playbook-s3-goofys.md @@ -11,7 +11,7 @@ If you'd like to move your locally-stored media store data to Amazon S3 (or anot ## Adjusting the playbook configuration -After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_s3_media_store_enabled: true diff --git a/docs/configuring-playbook-s3.md b/docs/configuring-playbook-s3.md index 48f44883d..f29f1e3bd 100644 --- a/docs/configuring-playbook-s3.md +++ b/docs/configuring-playbook-s3.md @@ -75,11 +75,11 @@ You [can't easily change which region (US, Europe) your Backblaze account stores After logging in to Backblaze: -- create a new **private** bucket through its user interface (you can call it something like `matrix-DOMAIN-media-store`) +- create a new **private** bucket through its user interface (you can call it something like `matrix-example.com-media-store`) - note the **Endpoint** for your bucket (something like `s3.us-west-002.backblazeb2.com`). - adjust its Lifecycle Rules to: Keep only the last version of the file - go to [App Keys](https://secure.backblaze.com/app_keys.htm) and use the **Add a New Application Key** to create a new one - - restrict it to the previously created bucket (e.g. `matrix-DOMAIN-media-store`) + - restrict it to the previously created bucket (e.g. `matrix-example.com-media-store`) - give it *Read & Write* access The `keyID` value is your **Access Key** and `applicationKey` is your **Secret Key**. diff --git a/docs/configuring-playbook-shared-secret-auth.md b/docs/configuring-playbook-shared-secret-auth.md index 542cd3cee..0c11df290 100644 --- a/docs/configuring-playbook-shared-secret-auth.md +++ b/docs/configuring-playbook-shared-secret-auth.md @@ -6,7 +6,7 @@ See that project's documentation to learn what it does and why it might be usefu ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true diff --git a/docs/configuring-playbook-sliding-sync-proxy.md b/docs/configuring-playbook-sliding-sync-proxy.md index 4a1dd521e..0368f4a3a 100644 --- a/docs/configuring-playbook-sliding-sync-proxy.md +++ b/docs/configuring-playbook-sliding-sync-proxy.md @@ -14,7 +14,7 @@ Element X Android is [available on the Github Releases page](https://github.com/ ## Decide on a domain and path -By default, the Sliding Sync proxy is configured to be served on the Matrix domain (`matrix.DOMAIN`, controlled by `matrix_server_fqn_matrix`), under the `/sliding-sync` path. +By default, the Sliding Sync proxy is configured to be served on the Matrix domain (`matrix.example.com`, controlled by `matrix_server_fqn_matrix`), under the `/sliding-sync` path. This makes it easy to set it up, **without** having to [adjust your DNS records](#adjusting-dns-records). @@ -28,7 +28,7 @@ If you've changed the default hostname, **you may need to adjust your DNS** reco ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_sliding_sync_enabled: true @@ -56,6 +56,6 @@ matrix_sliding_sync_database_name: 'matrix_sliding_sync' You **don't need to do anything special** to make use of the Sliding Sync Proxy. Simply open your client which supports Sliding Sync (like Element X) and log in. -When the Sliding Sync proxy is [installed](#installing), your `/.well-known/matrix/client` file is also updated. A new `org.matrix.msc3575.proxy` section and `url` property are added there and made to point to your Sliding Sync proxy's base URL (e.g. `https://matrix.DOMAIN/sliding-sync`). +When the Sliding Sync proxy is [installed](#installing), your `/.well-known/matrix/client` file is also updated. A new `org.matrix.msc3575.proxy` section and `url` property are added there and made to point to your Sliding Sync proxy's base URL (e.g. `https://matrix.example.com/sliding-sync`). This allows clients which support Sliding Sync to detect the Sliding Sync Proxy's URL and make use of it. diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index 0f1b9e509..583bc0b11 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -9,7 +9,7 @@ This guide is about using the integrated Traefik server and doesn't apply if you For testing purposes, you may wish to use staging certificates provide by Let's Encrypt. -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml traefik_config_certificatesResolvers_acme_use_staging: true @@ -20,7 +20,7 @@ traefik_config_certificatesResolvers_acme_use_staging: true For testing or other purposes, you may wish to install services without SSL termination and have services exposed to `http://` instead of `https://`. -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml traefik_config_entrypoint_web_secure_enabled: false diff --git a/docs/configuring-playbook-sygnal.md b/docs/configuring-playbook-sygnal.md index 77e2f38a9..d7382c3d0 100644 --- a/docs/configuring-playbook-sygnal.md +++ b/docs/configuring-playbook-sygnal.md @@ -13,12 +13,12 @@ This optional playbook component is only useful to people who develop/build thei ## Decide on a domain and path -By default, Sygnal is configured to use its own dedicated domain (`sygnal.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records). +By default, Sygnal is configured to use its own dedicated domain (`sygnal.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records). You can override the domain and path like this: ```yaml -# Switch to the domain used for Matrix services (`matrix.DOMAIN`), +# Switch to the domain used for Matrix services (`matrix.example.com`), # so we won't need to add additional DNS records for Sygnal. matrix_sygnal_hostname: "{{ matrix_server_fqn_matrix }}" @@ -36,7 +36,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_sygnal_enabled: true @@ -87,6 +87,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start ## Usage -To make use of your Sygnal installation, you'd need to build your own Matrix client application, which uses the same API keys (for [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/)) and certificates (for [APNS](https://developer.apple.com/notifications/)) and is to your Sygnal URL endpoint (e.g. `https://sygnal.DOMAIN`). +To make use of your Sygnal installation, you'd need to build your own Matrix client application, which uses the same API keys (for [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/)) and certificates (for [APNS](https://developer.apple.com/notifications/)) and is to your Sygnal URL endpoint (e.g. `https://sygnal.example.com`). Refer to Sygnal's [Notes for application developers](https://github.com/matrix-org/sygnal/blob/master/docs/applications.md) document. diff --git a/docs/configuring-playbook-synapse-admin.md b/docs/configuring-playbook-synapse-admin.md index 1371ea93a..d62423a31 100644 --- a/docs/configuring-playbook-synapse-admin.md +++ b/docs/configuring-playbook-synapse-admin.md @@ -9,7 +9,7 @@ See the project's [documentation](https://github.com/etkecc/synapse-admin) to le ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_admin_enabled: true @@ -30,6 +30,6 @@ After configuring the playbook, run the [installation](installing.md) command: ` ## Usage -After installation, Synapse Admin will be accessible at: `https://matrix.DOMAIN/synapse-admin/` +After installation, Synapse Admin will be accessible at: `https://matrix.example.com/synapse-admin/` To use Synapse Admin, you need to have [registered at least one administrator account](registering-users.md) on your server. diff --git a/docs/configuring-playbook-synapse-auto-accept-invite.md b/docs/configuring-playbook-synapse-auto-accept-invite.md index 057d79d70..4aca475a2 100644 --- a/docs/configuring-playbook-synapse-auto-accept-invite.md +++ b/docs/configuring-playbook-synapse-auto-accept-invite.md @@ -10,7 +10,7 @@ In short, it automatically accepts room invites. You can specify that only 1:1 r ## Configuration -If you decide that you'd like to let this playbook install the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite module for you, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +If you decide that you'd like to let this playbook install the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite module for you, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_ext_synapse_auto_accept_invite_enabled: true diff --git a/docs/configuring-playbook-synapse-auto-compressor.md b/docs/configuring-playbook-synapse-auto-compressor.md index 1d22aa535..da279d9e3 100644 --- a/docs/configuring-playbook-synapse-auto-compressor.md +++ b/docs/configuring-playbook-synapse-auto-compressor.md @@ -9,7 +9,7 @@ See the project's [documentation](https://github.com/matrix-org/rust-synapse-com ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_auto_compressor_enabled: true diff --git a/docs/configuring-playbook-synapse-simple-antispam.md b/docs/configuring-playbook-synapse-simple-antispam.md index a5ba1033d..4c13b987a 100644 --- a/docs/configuring-playbook-synapse-simple-antispam.md +++ b/docs/configuring-playbook-synapse-simple-antispam.md @@ -7,7 +7,7 @@ In short, it lets you fight invite-spam by automatically blocking invitiations f ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs): +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_synapse_ext_spam_checker_synapse_simple_antispam_enabled: true diff --git a/docs/configuring-playbook-synapse-usage-exporter.md b/docs/configuring-playbook-synapse-usage-exporter.md index a67becdf4..85c455b0f 100644 --- a/docs/configuring-playbook-synapse-usage-exporter.md +++ b/docs/configuring-playbook-synapse-usage-exporter.md @@ -13,13 +13,13 @@ Enabling this service will automatically: ## Quickstart -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file and [re-run the installation process](./installing.md) for the playbook: +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file and [re-run the installation process](./installing.md) for the playbook: ```yaml matrix_synapse_usage_exporter_enabled: true # (Optional) Expose endpoint if you want to collect statistics from outside (from other homeservers). -# If enabled, synapse-usage-exporter will be exposed publicly at `matrix.DOMAIN/report-usage-stats/push`. +# If enabled, synapse-usage-exporter will be exposed publicly at `matrix.example.com/report-usage-stats/push`. # When collecting usage statistics for Synapse running on the same host, you don't need to enable this. # You can adjust the hostname and path via `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix`. # matrix_synapse_usage_exporter_proxying_enabled: true diff --git a/docs/configuring-playbook-synapse.md b/docs/configuring-playbook-synapse.md index 60f764bc7..f5a08ae5a 100644 --- a/docs/configuring-playbook-synapse.md +++ b/docs/configuring-playbook-synapse.md @@ -21,7 +21,7 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/element-hq/synapse/blob/master/docs/workers.md) and [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html). -To enable Synapse worker support, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable Synapse worker support, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_workers_enabled: true @@ -126,7 +126,7 @@ If template customization is enabled, the playbook will build a custom container Your custom templates need to live in a public or private git repository. This repository will be cloned during Synapse image customization (during the playbook run). -To enable template customizations, use a configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) like this: +To enable template customizations, use a configuration (`inventory/host_vars/matrix.example.com/vars.yml`) like this: ```yaml # If you'd like to ensure that the customized image is built each time the playbook runs, enable this. diff --git a/docs/configuring-playbook-telemetry.md b/docs/configuring-playbook-telemetry.md index 3d2efde68..a4a9117fd 100644 --- a/docs/configuring-playbook-telemetry.md +++ b/docs/configuring-playbook-telemetry.md @@ -9,7 +9,7 @@ growth of the Matrix community, and helps to make Matrix a success. ## Enabling Telemetry -If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_report_stats: true # for synapse diff --git a/docs/configuring-playbook-traefik.md b/docs/configuring-playbook-traefik.md index 3b49a8bb9..aeab79dbf 100644 --- a/docs/configuring-playbook-traefik.md +++ b/docs/configuring-playbook-traefik.md @@ -25,7 +25,7 @@ traefik_config_accessLog_enabled: false ## Enable Traefik Dashboard -This will enable a Traefik [Dashboard](https://doc.traefik.io/traefik/operations/dashboard/) UI at `https://matrix.DOMAIN/dashboard/` (note the trailing `/`). +This will enable a Traefik [Dashboard](https://doc.traefik.io/traefik/operations/dashboard/) UI at `https://matrix.example.com/dashboard/` (note the trailing `/`). ```yaml traefik_dashboard_enabled: true diff --git a/docs/configuring-playbook-turn.md b/docs/configuring-playbook-turn.md index d41ead932..b347c1309 100644 --- a/docs/configuring-playbook-turn.md +++ b/docs/configuring-playbook-turn.md @@ -7,7 +7,7 @@ By default, the Synapse chat server is configured, so that it points to the Cotu ## Disabling Coturn -If, for some reason, you'd like to prevent the playbook from installing Coturn, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +If, for some reason, you'd like to prevent the playbook from installing Coturn, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_coturn_enabled: false diff --git a/docs/configuring-playbook-user-verification-service.md b/docs/configuring-playbook-user-verification-service.md index ccac883a3..62b3ec00b 100644 --- a/docs/configuring-playbook-user-verification-service.md +++ b/docs/configuring-playbook-user-verification-service.md @@ -31,7 +31,7 @@ In order to use UVS, an admin token for the configured homeserver must be suppli ## Enable [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) installation is disabled by default. -To enable it, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +To enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_user_verification_service_enabled: true diff --git a/docs/faq.md b/docs/faq.md index 50dcdaaf6..24b2f9c35 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -74,9 +74,9 @@ To get started with the playbook, start at the [Prerequisites](prerequisites.md) We have written these automated tasks for you and all you need to do is execute them using the Ansible program. -You can install Ansible and this playbook code repository on your own computer and tell it to install Matrix services at the server living at `matrix.DOMAIN`. We recommend installing Ansible on your own computer. +You can install Ansible and this playbook code repository on your own computer and tell it to install Matrix services at the server living at `matrix.example.com`. We recommend installing Ansible on your own computer. -Alternatively, you can download Ansible and the playbook itself directly on the `matrix.DOMAIN` server. +Alternatively, you can download Ansible and the playbook itself directly on the `matrix.example.com` server. To learn more, see our [dedicated Ansible documentation page](ansible.md). @@ -218,61 +218,61 @@ If your distro runs within an [LXC container](https://linuxcontainers.org/), you ## Configuration -### Why install my server at matrix.DOMAIN and not at the base DOMAIN? +### Why install my server at matrix.example.com and not at the base domain? It's the same with email servers. Your email address is likely `name@company.com`, not `name@mail.company.com`, even though it's `mail.company.com` that is really handling your data for `@company.com` email to work. Using a separate domain name is easier to manage (although it's a little hard to get right at first) and keeps your Matrix server isolated from your website (if you have one), from your email server (if you have one), etc. -We allow `matrix.DOMAIN` to be the Matrix server handling Matrix stuff for `DOMAIN` by [Server Delegation](howto-server-delegation.md). During the installation procedure, we recommend that you set up server delegation using the [.well-known](configuring-well-known.md) method. +We allow `matrix.example.com` to be the Matrix server handling Matrix stuff for `example.com` by [Server Delegation](howto-server-delegation.md). During the installation procedure, we recommend that you set up server delegation using the [.well-known](configuring-well-known.md) method. -If you'd really like to install Matrix services directly on the base domain, see [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain) +If you'd really like to install Matrix services directly on the base domain, see [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) -### I don't control anything on the base domain and can't set up delegation to matrix.DOMAIN. What do I do? +### I don't control anything on the base domain and can't set up delegation to matrix.example.com. What do I do? -If you're not in control of your base domain (or the server handling it) at all, you can take a look at [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain) +If you're not in control of your base domain (or the server handling it) at all, you can take a look at [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) ### I can't set up HTTPS on the base domain. How will I get Matrix federating? -If you really can't obtain an HTTPS certificate for your base domain, you can take a look at [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain) +If you really can't obtain an HTTPS certificate for your base domain, you can take a look at [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) -### How do I install on matrix.DOMAIN without involving the base DOMAIN? +### How do I install on matrix.example.com without involving the base domain? -This Ansible playbook guides you into installing a server for `DOMAIN` (user identifiers are like this: `@user:DOMAIN`), while the server is at `matrix.DOMAIN`. +This Ansible playbook guides you into installing a server for `example.com` (user identifiers are like this: `@user:example.com`), while the server is at `matrix.example.com`. -We allow `matrix.DOMAIN` to be the Matrix server handling Matrix stuff for `DOMAIN` by [Server Delegation](howto-server-delegation.md). During the installation procedure, we recommend that you set up server delegation using the [.well-known](configuring-well-known.md) method. +We allow `matrix.example.com` to be the Matrix server handling Matrix stuff for `example.com` by [Server Delegation](howto-server-delegation.md). During the installation procedure, we recommend that you set up server delegation using the [.well-known](configuring-well-known.md) method. -If you're fine with uglier identifiers (`@user:matrix.DOMAIN`, which is the equivalent of having an email address like `bob@mail.company.com`, instead of just `bob@company.com`), you can do that as well using the following configuration in your `vars.yml` file: +If you're fine with uglier identifiers (`@user:matrix.example.com`, which is the equivalent of having an email address like `bob@mail.company.com`, instead of just `bob@company.com`), you can do that as well using the following configuration in your `vars.yml` file: ```yaml -# This is what your identifiers are like (e.g. `@bob:matrix.YOUR_BASE_DOMAIN`). -matrix_domain: "matrix.YOUR_BASE_DOMAIN" +# This is what your identifiers are like (e.g. `@bob:matrix.example.com`). +matrix_domain: "matrix.example.com" # This is where Matrix services -matrix_server_fqn_matrix: "matrix.YOUR_BASE_DOMAIN" +matrix_server_fqn_matrix: "matrix.example.com" # This is where you access the Element web UI from (if enabled via `matrix_client_element_enabled: true`; enabled by default). # This and the Matrix FQN (see above) are expected to be on the same server. # -# Feel free to use `element.matrix.YOUR_BASE_DOMAIN`, if you'd prefer that. -matrix_server_fqn_element: "element.YOUR_BASE_DOMAIN" +# Feel free to use `element.matrix.example.com`, if you'd prefer that. +matrix_server_fqn_element: "element.example.com" # This is where you access Dimension (if enabled via `matrix_dimension_enabled: true`; NOT enabled by default). # -# Feel free to use `dimension.matrix.YOUR_BASE_DOMAIN`, if you'd prefer that. -matrix_server_fqn_dimension: "dimension.YOUR_BASE_DOMAIN" +# Feel free to use `dimension.matrix.example.com`, if you'd prefer that. +matrix_server_fqn_dimension: "dimension.example.com" # This is where you access Jitsi (if enabled via `jitsi_enabled: true`; NOT enabled by default). # -# Feel free to use `jitsi.matrix.YOUR_BASE_DOMAIN`, if you'd prefer that. -matrix_server_fqn_jitsi: "jitsi.YOUR_BASE_DOMAIN" +# Feel free to use `jitsi.matrix.example.com`, if you'd prefer that. +matrix_server_fqn_jitsi: "jitsi.example.com" ``` ### 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)). -Luckily, the playbook can set up your Matrix server (at `matrix.DOMAIN`) to also handle traffic for the base domain (`DOMAIN`). +Luckily, the playbook can set up your Matrix server (at `matrix.example.com`) to also handle traffic for the base domain (`example.com`). See [Serving the base domain](configuring-playbook-base-domain-serving.md). @@ -332,7 +332,7 @@ Configuration variables are defined in multiple places in this playbook and are - then, there are overrides in `group_vars/matrix_servers`, which aim to adjust these "standalone role defaults" to something which better fits the playbook in its entirety. -- finally, there's your `inventory/host_vars/matrix.DOMAIN/vars.yml` file, which is the ultimate override +- finally, there's your `inventory/host_vars/matrix.example.com/vars.yml` file, which is the ultimate override ### What configuration variables are available? @@ -340,7 +340,7 @@ You can discover the variables you can override in each role (`roles/*/*/default 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`. -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.DOMAIN/vars.yml` file and nothing else inside the playbook (unless you're meaning to contribute new features). +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). **Note**: some of the roles (`roles/galaxy/*`) live in separate repositories and are only installed after your run `just roles` (or `make roles`) or `just update` (which automatically does `git pull` and `just roles`). @@ -373,7 +373,7 @@ Yes, you can. You generally need to do a playbook installation (start at the [Prerequisites](prerequisites.md) page), followed by importing your existing data into it. -This Ansible playbook guides you into installing a server for `DOMAIN` (user identifiers are like this: `@user:DOMAIN`), while the server is at `matrix.DOMAIN`. If your existing setup has a server name (`server_name` configuration setting in Synapse's `homeserver.yaml` file) other than the base `DOMAIN`, 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.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain) +This Ansible playbook guides you into installing a server for `example.com` (user identifiers are like this: `@user: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-matrix-example-com-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/maintenance-and-troubleshooting.md b/docs/maintenance-and-troubleshooting.md index aea32cd8e..b6262a63a 100644 --- a/docs/maintenance-and-troubleshooting.md +++ b/docs/maintenance-and-troubleshooting.md @@ -28,7 +28,7 @@ Because the [Synapse](https://github.com/element-hq/synapse) Matrix server is or If you'd like to debug an issue or [report a Synapse bug](https://github.com/matrix-org/synapse/issues/new/choose) to the developers, it'd be better if you temporarily increasing the logging level to `INFO`. -Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`): +Example configuration (`inventory/host_vars/matrix.example.com/vars.yml`): ```yaml matrix_synapse_log_level: "INFO" diff --git a/docs/maintenance-migrating.md b/docs/maintenance-migrating.md index 638b3c0cb..d71a13e3d 100644 --- a/docs/maintenance-migrating.md +++ b/docs/maintenance-migrating.md @@ -4,7 +4,7 @@ # Migrating to new server -1. Prepare by lowering DNS TTL for your domains (`matrix.DOMAIN`, etc.), so that DNS record changes (step 4 below) would happen faster, leading to less downtime +1. Prepare by lowering DNS TTL for your domains (`matrix.example.com`, etc.), so that DNS record changes (step 4 below) would happen faster, leading to less downtime 2. Stop all services on the old server and make sure they won't be starting again. Execute this on the old server: `systemctl disable --now matrix*` (you might have to cd to /etc/systemd/system/ first) 3. Copy directory `/matrix` from the old server to the new server. Make sure to preserve ownership and permissions (use `cp -p` or `rsync -ar`)! 4. Make sure your DNS records are adjusted to point to the new server's IP address diff --git a/docs/maintenance-synapse.md b/docs/maintenance-synapse.md index f89594a45..b81f91937 100644 --- a/docs/maintenance-synapse.md +++ b/docs/maintenance-synapse.md @@ -55,7 +55,7 @@ First, set up an SSH tunnel to your matrix server (skip if it is your local mach ``` # you may replace 1799 with an arbitrary port unbound on both machines -ssh -L 1799:localhost:1799 matrix.DOMAIN +ssh -L 1799:localhost:1799 matrix.example.com ``` Then start up an ephemeral [adminer](https://www.adminer.org/) container on the Matrix server, connecting it to the `matrix` network and linking the postgresql container: diff --git a/docs/obtaining-access-tokens.md b/docs/obtaining-access-tokens.md index 7db2ef1bf..913f1b90c 100644 --- a/docs/obtaining-access-tokens.md +++ b/docs/obtaining-access-tokens.md @@ -31,9 +31,9 @@ curl -XPOST -d '{ "password": "PASSWORD", "type": "m.login.password", "device_id": "YOURDEVICEID" -}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login' +}' 'https://matrix.example.com/_matrix/client/r0/login' ``` -Change `USERNAME`, `PASSWORD`, and `YOURDOMAIN` accordingly. +Change `USERNAME`, `PASSWORD`, and `example.com` accordingly. `YOURDEVICEID` is optional and can be used to more easily identify the session later. When omitted (mind the commas in the JSON payload if you'll be omitting it), a random device ID will be generated. @@ -41,9 +41,9 @@ Your response will look like this (prettified): ``` { - "user_id":"@USERNAME:YOURDOMAIN", + "user_id":"@USERNAME:example.com", "access_token":">>>YOUR_ACCESS_TOKEN_IS_HERE<<<", - "home_server":"YOURDOMAIN", + "home_server":"example.com", "device_id":"YOURDEVICEID" } ``` diff --git a/docs/registering-users.md b/docs/registering-users.md index 1fddafbbd..b6cd32852 100644 --- a/docs/registering-users.md +++ b/docs/registering-users.md @@ -71,13 +71,13 @@ If you're opening up registrations publicly like this, you might also wish to [c To change the admin privileges for a user, you need to run an SQL query like this against the `synapse` database: ```sql -UPDATE users SET admin=ADMIN_VALUE WHERE name = '@USER:DOMAIN'; +UPDATE users SET admin=ADMIN_VALUE WHERE name = '@USER:example.com'; ``` where: - `ADMIN_VALUE` being either `0` (regular user) or `1` (admin) -- `USER` and `DOMAIN` pointing to a valid user on your server +- `USER` and `example.com` pointing to a valid user on your server 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: diff --git a/examples/reverse-proxies/apache/README.md b/examples/reverse-proxies/apache/README.md index a25ba2017..939df3f22 100644 --- a/examples/reverse-proxies/apache/README.md +++ b/examples/reverse-proxies/apache/README.md @@ -10,5 +10,5 @@ To get started, first follow the [front the integrated reverse-proxy webserver w `matrix-domain.conf` contains configuration for the Matrix domain, which handles both the Client-Server API (port `443`) and the Matrix Federation API (port `8448`). -`matrix-client-element.conf` is an example for when you're hosting Element at `element.DOMAIN`. -This configuration can also be used as an example for handling other domains, depending on the services you enable with the playbook (e.g. `dimension.DOMAIN`, etc). +`matrix-client-element.conf` is an example for when you're hosting Element at `element.example.com`. +This configuration can also be used as an example for handling other domains, depending on the services you enable with the playbook (e.g. `dimension.example.com`, etc). diff --git a/examples/reverse-proxies/apache/matrix-client-element.conf b/examples/reverse-proxies/apache/matrix-client-element.conf index 005a9fc28..6ae104ea4 100644 --- a/examples/reverse-proxies/apache/matrix-client-element.conf +++ b/examples/reverse-proxies/apache/matrix-client-element.conf @@ -1,23 +1,23 @@ -# This is a sample file demonstrating how to set up reverse-proxy for element.DOMAIN. +# This is a sample file demonstrating how to set up reverse-proxy for element.example.com. # If you're not using Element (`matrix_client_element_enabled: false`), you won't need this. - ServerName element.DOMAIN + ServerName element.example.com # You may wish to handle the /.well-known/acme-challenge paths here somehow, # if you're using ACME (Let's Encrypt) certificates. - Redirect permanent / https://element.DOMAIN/ + Redirect permanent / https://element.example.com/ - ServerName element.DOMAIN + ServerName element.example.com SSLEngine On # If you manage SSL certificates by yourself, these paths will differ. - SSLCertificateFile /matrix/ssl/config/live/element.DOMAIN/fullchain.pem - SSLCertificateKeyFile /matrix/ssl/config/live/element.DOMAIN/privkey.pem + SSLCertificateFile /matrix/ssl/config/live/element.example.com/fullchain.pem + SSLCertificateKeyFile /matrix/ssl/config/live/element.example.com/privkey.pem SSLProxyEngine on SSLProxyProtocol +TLSv1.2 +TLSv1.3 @@ -30,6 +30,6 @@ ProxyPass / http://127.0.0.1:81/ ProxyPassReverse / http://127.0.0.1:81/ - ErrorLog ${APACHE_LOG_DIR}/element.DOMAIN-error.log - CustomLog ${APACHE_LOG_DIR}/element.DOMAIN-access.log combined + ErrorLog ${APACHE_LOG_DIR}/element.example.com-error.log + CustomLog ${APACHE_LOG_DIR}/element.example.com-access.log combined diff --git a/examples/reverse-proxies/apache/matrix-domain.conf b/examples/reverse-proxies/apache/matrix-domain.conf index 4c79558b2..18aaabd25 100644 --- a/examples/reverse-proxies/apache/matrix-domain.conf +++ b/examples/reverse-proxies/apache/matrix-domain.conf @@ -1,23 +1,23 @@ -# This is a sample file demonstrating how to set up reverse-proxy for matrix.DOMAIN +# This is a sample file demonstrating how to set up reverse-proxy for matrix.example.com - ServerName matrix.DOMAIN + ServerName matrix.example.com # You may wish to handle the /.well-known/acme-challenge paths here somehow, # if you're using ACME (Let's Encrypt) certificates. - Redirect permanent / https://matrix.DOMAIN/ + Redirect permanent / https://matrix.example.com/ # Client-Server API - ServerName matrix.DOMAIN + ServerName matrix.example.com SSLEngine On # If you manage SSL certificates by yourself, these paths will differ. - SSLCertificateFile /path/to/matrix.DOMAIN/fullchain.pem - SSLCertificateKeyFile /path/to/matrix.DOMAIN/privkey.pem + SSLCertificateFile /path/to/matrix.example.com/fullchain.pem + SSLCertificateKeyFile /path/to/matrix.example.com/privkey.pem SSLProxyEngine on SSLProxyProtocol +TLSv1.2 +TLSv1.3 @@ -32,20 +32,20 @@ ProxyPass / http://127.0.0.1:81/ retry=0 nocanon ProxyPassReverse / http://127.0.0.1:81/ - ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log - CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined + ErrorLog ${APACHE_LOG_DIR}/matrix.example.com-error.log + CustomLog ${APACHE_LOG_DIR}/matrix.example.com-access.log combined # Server-Server (federation) API Listen 8448 - ServerName matrix.DOMAIN + ServerName matrix.example.com SSLEngine On # If you manage SSL certificates by yourself, these paths will differ. - SSLCertificateFile /matrix/ssl/config/live/matrix.DOMAIN/fullchain.pem - SSLCertificateKeyFile /matrix/ssl/config/live/matrix.DOMAIN/privkey.pem + SSLCertificateFile /matrix/ssl/config/live/matrix.example.com/fullchain.pem + SSLCertificateKeyFile /matrix/ssl/config/live/matrix.example.com/privkey.pem SSLProxyEngine on SSLProxyProtocol +TLSv1.2 +TLSv1.3 @@ -60,6 +60,6 @@ Listen 8448 ProxyPass / http://127.0.0.1:8449/ retry=0 nocanon ProxyPassReverse / http://127.0.0.1:8449/ - ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log - CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined + ErrorLog ${APACHE_LOG_DIR}/matrix.example.com-error.log + CustomLog ${APACHE_LOG_DIR}/matrix.example.com-access.log combined diff --git a/examples/reverse-proxies/nginx-proxy-manager/README.md b/examples/reverse-proxies/nginx-proxy-manager/README.md index b4bce8846..aa7a7b53e 100644 --- a/examples/reverse-proxies/nginx-proxy-manager/README.md +++ b/examples/reverse-proxies/nginx-proxy-manager/README.md @@ -21,14 +21,14 @@ Open the 'Proxy Hosts' page in the NPM web interface and select `Add Proxy Host` ```md # Details # Matrix web proxy config -Domain Names: matrix.DOMAIN +Domain Names: matrix.example.com Scheme: http Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX Forward Port: 81 # SSL # Either 'Request a new certificate' or select an existing one -SSL Certificate: matrix.DOMAIN or *.DOMAIN +SSL Certificate: matrix.example.com or *.example.com Force SSL: true HTTP/2 Support: true @@ -42,14 +42,14 @@ Again, under the 'Proxy Hosts' page select `Add Proxy Host`, this time for your ```md # Details # Matrix Federation proxy config -Domain Names: matrix.DOMAIN:8448 +Domain Names: matrix.example.com:8448 Scheme: http Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX Forward Port: 8449 # SSL # Either 'Request a new certificate' or select an existing one -SSL Certificate: matrix.DOMAIN or *.DOMAIN +SSL Certificate: matrix.example.com or *.example.com Force SSL: true HTTP/2 Support: true @@ -60,4 +60,4 @@ Custom Nginx Configuration: client_max_body_size 50M; ``` -Also note, NPM would need to be configured for whatever other services you are using. For example, you would need to create additional proxy hosts for `element.DOMAIN` or `jitsi.DOMAIN`, which would use the forwarding port `81`. +Also note, NPM would need to be configured for whatever other services you are using. For example, you would need to create additional proxy hosts for `element.example.com` or `jitsi.example.com`, which would use the forwarding port `81`. diff --git a/examples/reverse-proxies/nginx/README.md b/examples/reverse-proxies/nginx/README.md index be52550e5..b57d4557d 100644 --- a/examples/reverse-proxies/nginx/README.md +++ b/examples/reverse-proxies/nginx/README.md @@ -12,6 +12,6 @@ To get started, first follow the [front the integrated reverse-proxy webserver w Copy the [matrix.conf](matrix.conf) file to your nginx server's filesystem, modify it to your needs and include it in your nginx configuration (e.g. `include /path/to/matrix.conf;`). -This configuration **disables SSL certificate retrieval**, so you will **need to obtain SSL certificates manually** (e.g. by using [certbot](https://certbot.eff.org/)) and set the appropriate path in `matrix.conf`. In the example nginx configuration, a single certificate is used for all subdomains (`matrix.DOMAIN`, `element.DOMAIN`, etc.). For your setup, may wish to change this and use separate `server` blocks and separate certificate files for each host. +This configuration **disables SSL certificate retrieval**, so you will **need to obtain SSL certificates manually** (e.g. by using [certbot](https://certbot.eff.org/)) and set the appropriate path in `matrix.conf`. In the example nginx configuration, a single certificate is used for all subdomains (`matrix.example.com`, `element.example.com`, etc.). For your setup, may wish to change this and use separate `server` blocks and separate certificate files for each host. Also note that your copy of the `matrix.conf` file has to be adapted to whatever services you are using. For example, remove `element.example.com` from the `server_name` list if you don't use [Element](../../../docs/configuring-playbook-client-element.md) web client or add `dimension.example.com` to it if you do use the [Dimension](../../../docs/configuring-playbook-dimension.md) integration manager. diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 0fbda0089..e0f7f907b 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -258,7 +258,7 @@ matrix_homeserver_sliding_sync_url: "{{ matrix_sliding_sync_base_url if matrix_s # - 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 -# - since Coturn is started before the homeserver, there's no container label telling Traefik to get a `matrix.DOMAIN` certificate +# - since Coturn is started before the homeserver, there's no container label telling Traefik to get a `matrix.example.com` certificate # - thus, Coturn would spin and wait for a certificate until it fails. We'd get a playbook failure due to it, but service manager will proceed to start all other services anyway. # - only later, when the homeserver actually starts, would that certificate be fetched and dumped # - reverse-proxying services get level 3000 diff --git a/roles/custom/matrix-alertmanager-receiver/defaults/main.yml b/roles/custom/matrix-alertmanager-receiver/defaults/main.yml index ee23b09b7..adc43220a 100644 --- a/roles/custom/matrix-alertmanager-receiver/defaults/main.yml +++ b/roles/custom/matrix-alertmanager-receiver/defaults/main.yml @@ -41,7 +41,7 @@ matrix_alertmanager_receiver_container_additional_networks_default: [] matrix_alertmanager_receiver_container_additional_networks_auto: [] matrix_alertmanager_receiver_container_additional_networks_custom: [] -# Controls whether matrix-alertmanager-receiver metrics should be proxied (exposed) on `matrix.DOMAIN/metrics/matrix-alertmanager-receiver` +# Controls whether matrix-alertmanager-receiver metrics should be proxied (exposed) on `matrix.example.com/metrics/matrix-alertmanager-receiver` matrix_alertmanager_receiver_metrics_proxying_enabled: false matrix_alertmanager_receiver_metrics_proxying_hostname: '' matrix_alertmanager_receiver_metrics_proxying_path: /metrics/matrix-alertmanager-receiver diff --git a/roles/custom/matrix-base/defaults/main.yml b/roles/custom/matrix-base/defaults/main.yml index 5dce05582..9cc9850cd 100644 --- a/roles/custom/matrix-base/defaults/main.yml +++ b/roles/custom/matrix-base/defaults/main.yml @@ -289,7 +289,7 @@ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_definition: # may wish to register their routes with this additional entrypoint and provide their services on it for internal (no-public-network and non-TLS) use. # # This entrypoint provides local addons (e.g. bridges, bots, etc.) with the ability to easily & quickly communicate with the homeserver and/or related software. -# Such services can reach the homeserver over the public internet (e.g. https://matrix.DOMAIN), but this is slow due to networking and SSL-termination. +# Such services can reach the homeserver over the public internet (e.g. https://matrix.example.com), but this is slow due to networking and SSL-termination. # Talking directly to the homeserver (e.g. `http://matrix-synapse:8008`) is another option, but does not allow other homeserver-related software # (e.g. identity servers like ma1sd, media repository servers like matrix-media-repo, firewalls like matrix-corporal) # to register itself for certain homeserver routes. diff --git a/roles/custom/matrix-base/tasks/validate_config.yml b/roles/custom/matrix-base/tasks/validate_config.yml index 3ca6061b4..fd389cd1c 100644 --- a/roles/custom/matrix-base/tasks/validate_config.yml +++ b/roles/custom/matrix-base/tasks/validate_config.yml @@ -30,7 +30,7 @@ If you're observing this error on a new installation, you should ensure that the `matrix_homeserver_generic_secret_key` is defined. If you think you've defined it, but are still getting this error, then it's likely that you have a typo - in your domain name in `inventory/hosts` or in one of the directories leading up to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file. + in your domain name in `inventory/hosts` or in one of the directories leading up to your `inventory/host_vars/matrix.example.com/vars.yml` file. If you're observing this error on an existing homeserver installation, you can fix it easily and in a backward-compatible way by adding `{% raw %}matrix_homeserver_generic_secret_key: "{{ matrix_synapse_macaroon_secret_key }}"{% endraw %}` diff --git a/roles/custom/matrix-bot-chatgpt/defaults/main.yml b/roles/custom/matrix-bot-chatgpt/defaults/main.yml index 8d1bc733c..aab8a5d90 100644 --- a/roles/custom/matrix-bot-chatgpt/defaults/main.yml +++ b/roles/custom/matrix-bot-chatgpt/defaults/main.yml @@ -57,7 +57,7 @@ matrix_bot_chatgpt_keyv_bot_storage: true # Matrix Static Settings (required, see notes) # Defaults to "https://matrix.org" matrix_bot_chatgpt_matrix_homeserver_url: "" # MATRIX_HOMESERVER_URL= -# With the @ and :DOMAIN, ie @SOMETHING:DOMAIN, needs to be set, created manually beforehand. +# With the @ and :example.com, ie @SOMETHING:example.com, needs to be set, created manually beforehand. matrix_bot_chatgpt_matrix_bot_username_localpart: 'bot.chatgpt' matrix_bot_chatgpt_matrix_bot_username: "@{{ matrix_bot_chatgpt_matrix_bot_username_localpart }}:{{ matrix_domain }}" # MATRIX_BOT_USERNAME= # Set `MATRIX_BOT_PASSWORD` the bot will print an `MATRIX_ACCESS_TOKEN` to the terminal diff --git a/roles/custom/matrix-bot-chatgpt/templates/env.j2 b/roles/custom/matrix-bot-chatgpt/templates/env.j2 index d9ca2d50c..a6f62cc67 100644 --- a/roles/custom/matrix-bot-chatgpt/templates/env.j2 +++ b/roles/custom/matrix-bot-chatgpt/templates/env.j2 @@ -10,7 +10,7 @@ KEYV_URL={{ matrix_bot_chatgpt_keyv_url }} KEYV_BOT_ENCRYPTION={{ matrix_bot_chatgpt_keyv_bot_encryption|lower }} KEYV_BOT_STORAGE={{ matrix_bot_chatgpt_keyv_bot_storage|lower }} -# With the @ and :DOMAIN, ie @SOMETHING:DOMAIN +# With the @ and :example.com, ie @SOMETHING:example.com MATRIX_BOT_USERNAME={{ matrix_bot_chatgpt_matrix_bot_username }} MATRIX_BOT_PASSWORD={{ matrix_bot_chatgpt_matrix_bot_password }} diff --git a/roles/custom/matrix-bridge-hookshot/tasks/validate_config.yml b/roles/custom/matrix-bridge-hookshot/tasks/validate_config.yml index 9a0f38353..33871b77b 100644 --- a/roles/custom/matrix-bridge-hookshot/tasks/validate_config.yml +++ b/roles/custom/matrix-bridge-hookshot/tasks/validate_config.yml @@ -102,7 +102,7 @@ ansible.builtin.fail: msg: >- Your configuration contains a variable (`{{ item }}`), which refers to the old metrics collection system for Hookshot, - which exposed metrics on `https://stats.DOMAIN/hookshot/metrics`. + which exposed metrics on `https://stats.example.com/hookshot/metrics`. We now recommend exposing Hookshot metrics in another way, from another URL. Refer to the changelog for more details: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md#2022-06-22 diff --git a/roles/custom/matrix-bridge-mautrix-meta-instagram/defaults/main.yml b/roles/custom/matrix-bridge-mautrix-meta-instagram/defaults/main.yml index 33d16a94a..327e8b0ab 100644 --- a/roles/custom/matrix-bridge-mautrix-meta-instagram/defaults/main.yml +++ b/roles/custom/matrix-bridge-mautrix-meta-instagram/defaults/main.yml @@ -114,10 +114,10 @@ matrix_mautrix_meta_instagram_appservice_address: "http://{{ matrix_mautrix_meta matrix_mautrix_meta_instagram_appservice_id: "{{ matrix_mautrix_meta_instagram_meta_mode }}" -# For Facebook/Messenger, we use the same `@messengerbot:DOMAIN` username regardless of how bridging happens for multiple reasons: +# For Facebook/Messenger, we use the same `@messengerbot:example.com` username regardless of how bridging happens for multiple reasons: # - it's consistent - regardless of how bridging happens, the bridged service is actually Messenger -# - it's easy for users - you may change the mode, but the bot is always at `@messengerbot:DOMAIN` -# - it doesn't conflict with mautrix-facebook which uses `@facebookbot:DOMAIN` +# - it's easy for users - you may change the mode, but the bot is always at `@messengerbot:example.com` +# - it doesn't conflict with mautrix-facebook which uses `@facebookbot:example.com` # - `matrix_mautrix_meta_instagram_appservice_avatar` only has icons for Messenger and Instagram, not Facebook matrix_mautrix_meta_instagram_appservice_username_prefix: |- {{ diff --git a/roles/custom/matrix-bridge-mautrix-meta-messenger/defaults/main.yml b/roles/custom/matrix-bridge-mautrix-meta-messenger/defaults/main.yml index 7c99f5d33..9b561f2df 100644 --- a/roles/custom/matrix-bridge-mautrix-meta-messenger/defaults/main.yml +++ b/roles/custom/matrix-bridge-mautrix-meta-messenger/defaults/main.yml @@ -114,10 +114,10 @@ matrix_mautrix_meta_messenger_appservice_address: "http://{{ matrix_mautrix_meta matrix_mautrix_meta_messenger_appservice_id: "{{ matrix_mautrix_meta_messenger_meta_mode }}" -# For Facebook/Messenger, we use the same `@messengerbot:DOMAIN` username regardless of how bridging happens for multiple reasons: +# For Facebook/Messenger, we use the same `@messengerbot:example.com` username regardless of how bridging happens for multiple reasons: # - it's consistent - regardless of how bridging happens, the bridged service is actually Messenger -# - it's easy for users - you may change the mode, but the bot is always at `@messengerbot:DOMAIN` -# - it doesn't conflict with mautrix-facebook which uses `@facebookbot:DOMAIN` +# - it's easy for users - you may change the mode, but the bot is always at `@messengerbot:example.com` +# - it doesn't conflict with mautrix-facebook which uses `@facebookbot:example.com` # - `matrix_mautrix_meta_messenger_appservice_avatar` only has icons for Messenger and Instagram, not Facebook matrix_mautrix_meta_messenger_appservice_username_prefix: |- {{ diff --git a/roles/custom/matrix-media-repo/defaults/main.yml b/roles/custom/matrix-media-repo/defaults/main.yml index 7f1ce62c4..aef4eb04b 100755 --- a/roles/custom/matrix-media-repo/defaults/main.yml +++ b/roles/custom/matrix-media-repo/defaults/main.yml @@ -44,7 +44,7 @@ matrix_media_repo_container_network: "{{ matrix_media_repo_identifier }}" # Use this to expose this container to another reverse proxy, which runs in a different container network. matrix_media_repo_container_additional_networks: [] -# Controls whether media repo metrics should be proxied (exposed) on `matrix.DOMAIN/metrics/matrix-media-repo` +# Controls whether media repo metrics should be proxied (exposed) on `matrix.example.com/metrics/matrix-media-repo` matrix_media_repo_metrics_proxying_enabled: false matrix_media_repo_metrics_proxying_hostname: "" matrix_media_repo_metrics_proxying_path: "/metrics/matrix-media-repo" diff --git a/roles/custom/matrix-registration/defaults/main.yml b/roles/custom/matrix-registration/defaults/main.yml index f2b87d942..008b9b75c 100644 --- a/roles/custom/matrix-registration/defaults/main.yml +++ b/roles/custom/matrix-registration/defaults/main.yml @@ -114,7 +114,7 @@ matrix_registration_api_token_endpoint: "{{ matrix_registration_scheme }}://{{ m matrix_registration_api_validate_certs: true -# The URL to your homeserver (e.g.: `https://matrix.DOMAIN`). +# The URL to your homeserver (e.g.: `https://matrix.example.com`). # A local (in-container address) is preferable. matrix_registration_server_location: "" diff --git a/roles/custom/matrix-sliding-sync/defaults/main.yml b/roles/custom/matrix-sliding-sync/defaults/main.yml index 65f51be4c..81e5a44a2 100644 --- a/roles/custom/matrix-sliding-sync/defaults/main.yml +++ b/roles/custom/matrix-sliding-sync/defaults/main.yml @@ -43,7 +43,7 @@ matrix_sliding_sync_container_additional_networks: [] matrix_sliding_sync_metrics_enabled: false matrix_sliding_sync_metrics_port: 2112 -# Controls whether Sliding Sync metrics should be proxied (exposed) on `matrix.DOMAIN/metrics/sliding-sync` +# Controls whether Sliding Sync metrics should be proxied (exposed) on `matrix.example.com/metrics/sliding-sync` matrix_sliding_sync_metrics_proxying_enabled: false matrix_sliding_sync_metrics_proxying_hostname: '' matrix_sliding_sync_metrics_proxying_path: /metrics/sliding-sync diff --git a/roles/custom/matrix-static-files/defaults/main.yml b/roles/custom/matrix-static-files/defaults/main.yml index 51a996dc0..09e9d4215 100644 --- a/roles/custom/matrix-static-files/defaults/main.yml +++ b/roles/custom/matrix-static-files/defaults/main.yml @@ -386,6 +386,6 @@ matrix_static_files_self_check_well_known_matrix_client_follow_redirects: none # TODO - review this one # Specifies where requests for the root URI (`/`) on the `matrix.` domain should be redirected. # If this has an empty value, they're just passed to the homeserver, which serves a static page. -# If you'd like to make `https://matrix.DOMAIN` redirect to `https://element.DOMAIN` (or something of that sort), specify the domain name here. -# Example value: `element.DOMAIN` (or `{{ matrix_server_fqn_element }}`). +# If you'd like to make `https://matrix.example.com` redirect to `https://element.example.com` (or something of that sort), specify the domain name here. +# Example value: `element.example.com` (or `{{ matrix_server_fqn_element }}`). matrix_static_files_client_redirect_root_uri_to_domain: "" diff --git a/roles/custom/matrix-synapse-usage-exporter/defaults/main.yml b/roles/custom/matrix-synapse-usage-exporter/defaults/main.yml index c207e4b1c..71f7b7423 100644 --- a/roles/custom/matrix-synapse-usage-exporter/defaults/main.yml +++ b/roles/custom/matrix-synapse-usage-exporter/defaults/main.yml @@ -51,7 +51,7 @@ matrix_synapse_usage_exporter_container_extra_arguments: [] # Controls whether the synapse-usage-exporter's web services should be proxied (exposed publicly). # -# Exposure happens on `matrix.DOMAIN/report-usage-stats/push` by default. +# Exposure happens on `matrix.example.com/report-usage-stats/push` by default. # See: `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix`. matrix_synapse_usage_exporter_proxying_enabled: false diff --git a/roles/custom/matrix-synapse/defaults/main.yml b/roles/custom/matrix-synapse/defaults/main.yml index c7489fa50..e9cf89e7b 100644 --- a/roles/custom/matrix-synapse/defaults/main.yml +++ b/roles/custom/matrix-synapse/defaults/main.yml @@ -733,8 +733,8 @@ matrix_synapse_grafana_dashboard_urls: - https://raw.githubusercontent.com/element-hq/synapse/master/contrib/grafana/synapse.json # Controls whether Synapse metrics should be proxied (exposed) on: -# - `matrix.DOMAIN/metrics/synapse/main-process` for the main process -# - `matrix.DOMAIN/metrics/synapse/worker/{type}-{id}` for each worker process +# - `matrix.example.com/metrics/synapse/main-process` for the main process +# - `matrix.example.com/metrics/synapse/worker/{type}-{id}` for each worker process matrix_synapse_metrics_proxying_enabled: false matrix_synapse_metrics_proxying_hostname: '' matrix_synapse_metrics_proxying_path_prefix: /metrics/synapse