matrix-ntfy: documentation

This commit is contained in:
Julian Foad 2022-06-27 22:20:02 +01:00
parent 2a516a16fb
commit 85b12b74a7
7 changed files with 71 additions and 36 deletions

View file

@ -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 | `stats` | - | - | - | `matrix.<your-domain>` |
| CNAME | `goneb` | - | - | - | `matrix.<your-domain>` | | CNAME | `goneb` | - | - | - | `matrix.<your-domain>` |
| CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` | | CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| CNAME | `ntfy` | - | - | - | `matrix.<your-domain>` |
| CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` | | CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
| CNAME | `cinny` | - | - | - | `matrix.<your-domain>` | | CNAME | `cinny` | - | - | - | `matrix.<your-domain>` |
| CNAME | `buscarron` | - | - | - | `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 `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 `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. 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.

View file

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

View file

@ -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 `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 `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 `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) - 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. If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too.

View file

@ -168,3 +168,5 @@ When you're done with all the configuration you'd like to do, continue with [Ins
### Other specialized services ### Other specialized services
- [Setting up the Sygnal push gateway](configuring-playbook-sygnal.md) (optional) - [Setting up the Sygnal push gateway](configuring-playbook-sygnal.md) (optional)
- [Setting up the ntfy push notifications server](configuring-playbook-ntfy.md) (optional)

View file

@ -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) - [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 - [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

View file

@ -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 # TODO
- Documentation.
- Self-check. - Self-check.
- Mount the ntfy database to disk so subscriptions persist across restarts. - Mount the ntfy database to disk so subscriptions persist across restarts.
- Authentication? - Authentication?

View file

@ -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. # 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: '' 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: [] matrix_ntfy_container_extra_arguments: []