Merge pull request #4050 from luixxiul/fix
Create instruction sections for Hookshot and matrix-media-repo on each document
This commit is contained in:
Slavi Pantaleev
GitHub
commit
f41337708b
@ -96,7 +96,6 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
|
||||
| provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) |
|
||||
| appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
|
||||
| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
|
||||
| metrics | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and exposure enabled via `matrix_hookshot_metrics_proxying_enabled` or `matrix_metrics_exposure_enabled`. Read more in the [Metrics section](#metrics) below. | Prometheus |
|
||||
|
||||
Also see the various `matrix_hookshot_container_labels_*` variables in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml), which expose URLs publicly.
|
||||
|
||||
@ -127,23 +126,46 @@ For more information, see the documentation in the [default configuration of the
|
||||
|
||||
The provisioning API will be enabled automatically if you set `matrix_dimension_enabled: true` and provided a `matrix_hookshot_provisioning_secret`, unless you override it either way. To use hookshot with Dimension, you will need to enter as "Provisioning URL": `http://matrix-hookshot:9002`, which is made up of the variables `matrix_hookshot_container_url` and `matrix_hookshot_provisioning_port`.
|
||||
|
||||
### Metrics
|
||||
|
||||
Metrics are **only enabled by default** if the builtin [Prometheus](configuring-playbook-prometheus-grafana.md) is enabled (by default, Prometheus isn't enabled). If so, metrics will automatically be collected by Prometheus and made available in Grafana. You will, however, need to set up your own Dashboard for displaying them.
|
||||
|
||||
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.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`
|
||||
|
||||
Whichever one you go with, by default metrics are exposed publicly **without** password-protection. See [the Prometheus and Grafana docs](configuring-playbook-prometheus-grafana.md) for details about password-protection for metrics.
|
||||
|
||||
### Collision with matrix-appservice-webhooks
|
||||
|
||||
If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_userIdPrefix: '_webhooks_'`).
|
||||
|
||||
### Enable metrics
|
||||
|
||||
The playbook can enable and configure the metrics of the service for you.
|
||||
|
||||
Metrics are **only enabled by default** if the builtin [Prometheus](configuring-playbook-prometheus-grafana.md) is enabled (by default, Prometheus isn't enabled). If so, metrics will automatically be collected by Prometheus and made available in Grafana. You will, however, need to set up your own Dashboard for displaying them.
|
||||
|
||||
To enable the metrics, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
# Expose metrics (locally, on the container network).
|
||||
matrix_hookshot_metrics_enabled: true
|
||||
```
|
||||
|
||||
**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 adding the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_hookshot_metrics_proxying_enabled: true
|
||||
```
|
||||
|
||||
By default metrics are exposed publicly **without** password-protection. To password-protect the metrics with dedicated credentials, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_hookshot_container_labels_metrics_middleware_basic_auth_enabled: true
|
||||
matrix_hookshot_container_labels_metrics_middleware_basic_auth_users: ''
|
||||
```
|
||||
|
||||
To `matrix_hookshot_container_labels_metrics_middleware_basic_auth_users`, set the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint. See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users for details about it.
|
||||
|
||||
**Note**: alternatively, you can use `matrix_metrics_exposure_enabled` to expose all services on this `/metrics/*` feature, and you can use `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` to password-protect the metrics of them. See [this section](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) for more information.
|
||||
|
||||
#### Enable Grafana (optional)
|
||||
|
||||
Probably you wish to enable Grafana along with Prometheus for generating graphs of the metics.
|
||||
|
||||
To enable Grafana, see [this section](configuring-playbook-prometheus-grafana.md#adjusting-the-playbook-configuration-grafana) for instructions.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-hookshot`.
|
||||
|
||||
@ -5,9 +5,8 @@ The playbook can install and configure [matrix-media-repo](https://docs.t2bot.io
|
||||
MMR is a highly customizable multi-domain media repository for Matrix. Intended for medium to large environments consisting of several homeservers, this media repo de-duplicates media (including remote media) while being fully compliant with the specification.
|
||||
|
||||
**Notes**:
|
||||
|
||||
- If MMR is enabled, other media store roles should be disabled (if using Synapse with other media store roles).
|
||||
- Smaller/individual homeservers can still make use of this project's features, though it may be difficult to set up or have higher than expected resource consumption. Please do your research before deploying this as this project may not be useful for your environment.
|
||||
|
||||
- For a simpler alternative (which allows you to offload your media repository storage to S3, etc.), you can [configure S3 storage](configuring-playbook-s3.md) instead of setting up matrix-media-repo.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
@ -16,15 +15,46 @@ To enable matrix-media-repo, add the following configuration to your `inventory/
|
||||
|
||||
```yaml
|
||||
matrix_media_repo_enabled: true
|
||||
|
||||
# (optional) Turned off by default
|
||||
# matrix_media_repo_metrics_enabled: true
|
||||
```
|
||||
|
||||
The repo is pre-configured for integrating with the Postgres database, Traefik proxy and [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) (if metrics enabled) from this playbook for all the available homeserver roles. When the media repo is enabled, other media store roles should be disabled (if using Synapse with other media store roles).
|
||||
|
||||
By default, the media-repo will use the local filesystem for data storage. You can alternatively use a `s3` cloud backend as well. Access token caching is also enabled by default since the logout endpoints are proxied through the media repo.
|
||||
|
||||
### Enable metrics
|
||||
|
||||
The playbook can enable and configure the metrics of the service for you.
|
||||
|
||||
Metrics are **only enabled by default** if the builtin [Prometheus](configuring-playbook-prometheus-grafana.md) is enabled (by default, Prometheus isn't enabled). If so, metrics will automatically be collected by Prometheus and made available in Grafana. You will, however, need to set up your own Dashboard for displaying them.
|
||||
|
||||
To enable the metrics, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
# Expose metrics (locally, on the container network).
|
||||
matrix_media_repo_metrics_enabled: true
|
||||
```
|
||||
|
||||
**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/matrix-media-repo` by adding the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_media_repo_metrics_proxying_enabled: true
|
||||
```
|
||||
|
||||
By default metrics are exposed publicly **without** password-protection. To password-protect the metrics with dedicated credentials, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_media_repo_container_labels_traefik_metrics_middleware_basic_auth_enabled: true
|
||||
matrix_media_repo_container_labels_traefik_metrics_middleware_basic_auth_users: ''
|
||||
```
|
||||
|
||||
To `matrix_media_repo_container_labels_traefik_metrics_middleware_basic_auth_users`, set the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint. See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users for details about it.
|
||||
|
||||
**Note**: alternatively, you can use `matrix_metrics_exposure_enabled` to expose all services on this `/metrics/*` feature, and you can use `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` to password-protect the metrics of them. See [this section](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) for more information.
|
||||
|
||||
#### Enable Grafana (optional)
|
||||
|
||||
Probably you wish to enable Grafana along with Prometheus for generating graphs of the metics.
|
||||
|
||||
To enable Grafana, see [this section](configuring-playbook-prometheus-grafana.md#adjusting-the-playbook-configuration-grafana) for instructions.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
@ -151,30 +151,51 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
|
||||
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.example.com/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/nginxlog`, `/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/nginxlog`, `/metrics/hookshot`, etc).
|
||||
|
||||
When using `matrix_metrics_exposure_enabled`, you don't need to expose metrics for individual services one by one.
|
||||
To expose all services on this `/metrics/*` feature, you can use `matrix_metrics_exposure_enabled`. When using it, you don't need to expose metrics for individual services one by one. If you think this is too much, refer [this section](#expose-metrics-of-other-services-roles) for details about exposing metrics on a per-service basis.
|
||||
|
||||
To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), you can use `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`. When enabled, all endpoints beneath `/metrics` will be protected with the same credentials. Alternatively, you can protect each endpoint with dedicated credentials. Refer [the section](#expose-metrics-of-other-services-roles) below for details about it.
|
||||
|
||||
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.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_enabled`|Set this to `true` to **enable metrics exposure for all services** on `https://matrix.example.com/metrics/*`.
|
||||
`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).
|
||||
`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.
|
||||
`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.example.com/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`.
|
||||
`prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](#enable-metrics-and-graphs-for-postgres-optional) (locally, on the container network).
|
||||
`prometheus_postgres_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the [Postgres exporter](#enable-metrics-and-graphs-for-postgres-optional) metrics on `https://matrix.example.com/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](#enable-metrics-and-graphs-for-postgres-optional) metrics on `https://matrix.example.com/metrics/postgres-exporter`.
|
||||
`matrix_prometheus_nginxlog_exporter_enabled`|Set this to `true` to enable the [nginx Log exporter](#enable-metrics-and-graphs-for-nginx-logs-optional) (locally, on the container network).
|
||||
`matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [nginx Log exporter](#enable-metrics-and-graphs-for-nginx-logs-optional) metrics on `https://matrix.example.com/metrics/nginxlog`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
|
||||
`matrix_hookshot_metrics_enabled`|Set this to `true` to make [Hookshot](configuring-playbook-bridge-hookshot.md) expose metrics (locally, on the container network).
|
||||
`matrix_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_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.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.
|
||||
`matrix_media_repo_metrics_enabled`|Set this to `true` to make media-repo expose metrics (locally, on the container network).
|
||||
`matrix_media_repo_metrics_proxying_enabled`|Set this to `true` to expose media-repo's metrics on `https://matrix.example.com/metrics/matrix-media-repo`.
|
||||
`matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [nginx Log exporter](#enable-metrics-and-graphs-for-nginx-logs-optional) metrics on `https://matrix.example.com/metrics/nginxlog`.
|
||||
|
||||
### Expose metrics of other services/roles
|
||||
|
||||
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 of a specific role, you can use `matrix_SERVICE_container_labels_metrics_middleware_basic_auth_enabled` and `matrix_SERVICE_container_labels_metrics_middleware_basic_auth_users` variables provided by the role.
|
||||
|
||||
**Note**: alternatively you can use `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` in order to password-protect the metrics of all services.
|
||||
|
||||
For example, you can enable and expose metrics for Synapse protecting them with dedicated credentials by adding the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
# Expose metrics (locally, on the container network).
|
||||
matrix_synapse_metrics_enabled: true
|
||||
|
||||
# Uncomment to expose metrics on https://matrix.example.com/metrics/synapse/main-process and https://matrix.example.com/metrics/synapse/worker/TYPE-ID.
|
||||
# Read the section below ("Collecting Synapse worker metrics to an external Prometheus server") if you're running a Synapse worker setup by setting `matrix_synapse_workers_enabled` to true.
|
||||
# matrix_synapse_metrics_proxying_enabled: true
|
||||
|
||||
# Uncomment to password-protect the metrics for Synapse.
|
||||
# matrix_synapse_container_labels_public_metrics_middleware_basic_auth_enabled: true
|
||||
|
||||
# Uncomment and set this part to the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoints.
|
||||
# See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users
|
||||
# matrix_synapse_container_labels_public_metrics_middleware_basic_auth_users: ''
|
||||
```
|
||||
|
||||
### Collecting Synapse worker metrics to an external Prometheus server
|
||||
|
||||
|
||||
@ -172,7 +172,7 @@ The playbook can install and configure Synapse Admin for you. For details about
|
||||
|
||||
This playbook allows you to enable Synapse metrics, which can provide insight into the performance and activity of Synapse.
|
||||
|
||||
To enable Synapse runtime metrics see: [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](configuring-playbook-prometheus-grafana.md)
|
||||
To enable Synapse runtime metrics, see: [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](configuring-playbook-prometheus-grafana.md) and [its subsection](configuring-playbook-prometheus-grafana.md#expose-metrics-of-other-services-roles)
|
||||
|
||||
To enable Synapse usage metrics, see: [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md)
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user