Merge branch 'master' into element-call-integration

This commit is contained in:
Slavi Pantaleev
2025-03-14 19:32:48 +02:00
25 changed files with 165 additions and 89 deletions

View File

@ -45,7 +45,7 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
```yaml
matrix_appservice_draupnir_for_all_enabled: true
matrix_appservice_draupnir_for_all_master_control_room_alias: "MANAGEMENT_ROOM_ALIAS_HERE"
matrix_appservice_draupnir_for_all_config_adminRoom: "MANAGEMENT_ROOM_ALIAS_HERE"
```
### Extending the configuration

View File

@ -54,11 +54,11 @@ To enable the native E2EE support, add the following configuration to your `vars
```yaml
# Enables the native E2EE support
matrix_bot_draupnir_enable_experimental_rust_crypto: true
matrix_bot_draupnir_config_experimentalRustCrypto: true
# Access token which the bot will use for logging in.
# Comment out `matrix_bot_draupnir_login_native` when using this option.
matrix_bot_draupnir_access_token: "CLEAN_ACCESS_TOKEN_HERE"
matrix_bot_draupnir_config_accessToken: "CLEAN_ACCESS_TOKEN_HERE"
```
## Adjusting the playbook configuration
@ -73,13 +73,13 @@ matrix_bot_draupnir_enabled: true
# matrix_bot_draupnir_login: bot.draupnir
# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
# If creating the user on your own and using `matrix_bot_draupnir_access_token` to login you can comment out this line.
# If creating the user on your own and using `matrix_bot_draupnir_config_accessToken` to login you can comment out this line.
matrix_bot_draupnir_password: PASSWORD_FOR_THE_BOT
# Comment out if using `matrix_bot_draupnir_enable_experimental_rust_crypto: true` or `matrix_bot_draupnir_access_token` to login.
# Comment out if using `matrix_bot_draupnir_config_experimentalRustCrypto: true` or `matrix_bot_draupnir_config_accessToken` to login.
matrix_bot_draupnir_login_native: true
matrix_bot_draupnir_management_room: "MANAGEMENT_ROOM_ID_HERE"
matrix_bot_draupnir_config_managementRoom: "MANAGEMENT_ROOM_ID_HERE"
```
### Create and invite the bot to the management room
@ -142,7 +142,7 @@ Draupnir can receive reports in the management room.
The bot can intercept the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver. If you are using Traefik, this playbook can set this up for you:
```yaml
matrix_bot_draupnir_abuse_reporting_enabled: true
matrix_bot_draupnir_config_web_abuseReporting: true
```
<!--

View File

