diff --git a/docs/config.md b/docs/config.md index 56db10c3..4f9afc09 100644 --- a/docs/config.md +++ b/docs/config.md @@ -21,7 +21,7 @@ If desired, ntfy can temporarily keep notifications in an in-memory or an on-dis of time is important to allow [phones](subscribe/phone.md) and other devices with brittle Internet connections to be able to retrieve notifications that they may have missed. -By default, ntfy keeps messages in memory for 12 hours, which means that **cached messages do not survive an application +By default, ntfy keeps messages **in-memory for 12 hours**, which means that **cached messages do not survive an application restart**. You can override this behavior using the following config settings: * `cache-file`: if set, ntfy will store messages in a SQLite based cache (default is empty, which means in-memory cache). @@ -29,7 +29,7 @@ restart**. You can override this behavior using the following config settings: * `cache-duration`: defines the duration for which messages are stored in the cache (default is `12h`) Subscribers can retrieve cached messaging using the [`poll=1` parameter](subscribe/api.md#polling), as well as the -[`since=` parameter](subscribe/api.md#since). +[`since=` parameter](subscribe/api.md#fetching-cached-messages). ## Behind a proxy (TLS, etc.) @@ -42,27 +42,27 @@ flag. This will instruct the [rate limiting](#rate-limiting) logic to use the `X identifier for a visitor, as opposed to the remote IP address. If the `behind-proxy` flag is not set, all visitors will be counted as one, because from the perspective of the ntfy server, they all share the proxy's IP address. -**TLS/SSL:** ntfy supports HTTPS/TLS by setting the `listen-https` config option. However, if you are behind a proxy, it is -recommended that TLS/SSL termination is done by the proxy itself. +**TLS/SSL:** ntfy supports HTTPS/TLS by setting the `listen-https` [config option](#config-options). However, if you +are behind a proxy, it is recommended that TLS/SSL termination is done by the proxy itself. ## Firebase (FCM) !!! info - Using Firebase is **optional** and only works if you modify and build your own Android .apk. + Using Firebase is **optional** and only works if you modify and [build your own Android .apk](develop.md#android-app). For a self-hosted instance, it's easier to just not bother with FCM. [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging) is the Google approved way to send push messages to Android devices. FCM is the only method that an Android app can receive messages without having to run a [foreground service](https://developer.android.com/guide/components/foreground-services). -For the main host [ntfy.sh](https://ntfy.sh), the [ntfy Android App](subscribe/phone.md) uses Firebase to send messages +For the main host [ntfy.sh](https://ntfy.sh), the [ntfy Android app](subscribe/phone.md) uses Firebase to send messages to the device. For other hosts, instant delivery is used and FCM is not involved. To configure FCM for your self-hosted instance of the ntfy server, follow these steps: 1. Sign up for a [Firebase account](https://console.firebase.google.com/) -2. Create an app and download the key file (e.g. `myapp-firebase-adminsdk-ahnce-....json`) +2. Create a Firebase app and download the key file (e.g. `myapp-firebase-adminsdk-...json`) 3. Place the key file in `/etc/ntfy`, set the `firebase-key-file` in `config.yml` accordingly and restart the ntfy server -4. Build your own Android .apk following [these instructions]() +4. Build your own Android .apk following [these instructions](develop.md#android-app) Example: ``` @@ -100,7 +100,7 @@ During normal usage, you shouldn't encounter this limit at all, and even if you reconnect after a connection drop), it shouldn't have any effect. ## Config options -Each config options can be set in the config file `/etc/ntfy/config.yml` (e.g. `listen-http: :80`) or as a +Each config option can be set in the config file `/etc/ntfy/config.yml` (e.g. `listen-http: :80`) or as a CLI option (e.g. `--listen-http :80`. Here's a list of all available options. Alternatively, you can set an environment variable before running the `ntfy` command (e.g. `export NTFY_LISTEN_HTTP=:80`). @@ -110,8 +110,8 @@ variable before running the `ntfy` command (e.g. `export NTFY_LISTEN_HTTP=:80`). | `listen-https` | `NTFY_LISTEN_HTTPS` | `[host]:port` | - | Listen address for the HTTPS web server. If set, you also need to set `key-file` and `cert-file`. | | `key-file` | `NTFY_KEY_FILE` | *filename* | - | HTTPS/TLS private key file, only used if `listen-https` is set. | | `cert-file` | `NTFY_CERT_FILE` | *filename* | - | HTTPS/TLS certificate file, only used if `listen-https` is set. | -| `firebase-key-file` | `NTFY_FIREBASE_KEY_FILE` | *filename* | - | If set, also publish messages to a Firebase Cloud Messaging (FCM) topic for your app. This is optional and only required to save battery when using the Android app. | -| `cache-file` | `NTFY_CACHE_FILE` | *filename* | - | If set, messages are cached in a local SQLite database instead of only in-memory. This allows for service restarts without losing messages in support of the since= parameter. | +| `firebase-key-file` | `NTFY_FIREBASE_KEY_FILE` | *filename* | - | If set, also publish messages to a Firebase Cloud Messaging (FCM) topic for your app. This is optional and only required to save battery when using the Android app. See [Firebase (FCM](#firebase-fcm). | +| `cache-file` | `NTFY_CACHE_FILE` | *filename* | - | If set, messages are cached in a local SQLite database instead of only in-memory. This allows for service restarts without losing messages in support of the since= parameter. See [message cache](#message-cache). | | `cache-duration` | `NTFY_CACHE_DURATION` | *duration* | 12h | Duration for which messages will be buffered before they are deleted. This is required to support the `since=...` and `poll=1` parameter. | | `keepalive-interval` | `NTFY_KEEPALIVE_INTERVAL` | *duration* | 30s | Interval in which keepalive messages are sent to the client. This is to prevent intermediaries closing the connection for inactivity. Note that the Android app has a hardcoded timeout at 77s, so it should be less than that. | | `manager-interval` | `$NTFY_MANAGER_INTERVAL` | *duration* | 1m | Interval in which the manager prunes old messages, deletes topics and prints the stats. | diff --git a/docs/examples.md b/docs/examples.md index b49d6ca1..1359331d 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -18,7 +18,7 @@ rsync -a root@laptop /backups/laptop \ ## Server-sent messages in your web app Just as you can [subscribe to topics in the Web UI](subscribe/web.md), you can use ntfy in your own -web application. Check out the live example or just look the source of this page. +web application. Check out the live example or just look the source of this page. ## Notify on SSH login Years ago my home server was broken into. That shook me hard, so every time someone logs into any machine that I diff --git a/docs/faq.md b/docs/faq.md index 947fcce6..351ad5ee 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -22,23 +22,24 @@ client network disruptions. ## Can I self-host it? Yes. The server (including this Web UI) can be self-hosted, and the Android app supports adding topics from -your own server as well. There are install instructions -on GitHub. +your own server as well. Check out the [install instructions](install.md). ## Why is Firebase used? In addition to caching messages locally and delivering them to long-polling subscribers, all messages are also published to Firebase Cloud Messaging (FCM) (if `FirebaseKeyFile` is set, which it is on ntfy.sh). This -is to facilitate instant notifications on Android. -
+is to facilitate notifications on Android. + +If you do not care for Firebase, I suggest you install the [F-Droid version](https://f-droid.org/en/packages/io.heckel.ntfy/) +of the app and [self-host your own ntfy server](install.md). ## How much battery does the Android app use? -If you use the ntfy.sh server and you don't use the instant delivery feature, the Android app uses no -additional battery, since Firebase Cloud Messaging (FCM) is used. If you use your own server, or you use -instant delivery, the app has to maintain a constant connection to the server, which consumes about 4% of -battery in 17h of use (on my phone). I use it and it makes no difference to me. +If you use the ntfy.sh server and you don't use the [instant delivery](subscribe/phone.md#instant-delivery) feature, +the Android app uses no additional battery, since Firebase Cloud Messaging (FCM) is used. If you use your own server, +or you use *instant delivery*, the app has to maintain a constant connection to the server, which consumes about 4% of +battery in 17h of use (on my phone). I use it, and it makes no difference to me. ## What is instant delivery? -Instant delivery is a feature in the Android app. If turned on, the app maintains a constant connection to the +[Instant delivery](subscribe/phone.md#instant-delivery) is a feature in the Android app. If turned on, the app maintains a constant connection to the server and listens for incoming notifications. This consumes additional battery, but delivers notifications instantly. diff --git a/docs/index.md b/docs/index.md index c6a42cc1..9e9a3d2d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,79 @@ # Getting started +ntfy lets you **send push notifications to your phone or desktop via scripts from any computer**, using simple HTTP PUT +or POST requests. I use it to notify myself when scripts fail, or long-running commands complete. -**ntfy** (pronounce: *notify*) is a simple HTTP-based [pub-sub](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) -notification service. It allows you to **send push notifications to your phone or desktop via scripts from any computer**, -entirely **without signup, cost or setup**. It's [open source](https://github.com/binwiederhier/ntfy) if you want to run your own. +## Step 1: Get the app + + + + +To [receive notifications on your phone](subscribe/phone.md), install the app, either via Google Play or F-Droid. +Once installed, open it and subscribe to a topic of your choosing. Topics don't have to explicitly be created, so just +pick a name and use it later when you [publish a message](publish.md). Note that **topic names are public, so it's wise +to choose something that cannot be guessed easily.** + +For this guide, we'll just use `mytopic` as our topic name: + + + +That's it. After you tap "Subscribe", the app is listening for new messages on that topic. + +## Step 2: Send a message +Now let's [send a message](publish.md) to our topic. It's easy in every language, since we're just using HTTP PUT or POST. The message +is in the request body. Here's an example showing how to publish a simple message using a POST request: + +=== "Command line (curl)" + ``` + curl -d "Backup successful 😀" ntfy.sh/mytopic + ``` + +=== "HTTP" + ``` http + POST /mytopic HTTP/1.1 + Host: ntfy.sh + + Backup successful 😀 + ``` + +=== "JavaScript" + ``` javascript + fetch('https://ntfy.sh/mytopic', { + method: 'POST', // PUT works too + body: 'Backup successful 😀' + }) + ``` + +=== "Go" + ``` go + http.Post("https://ntfy.sh/mytopic", "text/plain", + strings.NewReader("Backup successful 😀")) + ``` + +=== "PHP" + ``` php-inline + file_get_contents('https://ntfy.sh/mytopic', false, stream_context_create([ + 'http' => [ + 'method' => 'POST', // PUT also works + 'header' => 'Content-Type: text/plain', + 'content' => 'Backup successful 😀' + ] + ])); + ``` + +This will create a notification that looks like this: + + + +That's it. You're all set. Go play and read the rest of the docs. I highly recommend reading at least the page on +[publishing messages](publish.md), as well as the detailed page on the [Android app](subscribe/phone.md). + +Here's another video showing the entire process: ### Instant delivery -Instant delivery is allows you to receive messages on your phone instantly, **even when your phone is in doze mode**, i.e. +Instant delivery allows you to receive messages on your phone instantly, **even when your phone is in doze mode**, i.e. when the screen turns off, and you leave it on the desk for a while. This is achieved with a foreground service, which you'll see as a permanent notification that looks like this: diff --git a/docs/subscribe/web.md b/docs/subscribe/web.md index 70313a6d..3af6fccf 100644 --- a/docs/subscribe/web.md +++ b/docs/subscribe/web.md @@ -11,4 +11,10 @@ To learn how to send messages, check out the [publishing page](../publish.md). +To keep receiving desktop notifications from ntfy, you need to keep the website open. What I do, and what I highly recommend, +is to pin the tab so that it's always open, but sort of out of the way: + diff --git a/server/index.gohtml b/server/index.gohtml index 8d2c0226..22700b8a 100644 --- a/server/index.gohtml +++ b/server/index.gohtml @@ -4,7 +4,7 @@ -- There are many ways to use it: Notify yourself when a build finishes, when an rsync is done or a backup fails, - or know when somebody logs into your server. There are many more examples, endless possibilities 😀. -
- Publishing messages can be done via PUT or POST. Topics are created on the fly by subscribing or publishing to them. + Publishing messages can be done via PUT or POST. Topics are created on the fly by subscribing or publishing to them. Because there is no sign-up, the topic is essentially a password, so pick something that's not easily guessable.
@@ -81,8 +78,8 @@
There are more features related to publishing messages: You can set a - notification priority, a title, - and tag messages. + notification priority, a title, + and tag messages. Here's an example using all of them:
@@ -93,6 +90,13 @@
-d "Remote access to $(hostname) detected. Act right away." \
ntfy.sh/mytopic
+ + Here's what that looks like in the Android app: +
++ Here's a video showing the app in action: +
@@ -143,7 +149,7 @@ as well as a plain text stream.- Here's an example for JSON. Note that the connection stays open, so you can retrieve messages as they come in: + Here's an example for JSON. The connection stays open, so you can retrieve messages as they come in:
$ curl -s ntfy.sh/mytopic/json
@@ -152,24 +158,30 @@
{"id":"DGUDShMCsc","time":1635528787,"event":"keepalive","topic":"mytopic"}
...
-
- + Here's a short video demonstrating it in action:
+ -- ntfy has so many more features and you can learn about all of them in the documentation + ntfy has so many more features and you can learn about all of them in the documentation (I tried my very best to make it the best docs ever 😉, not sure if I succeeded, hehe).
+ - - -I love free software, and I'm doing this because it's fun. I have no bad intentions, and I will - never monetize or sell your information. This service will always stay free and open. You can - read more in the FAQs and in the privacy policy. + never monetize or sell your information. This service will always stay + free and open. + You can read more in the FAQs and in the privacy policy.