jowj/matrix-docker-ansible-deploy
1
0
Fork 0
forked from mirrors/matrix-docker-ansible-deploy
Code Issues Pull Requests Releases Wiki Activity
910166effd
matrix-docker-ansible-deploy/docs/configuring-playbook-ntfy.md

107 lines
6.8 KiB
Markdown
Raw Normal View History

matrix-ntfy: documentation
2022-06-27 21:20:02 +00:00
# Setting up ntfy (optional)
The playbook can install and configure the [ntfy](https://ntfy.sh/) push notifications server for you.
Using the [UnifiedPush](https://unifiedpush.org) standard, ntfy enables self-hosted (Google-free) push notifications from Matrix (and other) servers to UnifiedPush-compatible matrix compatible client apps running on Android and other devices.
This role is intended to support UnifiedPush notifications for use with the Matrix and Matrix-related services that this playbook installs. This role is not intended to support all of ntfy's other features.
**Note**: In contrast to push notifications using Google's FCM or Apple's APNs, the use of UnifiedPush allows each end-user to choose the push notification server that they prefer. As a consequence, deploying this ntfy server does not by itself ensure any particular user or device or client app will use it.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
# Enabling it is the only required setting
Switch to using an external Ntfy role The newly extracted role also has native Traefik support, so we no longer need to rely on `matrix-nginx-proxy` for reverse-proxying to Ntfy. The new role uses port `80` inside the container (not `8080`, like before), because that's the default assumption of the officially published container image. Using a custom port (like `8080`), means the default healthcheck command (which hardcodes port `80`) doesn't work. Instead of fiddling to override the healthcheck command, we've decided to stick to the default port instead. This only affects the inside-the-container port, not any external ports. The new role also supports adding the network ranges of the container's multiple additional networks as "exempt hosts". Previously, only one network's address range was added to "exempt hosts".
2023-02-17 07:54:33 +00:00
ntfy_enabled: true
matrix-ntfy: documentation
2022-06-27 21:20:02 +00:00
Switch to using an external Ntfy role The newly extracted role also has native Traefik support, so we no longer need to rely on `matrix-nginx-proxy` for reverse-proxying to Ntfy. The new role uses port `80` inside the container (not `8080`, like before), because that's the default assumption of the officially published container image. Using a custom port (like `8080`), means the default healthcheck command (which hardcodes port `80`) doesn't work. Instead of fiddling to override the healthcheck command, we've decided to stick to the default port instead. This only affects the inside-the-container port, not any external ports. The new role also supports adding the network ranges of the container's multiple additional networks as "exempt hosts". Previously, only one network's address range was added to "exempt hosts".
2023-02-17 07:54:33 +00:00
# This is the default hostname.
# Uncomment the line below and change it, if you'd like.
# matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
ntfy doc: Describe web app & how to enable it See #2529
2023-03-22 09:14:36 +00:00
# Uncomment to enable the ntfy web app (disabled by default)
# ntfy_web_root: app # defaults to "disable"
Switch to using an external Ntfy role The newly extracted role also has native Traefik support, so we no longer need to rely on `matrix-nginx-proxy` for reverse-proxying to Ntfy. The new role uses port `80` inside the container (not `8080`, like before), because that's the default assumption of the officially published container image. Using a custom port (like `8080`), means the default healthcheck command (which hardcodes port `80`) doesn't work. Instead of fiddling to override the healthcheck command, we've decided to stick to the default port instead. This only affects the inside-the-container port, not any external ports. The new role also supports adding the network ranges of the container's multiple additional networks as "exempt hosts". Previously, only one network's address range was added to "exempt hosts".
2023-02-17 07:54:33 +00:00
# Uncomment and change to inject additional configuration options.
# ntfy_configuration_extension_yaml: |
# log_level: DEBUG
matrix-ntfy: documentation
2022-06-27 21:20:02 +00:00
```
Switch to using an external Ntfy role The newly extracted role also has native Traefik support, so we no longer need to rely on `matrix-nginx-proxy` for reverse-proxying to Ntfy. The new role uses port `80` inside the container (not `8080`, like before), because that's the default assumption of the officially published container image. Using a custom port (like `8080`), means the default healthcheck command (which hardcodes port `80`) doesn't work. Instead of fiddling to override the healthcheck command, we've decided to stick to the default port instead. This only affects the inside-the-container port, not any external ports. The new role also supports adding the network ranges of the container's multiple additional networks as "exempt hosts". Previously, only one network's address range was added to "exempt hosts".
2023-02-17 07:54:33 +00:00
For a more complete list of variables that you could override, see the [`defaults/main.yml` file](https://gitlab.com/etke.cc/roles/ntfy/-/blob/main/defaults/main.yml) of the ntfy Ansible role.
matrix-ntfy: documentation
2022-06-27 21:20:02 +00:00
Switch to using an external Ntfy role The newly extracted role also has native Traefik support, so we no longer need to rely on `matrix-nginx-proxy` for reverse-proxying to Ntfy. The new role uses port `80` inside the container (not `8080`, like before), because that's the default assumption of the officially published container image. Using a custom port (like `8080`), means the default healthcheck command (which hardcodes port `80`) doesn't work. Instead of fiddling to override the healthcheck command, we've decided to stick to the default port instead. This only affects the inside-the-container port, not any external ports. The new role also supports adding the network ranges of the container's multiple additional networks as "exempt hosts". Previously, only one network's address range was added to "exempt hosts".
2023-02-17 07:54:33 +00:00
For a complete list of ntfy config options that you could put in `ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
matrix-ntfy: documentation
2022-06-27 21:20:02 +00:00
## Installing
Don't forget to add `ntfy.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
matrix-ntfy: document ntfy & schildichat app settings
2022-07-06 13:03:43 +00:00
To make use of your ntfy installation, on Android for example, you need two things:
matrix-ntfy: documentation
2022-06-27 21:20:02 +00:00
matrix-ntfy: document ntfy & schildichat app settings
2022-07-06 13:03:43 +00:00
* 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:
matrix-ntfy: more detailed usage docs for SchildiChat
2022-07-08 12:18:30 +00:00
* 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+:
Updated the Element settings.
2022-09-19 19:04:02 +00:00
1. choose `Settings` -> `Notifications` -> `Notification method` -> `ntfy`
2. verify `Settings` -> `Troubleshoot` -> `Troubleshoot notification settings`
matrix-ntfy: documentation
2022-06-27 21:20:02 +00:00
If the matrix app asks, "Choose a distributor: FCM Fallback or ntfy", then choose "ntfy".
If the matrix app doesn't seem to pick it up, try restarting it and try the Troubleshooting section below.
ntfy doc: Describe web app & how to enable it See #2529
2023-03-22 09:14:36 +00:00
### Web App
Update configuring-playbook-ntfy.md
2023-03-22 09:28:34 +00:00
ntfy also has a web app to subscribe to and push to topics from the browser. This may be helpful to further troubleshoot UnifiedPush problems or to use ntfy for other purposes. The web app only runs in the browser locally (after downloading the JavaScript).
ntfy doc: Describe web app & how to enable it See #2529
2023-03-22 09:14:36 +00:00
The web app is disabled in this playbook by default as the expectation is that most users won't use it. You can either use the [official hosted one](https://ntfy.sh/app) (it supports using other public reachable ntfy instances) or host it yourself by setting `ntfy_web_root: "app"` and re-running Ansible.
matrix-ntfy: documentation
2022-06-27 21:20:02 +00:00
## Troubleshooting
First check that the matrix client app you are using supports UnifiedPush. There may well be different variants of the app.
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`.
matrix-ntfy: more detailed usage docs for SchildiChat
2022-07-08 12:18:30 +00:00
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.
matrix-ntfy: documentation
2022-06-27 21:20:02 +00:00
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.
The simple [UnifiedPush troubleshooting](https://unifiedpush.org/users/troubleshooting/) app [UP-Example](https://f-droid.org/en/packages/org.unifiedpush.example/) can be used to manually test UnifiedPush registration and operation on an Android device.
Reference in New Issue Copy Permalink