@ -115,7 +115,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
## Usage
To receive push notifications with UnifiedPush from the ntfy server, you need to **install [the ntfy Android app](https://docs.ntfy.sh/subscribe/phone/)** which works as the Distrubutor and then **configure a UnifiedPush-compatible Matrix client**. After setting up the ntfy Android app, the Matrix client listens to it, and push notitications are "distributed" from it.
To receive push notifications with UnifiedPush from the ntfy server, you need to **install [the ntfy Android app](https://docs.ntfy.sh/subscribe/phone/)** which works as the Distrubutor, **log in to the account on the ntfy app** if you have enabled the access control, and then **configure a UnifiedPush-compatible Matrix client**. After setting up the ntfy Android app, the Matrix client listens to it, and push notitications are "distributed" from it.
For details about installing and configuring the ntfy Android app, take a look at [this section](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#install-the-ntfy-androidios-app) on the role's documentation.

View File

@ -11,57 +11,60 @@ SPDX-License-Identifier: AGPL-3.0-or-later
# 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.example.com` and others)
By default, the playbook retrieves and automatically renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) via [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) for the domains of the services it installs (e.g. `matrix.example.com` and others). Refer this guide if you want to modify settings about how it manages SSL certificates or have the Traefik server use yours.
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).
**Notes**:
- This guide is intended to be referred for configuring the integrated Traefik server with regard to SSL certificates retrieval. If you're using [your own webserver](configuring-playbook-own-webserver.md), consult its documentation about how to configure it.
- Let's Encrypt ends the expiration notification email service on June 4, 2025 (see: [the official announcement](https://letsencrypt.org/2025/01/22/ending-expiration-emails/)), and it recommends using a third party service for those who want to receive expiriation notifications. If you are looking for a self-hosting service, you may be interested in a monitoring tool such as [Update Kuma](https://github.com/louislam/uptime-kuma/).
## Using staging Let's Encrypt certificates instead of real ones
The [Mother-of-All-Self-Hosting (MASH)](https://github.com/mother-of-all-self-hosting/mash-playbook) Ansible playbook can be used to install and manage an Uptime Kuma instance. See [this page](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/uptime-kuma.md) for the instruction to install it with the MASH playbook. If you are wondering how to use the MASH playbook for your Matrix server, refer [this page](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/setting-up-services-on-mdad-server.md).
For testing purposes, you may wish to use staging certificates provide by Let's Encrypt.
## Use staging Let's Encrypt certificates
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
For testing purposes, you may wish to use staging certificates provided by Let's Encrypt to avoid hitting [its rate limits](https://letsencrypt.org/docs/rate-limits/).
To use ones, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
traefik_config_certificatesResolvers_acme_use_staging: true
```
## Disabling SSL termination
## Disable SSL termination
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 `vars.yml` file:
To do so, add the following configuration to your `vars.yml` file:
```yaml
traefik_config_entrypoint_web_secure_enabled: false
```
## Using self-signed SSL certificates
## Use self-signed SSL certificates
If you'd like to use your own SSL certificates, instead of the default (SSL certificates obtained automatically via [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) from [Let's Encrypt](https://letsencrypt.org/)):
To use self-signed certificates, generate them and follow the documentation below about using your own certificates.
- generate your self-signed certificate files
- follow the [Using your own SSL certificates](#using-your-own-ssl-certificates) documentation below
## Use your own SSL certificates
## Using your own SSL certificates
To use your own certificates, prepare them and follow the steps below:
To use your own SSL certificates with Traefik, you need to:
- Disable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/) support
- Put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
- Register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/)
- Put the SSL files on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
- disable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/) support
- put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
- register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/)
- put the SSL files on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
For those steps, you can add the following configuration to your `vars.yml` file (adapt to your needs). If you will put the custom configuration files manually, make sure to remove the `aux_file_definitions` variable.
```yaml
# Disable ACME / Let's Encrypt support.
traefik_config_certificatesResolvers_acme_enabled: false
# Disabling ACME support (above) automatically disables the creation of the SSL directory.
# Force-enable it here, because we'll add our certificate files there.
# Disabling ACME support (above) automatically disables the SSL directory to be created.
# Force-enable it to be created with this configuration, because we'll add our certificate files there.
traefik_ssl_dir_enabled: true
# Tell Traefik to load our custom ssl key pair by extending provider configuration.
# Tell Traefik to load our custom SSL key pair by extending provider configuration.
# The key pair files are created below, in `aux_file_definitions`.
# The `/ssl/…` path is an in-container path, not a path on the host (like `/matrix/traefik/ssl`). Do not change it!
# Note that the `/ssl/…` path is an **in-container path**, not a path on the host (like `/matrix/traefik/ssl`). Do not change it!
traefik_provider_configuration_extension_yaml:
tls:
certificates:
@ -74,14 +77,14 @@ traefik_provider_configuration_extension_yaml:
keyFile: /ssl/privkey.pem
# Use the aux role to create our custom files on the server.
# If you'd like to do this manually, you remove this `aux_file_definitions` variable.
# If you'd like to do this manually, remove this `aux_file_definitions` variable.
aux_file_definitions:
# Create the privkey.pem file on the server by
# uploading a file from the computer where Ansible is running.
- dest: "{{ traefik_ssl_dir_path }}/privkey.pem"
src: /path/on/your/Ansible/computer/to/privkey.pem
# Alternatively, comment out `src` above and uncomment the lines below to provide the certificate content inline.
# Note the indentation level.
# Mind the indentation level (indented with two white space characters).
# content: |
# FILE CONTENT
# HERE
@ -91,20 +94,22 @@ aux_file_definitions:
- dest: "{{ traefik_ssl_dir_path }}/cert.pem"
src: /path/on/your/Ansible/computer/to/cert.pem
# Alternatively, comment out `src` above and uncomment the lines below to provide the certificate content inline.
# Note the indentation level.
# Mind the indentation level (indented with two white space characters).
# content: |
# FILE CONTENT
# HERE
```
## Using a DNS-01 ACME challenge type, instead of HTTP-01
## Use a DNS-01 ACME challenge type, instead of HTTP-01
You can configure Traefik to use the [DNS-01 challenge type](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) for Let's Encrypt. This is less commonly used than the default [HTTP-01 challenge type](https://letsencrypt.org/docs/challenge-types/#http-01-challenge), but it can be helpful to:
You can configure Traefik to use the [DNS-01 challenge type](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) for Let's Encrypt. This is less commonly used than the default [HTTP-01 challenge type](https://letsencrypt.org/docs/challenge-types/#http-01-challenge), but can be helpful to:
- hide your public IP from Let's Encrypt logs
- allow you to obtain SSL certificates for servers which are not accessible (via HTTP) from the public internet (and for which the HTTP-01 challenge would fail)
This is an example for how to edit the `vars.yml` file if you're using Cloudflare:
### Example: Cloudflare
Here is an example for configurations on the `vars.yml` file for Cloudflare. Please adjust it as necessary before applying it.
```yaml
traefik_config_certificatesResolvers_acme_dnsChallenge_enabled: true

View File

@ -27,7 +27,7 @@ Here are some playbook tags that you should be familiar with:
- `stop` — stops all systemd services
- `ensure-matrix-users-created` — a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created
- `ensure-matrix-users-created` or its alias `ensure-users-created` — a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created
**Notes**:
- `setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc.