matrix-ntfy: documentation
This commit is contained in:
Julian Foad
parent
2a516a16fb
commit
85b12b74a7
|
|
@ -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.
|
||||
|
|
|
|||
62
docs/configuring-playbook-ntfy.md
Normal file
62
docs/configuring-playbook-ntfy.md
Normal 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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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?
|
||||
|
|
|
|||
|
|
@ -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: []
|
||||
|
|
|
|||
Loading…
Reference in a new issue