diff --git a/README.md b/README.md index 1d58eed0..4347b128 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,8 @@ Using this playbook, you can get the following services configured on your serve - (optional) the [Sygnal](https://github.com/matrix-org/sygnal) push gateway - see [Setting up the Sygnal push gateway](docs/configuring-playbook-sygnal.md) for setup documentation +- (optional) the [ntfy](https://ntfy.sh) push notifications server - see [docs/configuring-playbook-ntfy.md](docs/configuring-playbook-ntfy.md) for setup documentation + - (optional) the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client - see [docs/configuring-playbook-client-hydrogen.md](docs/configuring-playbook-client-hydrogen.md) for setup documentation - (optional) the [Cinny](https://github.com/ajbura/cinny) web client - see [docs/configuring-playbook-client-cinny.md](docs/configuring-playbook-client-cinny.md) for setup documentation diff --git a/docs/configuring-playbook-mautrix-bridges.md b/docs/configuring-playbook-mautrix-bridges.md new file mode 100644 index 00000000..1cd76f96 --- /dev/null +++ b/docs/configuring-playbook-mautrix-bridges.md @@ -0,0 +1,111 @@ +# Setting up a Generic Mautrix Bridge (optional) + +The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, facebook, instagram, signal, hangouts, googlechat, etc.), as well as many other (non-mautrix) bridges. +This is a common guide for configuring mautrix bridges. + +You can see each bridge's features at in the `ROADMAP.md` file in its corresponding [mautrix](https://github.com/mautrix) repository. + +To enable a bridge add: + + +```yaml +# Replace SERVICENAME with one of: twitter, facebook, instagram, .. +matrix_mautrix_SERVICENAME_enabled: true +``` + +to your `vars.yml` + +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. + +You can add + +```yaml +matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}" +``` +to `vars.yml` to **configure a user as an administrator for all bridges**. +**Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with: + +```yaml +matrix_mautrix_SERVICENAME_configuration_extension_yaml: | + bridge: + permissions: + '@YOUR_USERNAME:{{ matrix_domain }}': admin +``` + +Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file: +```yaml +matrix_mautrix_SERVICENAME_configuration_extension_yaml: | + bridge: + encryption: + allow: true + default: true +``` + + +You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this: + +```yaml +matrix_mautrix_SERVICENAME_configuration_extension_yaml: | + bridge: + permissions: + '@YOUR_USERNAME:{{ matrix_domain }}': admin + encryption: + allow: true + default: true +``` + +## Setting the bot's username + +```yaml +matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME" +``` + +Can be used to set the username for the bridge. + +## Discovering additional configuration options + +You may wish to look at `roles/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` to find other things you would like to configure. + + +## Set up Double Puppeting + +To set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) + +please do so automatically, by enabling Shared Secret Auth + +The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook by adding + +```yaml +matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true +matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: YOUR_SHARED_SECRET_GOES_HERE +``` + +You should generate a strong shared secret with a command like this: pwgen -s 64 1 + +This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. + +## Controlling the logging level + +```yaml +matrix_mautrix_SERVICENAME_logging_level: WARN +``` + +to `vars.yml` to control the logging level, where you may replace WARN with one of the following to control the verbosity of the logs generated: TRACE, DEBUG, INFO, WARN, ERROR, or FATAL. + +If you have issues with a service, and are requesting support, the higher levels of logging will generally be more helpful. + + +## Usage + +You then need to start a chat with `@SERVICENAMEbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` 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 . + +If you run into trouble, check the [Troubleshooting](#troubleshooting) section below. + + + +## Troubleshooting + +For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge. +Reporting bridge bugs should happen upstream, in the corresponding mautrix repository, not to us. diff --git a/docs/configuring-playbook-ntfy.md b/docs/configuring-playbook-ntfy.md index 56c859f3..57dfb3b2 100644 --- a/docs/configuring-playbook-ntfy.md +++ b/docs/configuring-playbook-ntfy.md @@ -41,9 +41,37 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start ## Usage -To make use of your ntfy installation, on Android for example, first you need to install the `ntfy` client app and configure it to point to your ntfy server, such as `https://ntfy.DOMAIN`. That is the only thing you need to do in the ntfy client app. (It has many other features, but for our purposes you can ignore them.) +To make use of your ntfy installation, on Android for example, you need two things: -Then any UnifiedPush-enabled matrix app on that device will discover it and tell your matrix server to use your ntfy server to send push notifications to that matrix app. +* the `ntfy` app +* a UnifiedPush-compatible matrix app + +You need to install the `ntfy` app on each device on which you want to receive push notifications through your ntfy server. The `ntfy` app will provide UnifiedPush notifications to any number of UnifiedPush-compatible messaging apps installed on the same device. + +### 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`. +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. + +### Setting up a UnifiedPush-compatible matrix app + +Install any UnifiedPush-enabled matrix app on that same device. The matrix app will learn from the `ntfy` app that you have configured UnifiedPush on this device, and then it will tell your matrix server to use it. + +Steps needed for specific matrix apps: + +* FluffyChat-android: + - Should auto-detect and use it. No manual settings. + +* SchildiChat-android: + 1. enable `Settings` -> `Notifications` -> `UnifiedPush: Force custom push gateway`. + 2. choose `Settings` -> `Notifications` -> `UnifiedPush: Re-register push distributor`. *(For info, a more complex alternative to achieve the same is: delete the relevant unifiedpush registration in `ntfy` app, force-close SchildiChat, re-open it.)* + 3. verify `Settings` -> `Notifications` -> `UnifiedPush: Notification targets` as described below in the "Troubleshooting" section. + +* Element-android v1.4.26+: + - [not yet documented; should auto-detect and use it?] If the matrix app asks, "Choose a distributor: FCM Fallback or ntfy", then choose "ntfy". @@ -56,7 +84,9 @@ First check that the matrix client app you are using supports UnifiedPush. There Set the ntfy server's log level to 'DEBUG', as shown in the example settings above, and watch the server's logs with `sudo journalctl -fu matrix-ntfy`. -To check if UnifiedPush is correctly configured on the client device, look at "Settings -> Notifications -> Notification Targets" in Element-Android or SchildiChat, or "Settings -> Notifications -> Devices" in FluffyChat. There should be one entry for each matrix client app that has enabled push notifications, and when that client is using UnifiedPush you should see a URL that begins with your ntfy server's URL. In Element-Android or SchildiChat, two URLs are shown: "push\_key" and "Url", and both should begin with your ntfy server's URL. +To check if UnifiedPush is correctly configured on the client device, look at "Settings -> Notifications -> Notification Targets" in Element-Android or SchildiChat, or "Settings -> Notifications -> Devices" in FluffyChat. There should be one entry for each matrix client app that has enabled push notifications, and when that client is using UnifiedPush you should see a URL that begins with your ntfy server's URL. + +In the "Notification Targets" screen in Element-Android or SchildiChat, two relevant URLs are shown, "push\_key" and "Url", and both should begin with your ntfy server's URL. If "push\_key" shows your server but "Url" shows an external server such as `up.schildi.chat` then push notifications will still work but are being routed through that external server before they reach your ntfy server. To rectify that, in SchildiChat (at least around version 1.4.20.sc55) you must enable the `Force custom push gateway` setting as described in the "Usage" section above. If it is not working, useful tools are "Settings -> Notifications -> Re-register push distributor" and "Settings -> Notifications -> Troubleshoot Notifications" in SchildiChat (possibly also Element-Android). In particular the "Endpoint/FCM" step of that troubleshooter should display your ntfy server's URL that it has discovered from the ntfy client app. diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 1c30405d..25d0a0e1 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -1973,6 +1973,8 @@ matrix_sygnal_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enable matrix_ntfy_enabled: false +matrix_ntfy_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:2586' }}" + ###################################################################### # # /matrix-ntfy diff --git a/roles/matrix-bot-mjolnir/defaults/main.yml b/roles/matrix-bot-mjolnir/defaults/main.yml index dd248379..714cd0d3 100644 --- a/roles/matrix-bot-mjolnir/defaults/main.yml +++ b/roles/matrix-bot-mjolnir/defaults/main.yml @@ -4,7 +4,7 @@ matrix_bot_mjolnir_enabled: true -matrix_bot_mjolnir_version: "v1.4.2" +matrix_bot_mjolnir_version: "v1.5.0" matrix_bot_mjolnir_container_image_self_build: false matrix_bot_mjolnir_container_image_self_build_repo: "https://github.com/matrix-org/mjolnir.git" diff --git a/roles/matrix-bridge-mautrix-whatsapp/defaults/main.yml b/roles/matrix-bridge-mautrix-whatsapp/defaults/main.yml index ef5d1065..e0af254d 100644 --- a/roles/matrix-bridge-mautrix-whatsapp/defaults/main.yml +++ b/roles/matrix-bridge-mautrix-whatsapp/defaults/main.yml @@ -39,6 +39,10 @@ matrix_mautrix_whatsapp_homeserver_token: '' matrix_mautrix_whatsapp_appservice_bot_username: whatsappbot +# Minimum severity of journal log messages. +# Options: debug, info, warn, error, fatal +matrix_mautrix_whatsapp_logging_level: 'warn' + # Whether or not created rooms should have federation enabled. # If false, created portal rooms will never be federated. matrix_mautrix_whatsapp_federate_rooms: true @@ -130,7 +134,3 @@ matrix_mautrix_whatsapp_registration: "{{ matrix_mautrix_whatsapp_registration_y matrix_mautrix_whatsapp_bridge_encryption_allow: false matrix_mautrix_whatsapp_bridge_encryption_default: "{{ matrix_mautrix_whatsapp_bridge_encryption_allow }}" matrix_mautrix_whatsapp_bridge_encryption_key_sharing_allow: "{{ matrix_mautrix_whatsapp_bridge_encryption_allow }}" - -# Minimum severity of journal log messages. -# Options: debug, info, warn, error, fatal -matrix_mautrix_whatsapp_log_level: 'warn' diff --git a/roles/matrix-bridge-mautrix-whatsapp/tasks/validate_config.yml b/roles/matrix-bridge-mautrix-whatsapp/tasks/validate_config.yml index c983c4cc..9b0a725c 100644 --- a/roles/matrix-bridge-mautrix-whatsapp/tasks/validate_config.yml +++ b/roles/matrix-bridge-mautrix-whatsapp/tasks/validate_config.yml @@ -8,3 +8,13 @@ with_items: - "matrix_mautrix_whatsapp_appservice_token" - "matrix_mautrix_whatsapp_homeserver_token" + + +- name: (Deprecation) Catch and report renamed settings + fail: + msg: >- + Your configuration contains a variable, which now has a different name. + Please change your configuration to rename the variable (`{{ item.old }}` -> `{{ item.new }}`). + when: "item.old in vars" + with_items: + - {'old': 'matrix_mautrix_whatsapp_log_level', 'new': 'matrix_mautrix_whatsapp_logging_level'} diff --git a/roles/matrix-bridge-mautrix-whatsapp/templates/config.yaml.j2 b/roles/matrix-bridge-mautrix-whatsapp/templates/config.yaml.j2 index 544e10ad..81be5d80 100644 --- a/roles/matrix-bridge-mautrix-whatsapp/templates/config.yaml.j2 +++ b/roles/matrix-bridge-mautrix-whatsapp/templates/config.yaml.j2 @@ -224,4 +224,4 @@ logging: timestamp_format: "Jan _2, 2006 15:04:05" # Minimum severity for log messages. # Options: debug, info, warn, error, fatal - print_level: {{ matrix_mautrix_whatsapp_log_level }} + print_level: {{ matrix_mautrix_whatsapp_logging_level }} diff --git a/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2 b/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2 index e095e721..988b3b35 100644 --- a/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2 +++ b/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2 @@ -25,7 +25,7 @@ proxy_pass http://$backend; {% else %} {# Generic configuration for use outside of our container setup #} - proxy_pass http://127.0.0.1:80; + proxy_pass http://127.0.0.1:2586; {% endif %} proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; diff --git a/roles/matrix-ntfy/defaults/main.yml b/roles/matrix-ntfy/defaults/main.yml index 4f0e2e55..d5fc3fba 100644 --- a/roles/matrix-ntfy/defaults/main.yml +++ b/roles/matrix-ntfy/defaults/main.yml @@ -12,9 +12,9 @@ matrix_ntfy_docker_image_force_pull: "{{ matrix_ntfy_docker_image.endswith(':lat # Public facing base URL of the ntfy service matrix_ntfy_base_url: "https://{{ matrix_server_fqn_ntfy }}" -# Controls whether the container exposes its HTTP port (tcp/8080 in the container). +# Controls whether the container exposes its HTTP port (tcp/80 in the container). # -# Takes an ":" or "" value (e.g. "127.0.0.1:8768"), or empty string to not expose. +# Takes an ":" or "" value (e.g. "127.0.0.1:2586"), or empty string to not expose. matrix_ntfy_container_http_host_bind_port: '' # A list of extra arguments to pass to the container (`docker run` command)