Julian Foad
2 years ago
parent
2a516a16fb
commit
85b12b74a7
@ -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.
|
||||||
@ -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?
|
||||||
|
|||||||
Loading…
Reference in new issue