mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2024-12-24 18:08:28 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3628 from luixxiul/fix

Browse Source 
Adopt special-use domain names for documentation purpose
This commit is contained in:
Slavi Pantaleev 2024-10-18 14:57:54 +03:00 committed by GitHub
commit e27fb2e206
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
156 changed files with 546 additions and 547 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
CHANGELOG.md
View File

@ -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.

2
README.md
View File

@ -6,7 +6,7 @@
This [Ansible](https://www.ansible.com/) playbook is meant to help you run your own [Matrix](http://matrix.org/) homeserver, along with the [various services](#supported-services) related to that.
That is, it lets you join the Matrix network using your own `@<username>:<your-domain>` identifier, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
That is, it lets you join the Matrix network using your own `@<username>:example.com` identifier, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
We run all services in [Docker](https://www.docker.com/) containers (see [the container images we use](docs/container-images.md)), which lets us have a predictable and up-to-date setup, across multiple supported distros (see [prerequisites](docs/prerequisites.md)) and [architectures](docs/alternative-architectures.md) (x86/amd64 being recommended).

2
docs/configuring-captcha.md
View File

@ -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

70
docs/configuring-dns.md
View File

@ -2,14 +2,14 @@
To set up Matrix on your domain, you'd need to do some DNS configuration.
To use an identifier like `@<username>:<your-domain>`, you don't actually need
to install anything on the actual `<your-domain>` server.
To use an identifier like `@<username>:example.com`, you don't actually need
to install anything on the actual `example.com` server.
You do, however need to instruct the Matrix network that Matrix services for `<your-domain>` are delegated
over to `matrix.<your-domain>`.
You do, however need to instruct the Matrix network that Matrix services for `example.com` are delegated
over to `matrix.example.com`.
As we discuss in [Server Delegation](howto-server-delegation.md), there are 2 different ways to set up such delegation:
- either by serving a `https://<your-domain>/.well-known/matrix/server` file (from the base domain!)
- either by serving a `https://example.com/.well-known/matrix/server` file (from the base domain!)
- or by using a `_matrix._tcp` DNS SRV record (don't confuse this with the `_matrix-identity._tcp` SRV record described below)
This playbook mostly discusses the well-known file method, because it's easier to manage with regard to certificates.
@ -20,7 +20,7 @@ If you decide to go with the alternative method ([Server Delegation via a DNS SR
| Type | Host | Priority | Weight | Port | Target |
| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
| A | `matrix` | - | - | - | `matrix-server-IP` |
| CNAME | `element` | - | - | - | `matrix.<your-domain>` |
| CNAME | `element` | - | - | - | `matrix.example.com` |
Be mindful as to how long it will take for the DNS records to propagate.
@ -32,20 +32,20 @@ When you're done configuring DNS, proceed to [Configuring the playbook](configur
| Used by component | Type | Host | Priority | Weight | Port | Target |
| ----------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | -------- | ------ | ---- | --------------------------- |
| [ma1sd](configuring-playbook-ma1sd.md) identity server | SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.<your-domain>` |
| [Dimension](configuring-playbook-dimension.md) integration server | CNAME | `dimension` | - | - | - | `matrix.<your-domain>` |
| [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform | CNAME | `jitsi` | - | - | - | `matrix.<your-domain>` |
| [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system | CNAME | `stats` | - | - | - | `matrix.<your-domain>` |
| [Go-NEB](configuring-playbook-bot-go-neb.md) bot | CNAME | `goneb` | - | - | - | `matrix.<your-domain>` |
| [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.<your-domain>` |
| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.<your-domain>` |
| [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
| [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.<your-domain>` |
| [SchildiChat](configuring-playbook-client-schildichat.md) web client | CNAME | `schildichat` | - | - | - | `matrix.<your-domain>` |
| [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge | CNAME | `wsproxy` | - | - | - | `matrix.<your-domain>` |
| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.<your-domain>` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX | `matrix` | 10 | 0 | - | `matrix.<your-domain>` |
| [ma1sd](configuring-playbook-ma1sd.md) identity server | SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.example.com` |
| [Dimension](configuring-playbook-dimension.md) integration server | CNAME | `dimension` | - | - | - | `matrix.example.com` |
| [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform | CNAME | `jitsi` | - | - | - | `matrix.example.com` |
| [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system | CNAME | `stats` | - | - | - | `matrix.example.com` |
| [Go-NEB](configuring-playbook-bot-go-neb.md) bot | CNAME | `goneb` | - | - | - | `matrix.example.com` |
| [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.example.com` |
| [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.example.com` |
| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.example.com` |
| [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.example.com` |
| [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.example.com` |
| [SchildiChat](configuring-playbook-client-schildichat.md) web client | CNAME | `schildichat` | - | - | - | `matrix.example.com` |
| [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge | CNAME | `wsproxy` | - | - | - | `matrix.example.com` |
| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.example.com` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX | `matrix` | 10 | 0 | - | `matrix.example.com` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `matrix` | - | - | - | `v=spf1 ip4:<your-ip> -all` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `postmoogle._domainkey.matrix` | - | - | - | get it from `!pm dkim` |
@ -54,38 +54,38 @@ When setting up a SRV record, if you are asked for a service and protocol instea
## Subdomains setup
As the table above illustrates, you need to create 2 subdomains (`matrix.<your-domain>` and `element.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` record is fine).
As the table above illustrates, you need to create 2 subdomains (`matrix.example.com` and `element.example.com`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` record is fine).
The `element.<your-domain>` subdomain may be necessary, because this playbook installs the [Element](https://github.com/element-hq/element-web) web client for you.
If you'd rather instruct the playbook not to install Element (`matrix_client_element_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `element.<your-domain>` DNS record.
The `element.example.com` subdomain may be necessary, because this playbook installs the [Element](https://github.com/element-hq/element-web) web client for you.
If you'd rather instruct the playbook not to install Element (`matrix_client_element_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `element.example.com` DNS record.
The `dimension.<your-domain>` subdomain may be necessary, because this playbook could install the [Dimension integrations manager](http://dimension.t2bot.io/) for you. Dimension installation is disabled by default, because it's only possible to install it after the other Matrix services are working (see [Setting up Dimension](configuring-playbook-dimension.md) later). If you do not wish to set up Dimension, feel free to skip the `dimension.<your-domain>` DNS record.
The `dimension.example.com` subdomain may be necessary, because this playbook could install the [Dimension integrations manager](http://dimension.t2bot.io/) for you. Dimension installation is disabled by default, because it's only possible to install it after the other Matrix services are working (see [Setting up Dimension](configuring-playbook-dimension.md) later). If you do not wish to set up Dimension, feel free to skip the `dimension.example.com` DNS record.
The `jitsi.<your-domain>` subdomain may be necessary, because this playbook could install the [Jitsi video-conferencing platform](https://jitsi.org/) for you. Jitsi installation is disabled by default, because it may be heavy and is not a core required component. To learn how to install it, see our [Jitsi](configuring-playbook-jitsi.md) guide. If you do not wish to set up Jitsi, feel free to skip the `jitsi.<your-domain>` DNS record.
The `jitsi.example.com` subdomain may be necessary, because this playbook could install the [Jitsi video-conferencing platform](https://jitsi.org/) for you. Jitsi installation is disabled by default, because it may be heavy and is not a core required component. To learn how to install it, see our [Jitsi](configuring-playbook-jitsi.md) guide. If you do not wish to set up Jitsi, feel free to skip the `jitsi.example.com` DNS record.
The `stats.<your-domain>` subdomain may be necessary, because this playbook could install [Grafana](https://grafana.com/) and setup performance metrics for you. Grafana installation is disabled by default, it is not a core required component. To learn how to install it, see our [metrics and graphs guide](configuring-playbook-prometheus-grafana.md). If you do not wish to set up Grafana, feel free to skip the `stats.<your-domain>` DNS record. It is possible to install Prometheus without installing Grafana, this would also not require the `stats.<your-domain>` subdomain.
The `stats.example.com` subdomain may be necessary, because this playbook could install [Grafana](https://grafana.com/) and setup performance metrics for you. Grafana installation is disabled by default, it is not a core required component. To learn how to install it, see our [metrics and graphs guide](configuring-playbook-prometheus-grafana.md). If you do not wish to set up Grafana, feel free to skip the `stats.example.com` DNS record. It is possible to install Prometheus without installing Grafana, this would also not require the `stats.example.com` subdomain.
The `goneb.<your-domain>` subdomain may be necessary, because this playbook could install the [Go-NEB](https://github.com/matrix-org/go-neb) bot. The installation of Go-NEB is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Go-NEB guide](configuring-playbook-bot-go-neb.md). If you do not wish to set up Go-NEB, feel free to skip the `goneb.<your-domain>` DNS record.
The `goneb.example.com` subdomain may be necessary, because this playbook could install the [Go-NEB](https://github.com/matrix-org/go-neb) bot. The installation of Go-NEB is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Go-NEB guide](configuring-playbook-bot-go-neb.md). If you do not wish to set up Go-NEB, feel free to skip the `goneb.example.com` DNS record.
The `sygnal.<your-domain>` subdomain may be necessary, because this playbook could install the [Sygnal](https://github.com/matrix-org/sygnal) push gateway. The installation of Sygnal is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Sygnal guide](configuring-playbook-sygnal.md). If you do not wish to set up Sygnal (you probably don't, unless you're also developing/building your own Matrix apps), feel free to skip the `sygnal.<your-domain>` DNS record.
The `sygnal.example.com` subdomain may be necessary, because this playbook could install the [Sygnal](https://github.com/matrix-org/sygnal) push gateway. The installation of Sygnal is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Sygnal guide](configuring-playbook-sygnal.md). If you do not wish to set up Sygnal (you probably don't, unless you're also developing/building your own Matrix apps), feel free to skip the `sygnal.example.com` DNS record.
The `ntfy.<your-domain>` subdomain may be necessary, because this playbook could install the [ntfy](https://ntfy.sh/) UnifiedPush-compatible push notifications server. The installation of ntfy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring ntfy guide](configuring-playbook-ntfy.md). If you do not wish to set up ntfy, feel free to skip the `ntfy.<your-domain>` DNS record.
The `ntfy.example.com` subdomain may be necessary, because this playbook could install the [ntfy](https://ntfy.sh/) UnifiedPush-compatible push notifications server. The installation of ntfy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring ntfy guide](configuring-playbook-ntfy.md). If you do not wish to set up ntfy, feel free to skip the `ntfy.example.com` DNS record.
The `etherpad.<your-domain>` subdomain may be necessary, because this playbook could install the [Etherpad](https://etherpad.org/) a highly customizable open source online editor providing collaborative editing in really real-time. The installation of Etherpad is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Etherpad guide](configuring-playbook-etherpad.md). If you do not wish to set up Etherpad, feel free to skip the `etherpad.<your-domain>` DNS record.
The `etherpad.example.com` subdomain may be necessary, because this playbook could install the [Etherpad](https://etherpad.org/) a highly customizable open source online editor providing collaborative editing in really real-time. The installation of Etherpad is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Etherpad guide](configuring-playbook-etherpad.md). If you do not wish to set up Etherpad, feel free to skip the `etherpad.example.com` DNS record.
The `hydrogen.<your-domain>` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/element-hq/hydrogen-web) web client. The installation of Hydrogen is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Hydrogen guide](configuring-playbook-client-hydrogen.md). If you do not wish to set up Hydrogen, feel free to skip the `hydrogen.<your-domain>` DNS record.
The `hydrogen.example.com` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/element-hq/hydrogen-web) web client. The installation of Hydrogen is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Hydrogen guide](configuring-playbook-client-hydrogen.md). If you do not wish to set up Hydrogen, feel free to skip the `hydrogen.example.com` DNS record.
The `cinny.<your-domain>` subdomain may be necessary, because this playbook could install the [Cinny](https://github.com/ajbura/cinny) web client. The installation of Cinny is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Cinny guide](configuring-playbook-client-cinny.md). If you do not wish to set up Cinny, feel free to skip the `cinny.<your-domain>` DNS record.
The `cinny.example.com` subdomain may be necessary, because this playbook could install the [Cinny](https://github.com/ajbura/cinny) web client. The installation of Cinny is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Cinny guide](configuring-playbook-client-cinny.md). If you do not wish to set up Cinny, feel free to skip the `cinny.example.com` DNS record.
The `wsproxy.<your-domain>` subdomain may be necessary, because this playbook could install the [wsproxy](https://github.com/mautrix/wsproxy) web client. The installation of wsproxy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring wsproxy guide](configuring-playbook-bridge-mautrix-wsproxy.md). If you do not wish to set up wsproxy, feel free to skip the `wsproxy.<your-domain>` DNS record.
The `wsproxy.example.com` subdomain may be necessary, because this playbook could install the [wsproxy](https://github.com/mautrix/wsproxy) web client. The installation of wsproxy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring wsproxy guide](configuring-playbook-bridge-mautrix-wsproxy.md). If you do not wish to set up wsproxy, feel free to skip the `wsproxy.example.com` DNS record.
The `buscarron.<your-domain>` subdomain may be necessary, because this playbook could install the [buscarron](https://github.com/etkecc/buscarron) bot. The installation of buscarron is disabled by default, it is not a core required component. To learn how to install it, see our [configuring buscarron guide](configuring-playbook-bot-buscarron.md). If you do not wish to set up buscarron, feel free to skip the `buscarron.<your-domain>` DNS record.
The `buscarron.example.com` subdomain may be necessary, because this playbook could install the [buscarron](https://github.com/etkecc/buscarron) bot. The installation of buscarron is disabled by default, it is not a core required component. To learn how to install it, see our [configuring buscarron guide](configuring-playbook-bot-buscarron.md). If you do not wish to set up buscarron, feel free to skip the `buscarron.example.com` DNS record.
## `_matrix-identity._tcp` SRV record setup
To make the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server (which this playbook may optionally install for you) enable its federation features, set up an SRV record that looks like this:
- Name: `_matrix-identity._tcp` (use this text as-is)
- Content: `10 0 443 matrix.<your-domain>` (replace `<your-domain>` with your own)
- Content: `10 0 443 matrix.example.com` (replace `example.com` with your own)
This is an optional feature for the optionally-installed [ma1sd service](configuring-playbook-ma1sd.md). See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.

8
docs/configuring-playbook-alertmanager-receiver.md
View File

@ -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.

2
docs/configuring-playbook-appservice-double-puppet.md
View File

@ -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

10
docs/configuring-playbook-appservice-draupnir-for-all.md
View File

@ -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.
@ -59,7 +59,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
## Usage
If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:matrix-homeserver-domain` you have succesfully installed Draupnir for All and can now start using it.
If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com` you have succesfully installed Draupnir for All and can now start using it.
The installation of Draupnir for all in this playbook is very much Alpha quality. Usage-wise, Draupnir for allis almost identical to Draupnir bot mode.
@ -69,11 +69,11 @@ Draupnir for all includes several security measures like that it only allows use
The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297))
To allow users or whole homeservers you type /plain @draupnir-main:matrix-homeserver-domain allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
To allow users or whole homeservers you type /plain @draupnir-main:example.com allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
### 2. How to provision a D4A once you are allowed to.
Open a DM with @draupnir-main:matrix-homeserver-domain and if using Element send a message into this DM to finalise creating it. The bot will reject this invite and you will shortly get invited to the Draupnir control room for your newly provisioned Draupnir. From here its just a normal Draupnir experience.
Open a DM with @draupnir-main:example.com and if using Element send a message into this DM to finalise creating it. The bot will reject this invite and you will shortly get invited to the Draupnir control room for your newly provisioned Draupnir. From here its just a normal Draupnir experience.
Congratulations if you made it all the way here because you now have a fully working Draupnir for all deployment.
@ -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.

2
docs/configuring-playbook-backup-borg.md
View File

@ -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

12
docs/configuring-playbook-base-domain-serving.md
View File

@ -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:

12
docs/configuring-playbook-bot-baibot.md
View File

@ -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,18 +82,18 @@ 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:
#
# matrix_bot_baibot_config_access_admin_patterns:
# - "@*:example.com"
# - "@admin:another.com"
# - "@admin:example.net"
#
# .. unless you've made yourself an admin of all bots/bridges like this:
#
# matrix_admin: '@yourAdminAccount:domain.com'
# matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
```
### 👥 Initial users configuration
@ -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.

16
docs/configuring-playbook-bot-buscarron.md
View File

@ -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
room: "!yourRoomID:DOMAIN" # (mandatory) Room ID where form submission will be posted
redirect: https://DOMAIN # (mandatory) To what page user will be redirected after the form submission
- 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://example.com # (mandatory) To what page user will be redirected after the form submission
ratelimit: 1r/m # (optional) rate limit of the form, format: <max requests>r/<interval:s,m>, eg: 1r/s or 54r/m
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
<form method="POST" action="https://buscarron.DOMAIN/contact">
<form method="POST" action="https://buscarron.example.com/contact">
<!--your fields-->
</form>
```

4
docs/configuring-playbook-bot-chatgpt.md
View File

@ -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).

16
docs/configuring-playbook-bot-draupnir.md
View File

@ -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.

10
docs/configuring-playbook-bot-go-neb.md
View File

@ -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
@ -207,7 +207,7 @@ matrix_bot_go_neb_services:
webhook_url: "http://localhost/services/hooks/YWxlcnRtYW5hZ2VyX3NlcnZpY2U"
# Each room will get the notification with the alert rendered with the given template
rooms:
"!someroomid:domain.tld":
"!someroomid:example.com":
text_template: "{% raw %}{{range .Alerts -}} [{{ .Status }}] {{index .Labels \"alertname\" }}: {{index .Annotations \"description\"}} {{ end -}}{% endraw %}"
html_template: "{% raw %}{{range .Alerts -}} {{ $severity := index .Labels \"severity\" }} {{ if eq .Status \"firing\" }} {{ if eq $severity \"critical\"}} <font color='red'><b>[FIRING - CRITICAL]</b></font> {{ else if eq $severity \"warning\"}} <font color='orange'><b>[FIRING - WARNING]</b></font> {{ else }} <b>[FIRING - {{ $severity }}]</b> {{ end }} {{ else }} <font color='green'><b>[RESOLVED]</b></font> {{ end }} {{ index .Labels \"alertname\"}} : {{ index .Annotations \"description\"}} <a href=\"{{ .GeneratorURL }}\">source</a><br/>{{end -}}{% endraw %}"
msg_type: "m.text" # Must be either `m.text` or `m.notice`
@ -225,7 +225,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
## Usage
To use the bot, invite it to any existing Matrix room (`/invite @whatever_you_chose:DOMAIN` where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain, make sure you have permission from the room owner if that's not you).
To use the bot, invite it to any existing Matrix room (`/invite @whatever_you_chose:example.com` where `example.com` is your base domain, not the `matrix.` domain, make sure you have permission from the room owner if that's not you).
Basic usage is like this: `!echo hi` or `!imgur puppies` or `!giphy matrix`

6
docs/configuring-playbook-bot-honoroit.md
View File

@ -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
@ -25,7 +25,7 @@ matrix_bot_honoroit_enabled: true
matrix_bot_honoroit_password: PASSWORD_FOR_THE_BOT
# Adjust this to your room ID
matrix_bot_honoroit_roomid: "!yourRoomID:DOMAIN"
matrix_bot_honoroit_roomid: "!yourRoomID:{{ matrix_domain }}"
```
@ -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.

6
docs/configuring-playbook-bot-matrix-registration-bot.md
View File

@ -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.

6
docs/configuring-playbook-bot-matrix-reminder-bot.md
View File

@ -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 `YOUR_DOMAIN` 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`

6
docs/configuring-playbook-bot-maubot.md
View File

@ -3,14 +3,14 @@
The playbook can install and configure [maubot](https://github.com/maubot/maubot) for you.
After setting up maubot, you can use the web management interface to make it do things.
The default location of the management interface is `matrix.<your-domain>/_matrix/maubot/`
The default location of the management interface is `matrix.example.com/_matrix/maubot/`
See the project's [documentation](https://docs.mau.fi/maubot/usage/basic.html) to learn what it
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
@ -38,7 +38,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
You can visit `matrix.<your-domain>/_matrix/maubot/` to manage your available plugins, clients and instances.
You can visit `matrix.example.com/_matrix/maubot/` to manage your available plugins, clients and instances.
You should start in the following order
1. **Create one or more clients**: A client is a matrix account which the bot will use to message. By default, the playbook creates a `bot.maubot` account (as per the configuration above). You only need to [obtain an access token](#obtaining-an-access-token) for it

12
docs/configuring-playbook-bot-mjolnir.md
View File

@ -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.

10
docs/configuring-playbook-bot-postmoogle.md
View File

@ -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
@ -39,11 +39,11 @@ matrix_bot_postmoogle_password: PASSWORD_FOR_THE_BOT
# Uncomment to add one or more admins to this bridge:
#
# matrix_bot_postmoogle_admins:
# - '@yourAdminAccount:domain.com'
# - '@yourAdminAccount:{{ matrix_domain }}'
#
# .. unless you've made yourself an admin of all bots/bridges like this:
#
# matrix_admin: '@yourAdminAccount:domain.com'
# matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
```
### DNS
@ -69,9 +69,9 @@ 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.
Then send `!pm mailbox NAME` to expose this Matrix room as an inbox with the email address `NAME@matrix.example.com`. Emails sent to that email address will be forwarded to the room.
Send `!pm help` to the room to see the bot's help menu for additional commands.

2
docs/configuring-playbook-bridge-appservice-discord.md
View File

@ -46,7 +46,7 @@ matrix_appservice_discord_bridge_enableSelfServiceBridging: true
Once self-service is enabled:
1. Start a chat with `@_discord_bot:<YOUR_DOMAIN>` and say `!discord help bridge`.
1. Start a chat with `@_discord_bot:example.com` and say `!discord help bridge`.
2. Follow the instructions in the help output message. If the bot is not already in the Discord server, follow the provided invite link. This may require you to be a administrator of the Discord server.
**Note**: Encrypted Matrix rooms are not supported as of writing.

4
docs/configuring-playbook-bridge-appservice-irc.md
View File

@ -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
@ -66,4 +66,4 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
You then need to start a chat with `@irc_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@irc_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

4
docs/configuring-playbook-bridge-appservice-kakaotalk.md
View File

@ -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
@ -63,7 +63,7 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
Start a chat with `@kakaotalkbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.

8
docs/configuring-playbook-bridge-appservice-slack.md
View File

@ -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: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: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/<the channel ID>/details/`.

6
docs/configuring-playbook-bridge-appservice-webhooks.md
View File

@ -10,7 +10,7 @@ Setup Instructions:
loosely based on [this](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md)
1. All you basically need is to adjust your `inventory/host_vars/matrix.<domain-name>/vars.yml`:
1. All you basically need is to adjust your `inventory/host_vars/matrix.example.com/vars.yml`:
```yaml
matrix_appservice_webhooks_enabled: true
@ -18,7 +18,7 @@ matrix_appservice_webhooks_api_secret: '<your_secret>'
```
2. In case you want to change the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
you can adjust this in `inventory/host_vars/matrix.<domain-name>/vars.yml` as well.
you can adjust this in `inventory/host_vars/matrix.example.com/vars.yml` as well.
**Note**: default value is: `info` and availabe log levels are : `info`, `verbose`
@ -39,7 +39,7 @@ matrix_synapse_configuration_extension_yaml: |
6. Invite the bridge bot user to your room:
- either with `/invite @_webhook:<domain.name>` (**Note**: Make sure you have administration permissions in your room)
- either with `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
- or simply add the bridge bot to a private channel (personal channels imply you being an administrator)

6
docs/configuring-playbook-bridge-beeper-linkedin.md
View File

@ -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
@ -28,7 +28,7 @@ If you would like to be able to administrate the bridge from your account it can
matrix_beeper_linkedin_configuration_extension_yaml: |
bridge:
permissions:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
'@YOUR_USERNAME:example.com': admin
```
You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
@ -48,7 +48,7 @@ Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playb
## Usage
You then need to start a chat with `@linkedinbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account.

4
docs/configuring-playbook-bridge-go-skype-bridge.md
View File

@ -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
@ -20,7 +20,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
Once the bot is enabled, you need to start a chat with `Skype bridge bot`
with the handle `@skypebridgebot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
with the handle `@skypebridgebot:example.com` (where `example.com` is your base
domain, not the `matrix.` domain).
Send `help` to the bot to see the commands available.

4
docs/configuring-playbook-bridge-heisenbridge.md
View File

@ -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.

4
docs/configuring-playbook-bridge-hookshot.md
View File

@ -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`

2
docs/configuring-playbook-bridge-matrix-bridge-sms.md
View File

@ -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

4
docs/configuring-playbook-bridge-mautrix-discord.md
View File

@ -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
@ -87,7 +87,7 @@ To acquire the token, open Discord in a private browser window. Then open the de
### Bridging
1. Start a chat with `@discordbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
1. Start a chat with `@discordbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
2. If you would like to login to Discord using a token, send `login-token` command, otherwise, send `login-qr` command.
3. You'll see a QR code which you need to scan with the Discord app on your phone. You can scan it with the camera app too, which will open Discord, which will then instruct you to scan it a 2nd time in the Discord app.
4. After confirming (in the Discord app) that you'd like to allow this login, the bot should respond with "Succcessfully authenticated as ..."

6
docs/configuring-playbook-bridge-mautrix-facebook.md
View File

@ -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
@ -76,7 +76,7 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
You then need to start a chat with `@facebookbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/facebook/authentication.html).
@ -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/).

4
docs/configuring-playbook-bridge-mautrix-gmessages.md
View File

@ -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
@ -41,4 +41,4 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
You then need to start a chat with `@gmessagesbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@gmessagesbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

4
docs/configuring-playbook-bridge-mautrix-googlechat.md
View File

@ -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
@ -44,7 +44,7 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
Once the bot is enabled you need to start a chat with `googlechat bridge bot` with handle `@googlechatbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Once the bot is enabled you need to start a chat with `googlechat bridge bot` with handle `@googlechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions.

4
docs/configuring-playbook-bridge-mautrix-hangouts.md
View File

@ -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
@ -44,7 +44,7 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
Once the bot is enabled you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Once the bot is enabled you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions.

6
docs/configuring-playbook-bridge-mautrix-instagram.md
View File

@ -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
@ -35,7 +35,7 @@ matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
matrix_mautrix_instagram_configuration_extension_yaml: |
bridge:
permissions:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
'@YOUR_USERNAME:example.com': admin
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure.
@ -46,7 +46,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
You then need to start a chat with `@instagrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account.

14
docs/configuring-playbook-bridge-mautrix-meta-instagram.md
View File

@ -11,10 +11,10 @@ This documentation page only deals with the bridge's ability to bridge to Instag
If you've been using the [mautrix-instagram](./configuring-playbook-bridge-mautrix-instagram.md) bridge, **you'd better get rid of it first** or the 2 bridges will be in conflict:
- both trying to use `@instagrambot:YOUR_DOMAIN` as their username. This conflict may be resolved by adjusting `matrix_mautrix_instagram_appservice_bot_username` or `matrix_mautrix_meta_instagram_appservice_username`
- both trying to use `@instagrambot:example.com` as their username. This conflict may be resolved by adjusting `matrix_mautrix_instagram_appservice_bot_username` or `matrix_mautrix_meta_instagram_appservice_username`
- both trying to bridge the same DMs
To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@instagrambot:YOUR_DOMAIN`).
To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@instagrambot:example.com`).
This would give you a list of portals and groups of portals you may purge. Proceed with sending commands like `clean recommended`, etc.
@ -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
@ -47,17 +47,17 @@ The default permissions are set via `matrix_mautrix_meta_instagram_bridge_permis
```yaml
matrix_mautrix_meta_instagram_bridge_permissions_default:
'*': relay
YOUR_DOMAIN: user
example.com: user
'{{ matrix_admin }}': admin
```
If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:YOUR_DOMAIN`), then there's no admin by default.
If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:example.com`), then there's no admin by default.
You may redefine `matrix_mautrix_meta_instagram_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_instagram_bridge_permissions_custom` like this:
```yaml
matrix_mautrix_meta_instagram_bridge_permissions_custom:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
'@YOUR_USERNAME:example.com': admin
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
@ -91,4 +91,4 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
You then need to start a chat with `@instagrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

12
docs/configuring-playbook-bridge-mautrix-meta-messenger.md
View File

@ -11,7 +11,7 @@ This documentation page only deals with the bridge's ability to bridge to Facebo
If you've been using the [mautrix-facebook](./configuring-playbook-bridge-mautrix-facebook.md) bridge, it's possible to migrate the database using [instructions from the bridge documentation](https://docs.mau.fi/bridges/go/meta/facebook-migration.html) (advanced).
Then you may wish to get rid of the Facebook bridge. To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@facebookbot:YOUR_DOMAIN`).
Then you may wish to get rid of the Facebook bridge. To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@facebookbot:example.com`).
This would give you a list of portals and groups of portals you may purge. Proceed with sending commands like `clean recommended`, etc.
@ -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
@ -57,17 +57,17 @@ The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permis
```yaml
matrix_mautrix_meta_messenger_bridge_permissions_default:
'*': relay
YOUR_DOMAIN: user
example.com: user
'{{ matrix_admin }}': admin
```
If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:YOUR_DOMAIN`), then there's no admin by default.
If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:example.com`), then there's no admin by default.
You may redefine `matrix_mautrix_meta_messenger_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_messenger_bridge_permissions_custom` like this:
```yaml
matrix_mautrix_meta_messenger_bridge_permissions_custom:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
'@YOUR_USERNAME:example.com': admin
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
@ -101,7 +101,7 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
You then need to start a chat with `@messengerbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@messengerbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
You then need to send a `login` command and follow the bridge bot's instructions.

12
docs/configuring-playbook-bridge-mautrix-signal.md
View File

@ -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
@ -32,7 +32,7 @@ The default permissions are set as follows:
```yaml
permissions:
'*': relay
YOUR_DOMAIN: user
example.com: user
```
If you want to augment the preset permissions, you might want to set the additional permissions with the following settings in your `vars.yml` file:
@ -40,7 +40,7 @@ If you want to augment the preset permissions, you might want to set the additio
matrix_mautrix_signal_configuration_extension_yaml: |
bridge:
permissions:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
'@YOUR_USERNAME:example.com': admin
```
This will add the admin permission to the specific user, while keeping the default permissions.
@ -48,8 +48,8 @@ This will add the admin permission to the specific user, while keeping the defau
In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file:
```yaml
matrix_mautrix_signal_bridge_permissions:
'@ADMIN:YOUR_DOMAIN': admin
'@USER:YOUR_DOMAIN' : user
'@ADMIN:example.com': admin
'@USER:example.com' : user
```
You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
@ -83,4 +83,4 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
You then need to start a chat with `@signalbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@signalbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

4
docs/configuring-playbook-bridge-mautrix-slack.md
View File

@ -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
@ -74,7 +74,7 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
1. Start a chat with `@slackbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
1. Start a chat with `@slackbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
2. If you would like to login to Slack using a token, send the `login-token` command, otherwise, send the `login-password` command. Read [here](https://docs.mau.fi/bridges/go/slack/authentication.html) on how to retrieve your token and cookie token.
3. The bot should respond with "Successfully logged into <email> for team <workspace>"
4. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to.

8
docs/configuring-playbook-bridge-mautrix-telegram.md
View File

@ -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
@ -45,9 +45,9 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
You then need to start a chat with `@telegrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
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:

4
docs/configuring-playbook-bridge-mautrix-twitter.md
View File

@ -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
@ -36,7 +36,7 @@ This method is currently not available for the Mautrix-Twitter bridge, but is on
## Usage
1. You then need to start a chat with `@twitterbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
1. You then need to start a chat with `@twitterbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
2. Send login-cookie to start the login. The bot should respond with instructions on how to proceed.
You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/twitter/authentication.html).

4
docs/configuring-playbook-bridge-mautrix-whatsapp.md
View File

@ -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
@ -58,4 +58,4 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
## Usage
You then need to start a chat with `@whatsappbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@whatsappbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

4
docs/configuring-playbook-bridge-mautrix-wsproxy.md
View File

@ -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

4
docs/configuring-playbook-bridge-mx-puppet-discord.md
View File

@ -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
@ -26,7 +26,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
Once the bot is enabled you need to start a chat with `Discord Puppet Bridge` with
the handle `@_discordpuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
the handle `@_discordpuppet_bot:example.com` (where `example.com` is your base
domain, not the `matrix.` domain).
Three authentication methods are available, Legacy Token, OAuth and xoxc token.

4
docs/configuring-playbook-bridge-mx-puppet-groupme.md
View File

@ -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
@ -20,7 +20,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
Once the bot is enabled you need to start a chat with `GroupMe Puppet Bridge` with
the handle `@_groupmepuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
the handle `@_groupmepuppet_bot:example.com` (where `example.com` is your base
domain, not the `matrix.` domain).
One authentication method is available.

4
docs/configuring-playbook-bridge-mx-puppet-instagram.md
View File

@ -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
@ -20,7 +20,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
Once the bot is enabled, you need to start a chat with `Instagram Puppet Bridge` with
the handle `@_instagrampuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
the handle `@_instagrampuppet_bot:example.com` (where `example.com` is your base
domain, not the `matrix.` domain).
Send `link <username> <password>` to the bridge bot to link your instagram account.

6
docs/configuring-playbook-bridge-mx-puppet-slack.md
View File

@ -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
@ -34,7 +34,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
## Usage
Once the bot is enabled you need to start a chat with `Slack Puppet Bridge` with
the handle `@_slackpuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
the handle `@_slackpuppet_bot:example.com` (where `example.com` is your base
domain, not the `matrix.` domain).
Three authentication methods are available, Legacy Token, OAuth and xoxc token.

4
docs/configuring-playbook-bridge-mx-puppet-steam.md
View File

@ -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
@ -20,7 +20,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
Once the bot is enabled you need to start a chat with `Steam Puppet Bridge` with
the handle `@_steampuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
the handle `@_steampuppet_bot:example.com` (where `example.com` is your base
domain, not the `matrix.` domain).
Three authentication methods are available, Legacy Token, OAuth and xoxc token.

4
docs/configuring-playbook-bridge-mx-puppet-twitter.md
View File

@ -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
@ -31,7 +31,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
Once the bot is enabled you need to start a chat with `Twitter Puppet Bridge` with
the handle `@_twitterpuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
the handle `@_twitterpuppet_bot:example.com` (where `example.com` is your base
domain, not the `matrix.` domain).
To log in, use `link` and click the link.

4
docs/configuring-playbook-bridge-wechat.md
View File

@ -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
@ -18,6 +18,6 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
Once the bridge is installed, start a chat with `@wechatbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Once the bridge is installed, start a chat with `@wechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `help` to the bot to see the available commands.

4
docs/configuring-playbook-cactus-comments.md
View File

@ -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
@ -52,7 +52,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
Upon starting Cactus Comments, a `bot.cactusbot` user account is created automatically.
To get started, send a `help` message to the `@bot.cactusbot:your-homeserver.com` bot to confirm it's working.
To get started, send a `help` message to the `@bot.cactusbot:example.com` bot to confirm it's working.
Then, register a site by typing: `register <sitename>`. You will then be invited into a moderation room.

8
docs/configuring-playbook-client-cinny.md
View File

@ -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

4
docs/configuring-playbook-client-element.md
View File

@ -5,7 +5,7 @@ By default, this playbook installs the [Element](https://github.com/element-hq/e
## Disabling Element
If you'd like for the playbook to not install Element (or to uninstall it if it was previously installed), you can disable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
If you'd like for the playbook to not install Element (or to uninstall it if it was previously installed), you can disable it in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_client_element_enabled: false
@ -18,7 +18,7 @@ The playbook provides some customization variables you could use to change Eleme
Their defaults are defined in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-element/templates/config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for an Element setting you wish to change:

8
docs/configuring-playbook-client-hydrogen.md
View File

@ -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

10
docs/configuring-playbook-client-schildichat.md
View File

@ -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
@ -30,7 +30,7 @@ The playbook provides some customization variables you could use to change Schil
Their defaults are defined in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml) and they ultimately end up in the generated `/matrix/schildichat/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-schildichat/templates/config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for a SchildiChat setting you wish to change:

2
docs/configuring-playbook-conduit.md
View File

@ -36,7 +36,7 @@ You will have to manually register appservices using the the [register-appservic
Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`, then pass the content to Conduit:
@conduit:your.server.name: register-appservice
@conduit:example.com: register-appservice
```
as_token: <token>
de.sorunome.msc2409.push_ephemeral: true

2
docs/configuring-playbook-dendrite.md
View File

@ -10,7 +10,7 @@ By default, this playbook configures the [Synapse](https://github.com/element-hq
The playbook provided settings for Dendrite are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for a Dendrite setting you wish to change:

8
docs/configuring-playbook-dimension.md
View File

@ -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:
@ -30,7 +30,7 @@ Once you've decided on the domain and path, **you may need to adjust your DNS**
## Enable
To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_dimension_enabled: true
@ -40,7 +40,7 @@ matrix_dimension_enabled: true
## Define admin users
These users can modify the integrations this Dimension supports.
Add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
Add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_dimension_admins:
@ -60,7 +60,7 @@ To get an access token for the Dimension user, you can follow the documentation
**Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
Add access token to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
Add access token to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_dimension_access_token: "YOUR ACCESS TOKEN HERE"

2
docs/configuring-playbook-dynamic-dns.md
View File

@ -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

4
docs/configuring-playbook-email.md
View File

@ -5,7 +5,7 @@ By default, this playbook sets up an [Exim](https://www.exim.org/) email server
The email server would attempt to deliver emails directly to their final destination.
This may or may not work, depending on your domain configuration (SPF settings, etc.)
By default, emails are sent from `matrix@<your-domain-name>` (as specified by the `exim_relay_sender_address` playbook variable).
By default, emails are sent from `matrix@matrix.example.com`, as specified by the `exim_relay_sender_address` playbook variable.
**Note**: If you are using a Google Cloud instance, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so you need to relay email through another SMTP server as described below.
@ -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"

6
docs/configuring-playbook-email2matrix.md
View File

@ -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.

16
docs/configuring-playbook-etherpad.md
View File

@ -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
@ -46,23 +46,23 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
The Etherpad UI should be available at `https://etherpad.<your-domain>`, while the admin UI (if enabled) should then be available at `https://etherpad.<your-domain>/admin`.
The Etherpad UI should be available at `https://etherpad.example.com`, while the admin UI (if enabled) should then be available at `https://etherpad.example.com/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
If you want to manage and remove old unused pads from Etherpad, you will first need to able Admin access as described above.
Then from the plugin manager page (`https://etherpad.<your-domain>/admin/plugins`, install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
Then from the plugin manager page (`https://etherpad.example.com/admin/plugins`, install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
### How to use Etherpad widgets without an Integration Manager (like Dimension)
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)
@ -76,7 +76,7 @@ The Dimension configuration menu can be accessed with the sprocket icon as you b
If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
Example: `https://etherpad.<your-domain>/p/$roomId_$padName?showChat=false`
Example: `https://etherpad.example.com/p/$roomId_$padName?showChat=false`
## Known issues

2
docs/configuring-playbook-external-postgres.md
View File

@ -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

10
docs/configuring-playbook-federation.md
View File

@ -6,12 +6,12 @@ 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:
- example.com
- another.com
- example.net
```
If you wish to disable federation, you can do that with an empty list (`[]`), or better yet by completely disabling federation (see below).
@ -21,7 +21,7 @@ If you wish to disable federation, you can do that with an empty list (`[]`), or
By default, your server's public rooms directory is not exposed to other servers via federation.
If you wish to expose it, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
If you wish to expose it, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_synapse_allow_public_rooms_over_federation: true
@ -30,7 +30,7 @@ matrix_synapse_allow_public_rooms_over_federation: true
## Disabling federation
To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_homeserver_federation_enabled: false
@ -55,7 +55,7 @@ matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
Why? This change could be useful for people running small Synapse instances on small severs/VPSes to avoid being impacted by a simple DOS/DDOS when bandwidth, RAM, an CPU resources are limited and if your hosting provider does not provide a DOS/DDOS protection.
The following changes in the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other:
The following changes in the configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other:
```
matrix_synapse_http_listener_resource_names: ["client","federation"]

20
docs/configuring-playbook-jitsi.md
View File

@ -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).

6
docs/configuring-playbook-ldap-auth.md
View File

@ -4,13 +4,13 @@ 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
matrix_synapse_ext_password_provider_ldap_uri:
- "ldap://ldap-01.mydomain.tld:389"
- "ldap://ldap-02.mydomain.tld:389"
- "ldap://ldap-01.example.com:389"
- "ldap://ldap-02.example.com:389"
matrix_synapse_ext_password_provider_ldap_start_tls: true
matrix_synapse_ext_password_provider_ldap_base: "ou=users,dc=example,dc=com"
matrix_synapse_ext_password_provider_ldap_attributes_uid: "uid"

6
docs/configuring-playbook-ma1sd.md
View File

@ -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

2
docs/configuring-playbook-matrix-corporal.md
View File

@ -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.

2
docs/configuring-playbook-matrix-ldap-registration-proxy.md
View File

@ -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

4
docs/configuring-playbook-matrix-media-repo.md
View File

@ -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.

6
docs/configuring-playbook-matrix-registration.md
View File

@ -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`.

10
docs/configuring-playbook-mautrix-bridges.md
View File

@ -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**:
@ -121,7 +121,7 @@ If you have issues with a service, and are requesting support, the higher levels
## Usage
You then need to start a chat with `@SERVICENAMEbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login ` to the bridge bot to get started You can learn more here about authentication from the bridge's official documentation on Authentication https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html .

6
docs/configuring-playbook-ntfy.md
View File

@ -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
@ -35,7 +35,7 @@ For a complete list of ntfy config options that you could put in `ntfy_configura
## Installing
Don't forget to add `ntfy.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
Don't forget to add `ntfy.example.com` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
After configuring the playbook, run the [installation](installing.md) command:
@ -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.

4
docs/configuring-playbook-own-webserver.md
View File

@ -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

2
docs/configuring-playbook-pantalaimon.md
View File

@ -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

2
docs/configuring-playbook-postgres-backup.md
View File

@ -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

30
docs/configuring-playbook-prometheus-grafana.md
View File

@ -2,9 +2,9 @@
It can be useful to have some (visual) insight into the performance of your homeserver.
You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
Remember to add `stats.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
Remember to add `stats.example.com` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
```yaml
prometheus_enabled: true
@ -30,7 +30,7 @@ grafana_default_admin_user: "some_username_chosen_by_you"
grafana_default_admin_password: "some_strong_password_chosen_by_you"
```
By default, a [Grafana](https://grafana.com/) web user-interface will be available at `https://stats.<your-domain>`.
By default, a [Grafana](https://grafana.com/) web user-interface will be available at `https://stats.example.com`.
The retention policy of Prometheus metrics is [15 days by default](https://prometheus.io/docs/prometheus/latest/storage/#operational-aspects). Older data gets deleted automatically.
@ -43,7 +43,7 @@ Name | Description
`prometheus_node_exporter_enabled`|[Node Exporter](https://prometheus.io/docs/guides/node-exporter/) is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
`prometheus_postgres_exporter_enabled`|[Postgres Exporter](configuring-playbook-prometheus-postgres.md) is an addon of sorts to expose Postgres database metrics to Prometheus.
`matrix_prometheus_nginxlog_exporter_enabled`|[NGINX Log Exporter](configuring-playbook-prometheus-nginxlog.md) is an addon of sorts to expose NGINX logs to Prometheus.
`grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
`grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.example.com` subdomain) the dashboards with the graphs that we're interested in
`grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
`grafana_default_admin_user`<br>`grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
@ -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

4
docs/configuring-playbook-prometheus-nginxlog.md
View File

@ -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`).

4
docs/configuring-playbook-prometheus-postgres.md
View File

@ -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

6
docs/configuring-playbook-rageshake.md
View File

@ -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

2
docs/configuring-playbook-rest-auth.md
View File

@ -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

8
docs/configuring-playbook-riot-web.md
View File

@ -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

2
docs/configuring-playbook-s3-goofys.md
View File

@ -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

4
docs/configuring-playbook-s3.md
View File

@ -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-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-media-store`)
- give it *Read & Write* access
The `keyID` value is your **Access Key** and `applicationKey` is your **Secret Key**.

2
docs/configuring-playbook-shared-secret-auth.md
View File

@ -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

6
docs/configuring-playbook-sliding-sync-proxy.md
View File

@ -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.

6
docs/configuring-playbook-ssl-certificates.md
View File

@ -1,6 +1,6 @@
# Adjusting SSL certificate retrieval (optional, advanced)
By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (e.g. `matrix.<your-domain>` and others)
By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (e.g. `matrix.example.com` and others)
This guide is about using the integrated Traefik server and doesn't apply if you're using [your own webserver](configuring-playbook-own-webserver.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

8
docs/configuring-playbook-sygnal.md
View File

@ -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.

4
docs/configuring-playbook-synapse-admin.md
View File

@ -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.

2
docs/configuring-playbook-synapse-auto-accept-invite.md
View File

@ -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

2
docs/configuring-playbook-synapse-auto-compressor.md
View File

@ -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

2
docs/configuring-playbook-synapse-s3-storage-provider.md
View File

@ -26,7 +26,7 @@ While you will need some local disk space around, it's only to accommodate usage
## Installing
After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure `s3-storage-provider` in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure `s3-storage-provider` in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
```yaml
matrix_synapse_ext_synapse_s3_storage_provider_enabled: true

4
docs/configuring-playbook-synapse-simple-antispam.md
View File

@ -7,12 +7,12 @@ 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
matrix_synapse_ext_spam_checker_synapse_simple_antispam_config_blocked_homeservers:
- example.com
- another.com
- example.net
```

4
docs/configuring-playbook-synapse-usage-exporter.md
View File

@ -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

6
docs/configuring-playbook-synapse.md
View File

@ -6,7 +6,7 @@ The playbook provides lots of customization variables you could use to change Sy
Their defaults are defined in [`roles/custom/matrix-synapse/defaults/main.yml`](../roles/custom/matrix-synapse/defaults/main.yml) and they ultimately end up in the generated `/matrix/synapse/config/homeserver.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2`](../roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for a Synapse setting you wish to change:
@ -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.

2
docs/configuring-playbook-telemetry.md
View File

@ -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

10
docs/configuring-playbook-traefik.md
View File

@ -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
@ -57,9 +57,9 @@ However, if your service does not run on a container or runs on another machine,
## Reverse-proxying a remote HTTP/HTTPS service behind Traefik
If you want to host another webserver would be reachable via `my-fancy-website.mydomain.com` from the internet and via `https://<internal webserver IP address>:<internal port>` from inside your network, you can make the playbook's integrated Traefik instance reverse-proxy the traffic to the correct host.
If you want to host another webserver would be reachable via `my-fancy-website.example.net` from the internet and via `https://<internal webserver IP address>:<internal port>` from inside your network, you can make the playbook's integrated Traefik instance reverse-proxy the traffic to the correct host.
Prerequisites: DNS and routing for the domain `my-fancy-website.mydomain.com` need to be set up correctly. In this case, you'd be pointing the domain name to your Matrix server - `my-fancy-website.mydomain.com` would be a CNAME going to `matrix.example.com`.
Prerequisites: DNS and routing for the domain `my-fancy-website.example.net` need to be set up correctly. In this case, you'd be pointing the domain name to your Matrix server - `my-fancy-website.example.net` would be a CNAME going to `matrix.example.com`.
First, we have to adjust the static configuration of Traefik, so that we can add additional configuration files:
@ -99,7 +99,7 @@ aux_file_definitions:
http:
routers:
webserver-router:
rule: Host(`my_fancy_website.mydomain.com`)
rule: Host(`my-fancy-website.example.net`)
service: webserver-service
tls:
certResolver: default
@ -122,7 +122,7 @@ aux_file_definitions:
tcp:
routers:
webserver-router:
rule: Host(`my_fancy_website.mydomain.com`)
rule: Host(`my-fancy-website.example.net`)
service: webserver-service
tls:
passthrough: true

2
docs/configuring-playbook-turn.md
View File

@ -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

2
docs/configuring-playbook-user-verification-service.md
View File

@ -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

Some files were not shown because too many files have changed in this diff Show More