From 85b12b74a75d2e4360948843325238edac16cffd Mon Sep 17 00:00:00 2001 From: Julian Foad Date: Mon, 27 Jun 2022 22:20:02 +0100 Subject: [PATCH] matrix-ntfy: documentation --- docs/configuring-dns.md | 3 + docs/configuring-playbook-ntfy.md | 62 +++++++++++++++++++ docs/configuring-playbook-ssl-certificates.md | 1 + docs/configuring-playbook.md | 2 + docs/container-images.md | 2 + roles/matrix-ntfy/README.md | 35 ----------- roles/matrix-ntfy/defaults/main.yml | 2 +- 7 files changed, 71 insertions(+), 36 deletions(-) create mode 100644 docs/configuring-playbook-ntfy.md diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index 666f8a63d..aec3c2539 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -36,6 +36,7 @@ If you are using Cloudflare DNS, make sure to disable the proxy and set all reco | CNAME | `stats` | - | - | - | `matrix.` | | CNAME | `goneb` | - | - | - | `matrix.` | | CNAME | `sygnal` | - | - | - | `matrix.` | +| CNAME | `ntfy` | - | - | - | `matrix.` | | CNAME | `hydrogen` | - | - | - | `matrix.` | | CNAME | `cinny` | - | - | - | `matrix.` | | CNAME | `buscarron` | - | - | - | `matrix.` | @@ -57,6 +58,8 @@ The `goneb.` subdomain may be necessary, because this playbook coul The `sygnal.` 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.` DNS record. +The `ntfy.` 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.` DNS record. + The `hydrogen.` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/vector-im/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.` DNS record. The `cinny.` 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.` DNS record. diff --git a/docs/configuring-playbook-ntfy.md b/docs/configuring-playbook-ntfy.md new file mode 100644 index 000000000..03684b9c8 --- /dev/null +++ b/docs/configuring-playbook-ntfy.md @@ -0,0 +1,62 @@ +# 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 +matrix_ntfy_enabled: true + +# Some other options +matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}" +matrix_ntfy_container_extra_arguments: [ '--env=NTFY_LOG_LEVEL=DEBUG' ] +``` + +For a more complete list of variables that you could override, see `roles/matrix-ntfy/defaults/main.yml`. + +For a complete list of ntfy config options that you could put in `matrix_ntfy_container_extra_arguments`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options). + + +## Installing + +Don't forget to add `ntfy.` 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 + +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.) + +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. + +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. + + +## 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`. + +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. + +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. diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index eae584e72..30a8f0b87 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -74,6 +74,7 @@ By default, it obtains certificates for: - possibly for `jitsi.`, if you have explicitly [set up Jitsi](configuring-playbook-jitsi.md). - possibly for `stats.`, if you have explicitly [set up Grafana](configuring-playbook-prometheus-grafana.md). - possibly for `sygnal.`, if you have explicitly [set up Sygnal](configuring-playbook-sygnal.md). +- possibly for `ntfy.`, if you have explicitly [set up ntfy](configuring-playbook-ntfy.md). - possibly for your base domain (``), if you have explicitly configured [Serving the base domain](configuring-playbook-base-domain-serving.md) If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too. diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 3bfb01bdc..f71a23f5c 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -168,3 +168,5 @@ When you're done with all the configuration you'd like to do, continue with [Ins ### Other specialized services - [Setting up the Sygnal push gateway](configuring-playbook-sygnal.md) (optional) + +- [Setting up the ntfy push notifications server](configuring-playbook-ntfy.md) (optional) diff --git a/docs/container-images.md b/docs/container-images.md index bf5885e06..25005d5ac 100644 --- a/docs/container-images.md +++ b/docs/container-images.md @@ -109,3 +109,5 @@ These services are not part of our default installation, but can be enabled by [ - [grafana/grafana](https://hub.docker.com/r/grafana/grafana/) - [Grafana](https://github.com/grafana/grafana/) is a graphing tool that works well with the above two images. Our playbook also adds two dashboards for [Synapse](https://github.com/matrix-org/synapse/tree/master/contrib/grafana) and [Node Exporter](https://github.com/rfrail3/grafana-dashboards) - [matrixdotorg/sygnal](https://hub.docker.com/r/matrixdotorg/sygnal/) - [Sygnal](https://github.com/matrix-org/sygnal) is a reference Push Gateway for Matrix + +- [binwiederhier/ntfy](https://hub.docker.com/r/binwiederhier/ntfy/) - [ntfy](https://ntfy.sh/) is a self-hosted, UnifiedPush-compatible push notifications server diff --git a/roles/matrix-ntfy/README.md b/roles/matrix-ntfy/README.md index 8b4f760a1..2a5301f7f 100644 --- a/roles/matrix-ntfy/README.md +++ b/roles/matrix-ntfy/README.md @@ -1,40 +1,5 @@ -# A role to install the [ntfy](https://ntfy.sh) push-notification server. - -The ntfy server and clients implement self-hosted support push notifications -from Matrix (and other) servers to Android (and other) clients, using the -[UnifiedPush](https://unifiedpush.org) standard. - -This role installs ntfy server in Docker. It is intended to support push -notifications, via UnifiedPush, from the Matrix and Matrix-related services -that are installed alongside it to any clients that support UnifiedPush. - -This role is not intended to support other features of the ntfy server and -clients. - - -# Using the ntfy role - -Configure the role by adding settings in your Ansible inventory. - -The only required setting is to enable ntfy: - - matrix_ntfy_enabled: true - -The default domain for ntfy is `ntfy.`. This can be changed -with the `matrix_server_fqn_ntfy` variable: - - matrix_server_fqn_ntfy: "my-ntfy.{{ matrix_domain }}" - -Other ntfy settings can be configured by adding extra arguments to the -docker run command, e.g.: - - matrix_ntfy_container_extra_arguments: - - '--env=NTFY_LOG_LEVEL=DEBUG' - - # TODO -- Documentation. - Self-check. - Mount the ntfy database to disk so subscriptions persist across restarts. - Authentication? diff --git a/roles/matrix-ntfy/defaults/main.yml b/roles/matrix-ntfy/defaults/main.yml index 19e8af8f7..2df796742 100644 --- a/roles/matrix-ntfy/defaults/main.yml +++ b/roles/matrix-ntfy/defaults/main.yml @@ -12,5 +12,5 @@ matrix_ntfy_docker_image_force_pull: "{{ matrix_ntfy_docker_image.endswith(':lat # Takes an ":" or "" value (e.g. "127.0.0.1:8768"), or empty string to not expose. matrix_ntfy_container_http_host_bind_port: '' -# A list of extra arguments to pass to the container +# A list of extra arguments to pass to the container (`docker run` command) matrix_ntfy_container_extra_arguments: []