From 5ece1fea5a1a7084e8a937e774487b418bdf9c42 Mon Sep 17 00:00:00 2001
From: Suguru Hirahara <acioustick@noreply.codeberg.org>
Date: Tue, 11 Mar 2025 17:58:05 +0900
Subject: [PATCH] Update docs/configuring-playbook-ntfy.md: reflect the role's
 documentation

Based on https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/4e27dafc5cd48e1ce0804613f5a2afb94f9d8256/docs/configuring-ntfy.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
---
 docs/configuring-playbook-ntfy.md | 64 +++++++++++++++++++------------
 1 file changed, 40 insertions(+), 24 deletions(-)

diff --git a/docs/configuring-playbook-ntfy.md b/docs/configuring-playbook-ntfy.md
index b30aa2153..8d5a63997 100644
--- a/docs/configuring-playbook-ntfy.md
+++ b/docs/configuring-playbook-ntfy.md
@@ -1,5 +1,6 @@
 <!--
 SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 - 2024 Nikita Chernyi
 SPDX-FileCopyrightText: 2022 Julian Foad
 SPDX-FileCopyrightText: 2022 MDAD project contributors
 SPDX-FileCopyrightText: 2023 Felix Stupp
@@ -12,18 +13,36 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 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.
+ntfy lets you send push notifications to your phone or desktop via scripts from any computer, using simple HTTP PUT or POST requests. It makes it possible to send/receive notifications, without relying on servers owned and controlled by third parties.
 
