matrix-ntfy: documentation

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.<your-domain>` |
 | CNAME | `goneb`                      | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `sygnal`                     | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `ntfy`                       | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `hydrogen`                   | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `cinny`                      | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `buscarron`                  | -        | -      | -    | `matrix.<your-domain>` |
@@ -57,6 +58,8 @@ The `goneb.<your-domain>` subdomain may be necessary, because this playbook coul
 
 The `sygnal.<your-domain>` 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.<your-domain>` DNS record.
 
+The `ntfy.<your-domain>` 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.<your-domain>` DNS record.
+
 The `hydrogen.<your-domain>` 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.<your-domain>` DNS record.
 
 The `cinny.<your-domain>` 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.<your-domain>` DNS record.

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.<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
+
+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.

docs/configuring-playbook-ssl-certificates.md

@@ -74,6 +74,7 @@ By default, it obtains certificates for:
 - possibly for `jitsi.<your-domain>`, if you have explicitly [set up Jitsi](configuring-playbook-jitsi.md).
 - possibly for `stats.<your-domain>`, if you have explicitly [set up Grafana](configuring-playbook-prometheus-grafana.md).
 - possibly for `sygnal.<your-domain>`, if you have explicitly [set up Sygnal](configuring-playbook-sygnal.md).
+- possibly for `ntfy.<your-domain>`, if you have explicitly [set up ntfy](configuring-playbook-ntfy.md).
 - possibly for your base domain (`<your-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.

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)

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

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.<matrix_domain>`.  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?

roles/matrix-ntfy/defaults/main.yml

@@ -12,5 +12,5 @@ matrix_ntfy_docker_image_force_pull: "{{ matrix_ntfy_docker_image.endswith(':lat
 # Takes an "<ip>:<port>" or "<port>" 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: []