-See the project's [documentation](https://docs.ntfy.sh/) to learn what it does and why it might be useful to you.
+With the [UnifiedPush](https://unifiedpush.org) standard, ntfy also enables self-hosted push notifications from Matrix (and other) servers to UnifiedPush-compatible Matrix client apps running on Android devices.
 
-**Notes**:
-- To make use of your ntfy installation, you need to install [the `ntfy` app](https://docs.ntfy.sh/subscribe/phone/) on your device and configuring your UnifiedPush-compatible Matrix client. **Otherwise your device will not receive push notifications from the ntfy server.** Refer [this section](#usage) for details.
-- This playbook focuses on setting up a ntfy server for getting it send UnifiedPush notifications to Matrix-related services that this playbook installs, while the installed server will be available for other non-Matrix apps as well like [Tusky](https://tusky.app/) and [DAVx⁵](https://www.davx5.com/). This playbook does not intend to support all of ntfy's features.
+See the project's [documentation](https://docs.ntfy.sh/) to learn what ntfy does and why it might be useful to you.
 
 The [Ansible role for ntfy](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy) is developed and maintained by [the MASH (mother-of-all-self-hosting) project](https://github.com/mother-of-all-self-hosting). For details about configuring ntfy, you can check them via:
 - 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md) online
 - 📁 `roles/galaxy/ntfy/docs/configuring-ntfy.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
 
+**Note**: this playbook focuses on setting up a ntfy server for getting it send push notifications with UnifiedPush to Matrix-related services that this playbook installs, while the installed server will be available for other non-Matrix apps like [Tusky](https://tusky.app/) and [DAVx⁵](https://www.davx5.com/) as well. This playbook does not intend to support all of ntfy's features. If you want to use them as well, refer the role's documentation for details to configure them by yourself.
+
+### Improve push notification's privacy with ntfy
+
+By default, push notifications received on Matrix apps on Android/iOS act merely as "wake-up calls" for the application, which contain only event IDs, and do not transmit actual message payload such as text message data.
+
+While your messages remain private even without ntfy, it makes it possible to improve privacy and sovereignty of your Matrix installation, offering greater control over your data, by avoiding routing these "application wake-up calls" through Google or Apple servers and having them pass through the self-hosted ntfy instance on your Matrix server.
+
+### How ntfy works with UnifiedPush
+
+⚠️ [UnifiedPush does not work on iOS.](https://unifiedpush.org/users/faq/#will-unifiedpush-ever-work-on-ios)
+
+ntfy implements UnifiedPush, the standard which makes it possible to send and receive push notifications without using Google's Firebase Cloud Messaging (FCM) service.
+
+Working as a **Push Server**, a ntfy server can forward messages via [the ntfy Android app](https://docs.ntfy.sh/subscribe/phone/) as a **Distributor** to a UnifiedPush-compatible Matrix client such as Element Android and FluffyChat Android (see [here](https://unifiedpush.org/users/distributors/#definitions) for the definition of the Push Server and the Distributor).
+
+Note that UnifiedPush-compatible applications must be able to communicate with the ntfy Android app which works as the Distributor on the same device, in order to receive push notifications from the Push Server.
+
+As the ntfy Android app functions as the Distributor, you do not have to install something else on your device, besides a UnifiedPush-compatible Matrix client.
+
 ## Adjusting DNS records
 
 By default, this playbook installs ntfy on the `ntfy.` subdomain (`ntfy.example.com`) and requires you to create a CNAME record for `ntfy`, which targets `matrix.example.com`.
@@ -32,7 +51,7 @@ When setting, replace `example.com` with your own.
 
 ## Adjusting the playbook configuration
 
-To enable ntfy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable a ntfy server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 ########################################################################
@@ -50,7 +69,7 @@ ntfy_enabled: true
 ########################################################################
 ```
 
-As the most of the necessary settings for the role have been taken care of by the playbook, you can enable ntfy on your Matrix server with this minimum configuration.
+As the most of the necessary settings for the role have been taken care of by the playbook, you can enable the ntfy server on your Matrix server with this minimum configuration.
 
 See the role's documentation for details about configuring ntfy per your preference (such as [setting access control with authentication](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#enable-access-control-with-authentication-optional)).
 
@@ -69,7 +88,9 @@ After changing the domain, **you may need to adjust your DNS** records to point
 
 ### Enable web app (optional)
 
-ntfy also has a web app to subscribe to and push to topics from the browser. This may be helpful to troubleshoot notification issues or to use ntfy for other purposes than getting ntfy send UnifiedPush notifications to your Matrix-related services.
+The ntfy server can be accessed via its web app where you can subscribe to and push to "topics" from the browser. The web app may be helpful to troubleshoot notification issues or to use ntfy for other purposes than getting ntfy send UnifiedPush notifications to your Matrix-related services.
+
+**Note**: subscribing to a topic is not necessary for using the nfty server as the Push Server for UnifiedPush.
 
 To enable the web app, add the following configuration to your `vars.yml` file:
 
@@ -94,31 +115,26 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
 
 ## Usage
 
-Unlike push notifications using Google's FCM or Apple's APNs, each end-user can choose the UnifiedPush-enabled push notification server that one prefer. This means that deploying a ntfy server does not ensure any particular user, device or Matrix client will use it.
+To receive push notifications with UnifiedPush from the ntfy server, you need to **install [the ntfy Android app](https://docs.ntfy.sh/subscribe/phone/)** which works as the Distrubutor and then **configure a UnifiedPush-compatible Matrix client**. After setting up the ntfy Android app, the Matrix client listens to it, and push notitications are "distributed" from it.
 
-To receive push notifications from your ntfy server, you need to set up these two applications on your device:
+For details about installing and configuring the ntfy Android app, take a look at [this section](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#install-the-ntfy-androidios-app) on the role's documentation.
 
-* [the `ntfy` app](https://docs.ntfy.sh/subscribe/phone/)
-* a UnifiedPush-compatible Matrix client
-
-For details about installing and configuring the `ntfy` app, take a look at [this section](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#setting-up-the-ntfy-android-app) on the role's documentation.
-
-**Note**: on the app you do not need to subscribe to a notification topic by yourself, as UnifiedPush will do that automatically.
+⚠️ Though the ntfy app is available for iOS ([App Store](https://apps.apple.com/us/app/ntfy/id1625396347); the app's source code can be retrieved from [here](https://github.com/binwiederhier/ntfy-ios)), **any Matrix clients for iOS currently do not support ntfy** due to [technical limitations of the iOS platform](https://github.com/binwiederhier/ntfy-ios/blob/main/docs/TECHNICAL_LIMITATIONS.md). If you develop your own Matrix client app for iOS, you may need to use the [Sygnal](configuring-playbook-sygnal.md) push gateway service to deliver push notifications to it.
 
 ### Setting up a UnifiedPush-compatible Matrix client
 
-After installing the `ntfy` app, install any UnifiedPush-enabled Matrix client on that same device. The Matrix client will learn from the `ntfy` app that you have configured UnifiedPush on this device, and then it will tell your Matrix server to use it.
+Having configured the ntfy Android app, you can configure a UnifiedPush-compatible Matrix client on the same device.
 
 Steps needed for specific Matrix clients:
 
-* FluffyChat-android: this should auto-detect and use the app. No manual settings required.
+* FluffyChat-Android: this should auto-detect and use the app. No manual settings required.
 
-* SchildiChat-android:
+* SchildiChat-Android:
   1. enable `Settings` -> `Notifications` -> `UnifiedPush: Force custom push gateway`.
-  2. choose `Settings` -> `Notifications` -> `UnifiedPush: Re-register push distributor`. *(For info, a more complex alternative to achieve the same is: delete the relevant unifiedpush registration in `ntfy` app, force-close SchildiChat, re-open it.)*
+  2. choose `Settings` -> `Notifications` -> `UnifiedPush: Re-register push distributor`. *(For info, a more complex alternative to achieve the same is: delete the relevant unifiedpush registration in the ntfy Android app, force-close SchildiChat, re-open it.)*
   3. verify `Settings` -> `Notifications` -> `UnifiedPush: Notification targets` as described below in the "Troubleshooting" section.
 
-* Element-android v1.4.26+:
+* Element-Android v1.4.26+:
   1. choose `Settings` -> `Notifications` -> `Notification method` -> `ntfy`
   2. verify `Settings` -> `Troubleshoot` -> `Troubleshoot notification settings`
 
@@ -128,9 +144,11 @@ If the Matrix client doesn't seem to pick it up, try restarting it and try the T
 
 ## Troubleshooting
 
+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.
+
 ### Check the Matrix client
 
-First, make sure that the Matrix client you are using supports UnifiedPush. There may well be different variants of the app.
+Make sure that the Matrix client you are using supports UnifiedPush. There may well be different variants of the app.
 
 To check if UnifiedPush is correctly configured on the client device, look at "Settings -> Notifications -> Notification Targets" in Element Android or SchildiChat Android, or "Settings -> Notifications -> Devices" in FluffyChat. There should be one entry for each Matrix client 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.
 
@@ -138,8 +156,6 @@ In the "Notification Targets" screen in Element Android or SchildiChat Android,
 
 If it is not working, useful tools are "Settings -> Notifications -> Re-register push distributor" and "Settings -> Notifications -> Troubleshoot Notifications" in SchildiChat Android (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.
-
 ### Check the service's logs
 
 See [this section](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#check-the-services-logs) on the role's documentation for details.