Almost read to publish
This commit is contained in:
parent
4fcb3891a2
commit
0f495b881a
25 changed files with 229 additions and 70 deletions
|
@ -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. |
|
||||
|
|
|
@ -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 <a href="example.html">live example</a> or just look the source of this page.
|
||||
web application. Check out the <a href="/example.html">live example</a> 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
|
||||
|
|
19
docs/faq.md
19
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 <a href="https://github.com/binwiederhier/ntfy#installation">install instructions</a>
|
||||
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.
|
||||
</p>
|
||||
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 <i>instant delivery</i> feature, the Android app uses no
|
||||
additional battery, since Firebase Cloud Messaging (FCM) is used. If you use your own server, or you use
|
||||
<i>instant delivery</i>, 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 <a href="#battery-usage">additional battery</a>,
|
||||
but delivers notifications instantly.
|
||||
|
||||
|
|
|
@ -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
|
||||
<a href="https://play.google.com/store/apps/details?id=io.heckel.ntfy"><img src="../../static/img/badge-googleplay.png"></a>
|
||||
<a href="https://f-droid.org/en/packages/io.heckel.ntfy/"><img src="../../static/img/badge-fdroid.png"></a>
|
||||
<a href="https://github.com/binwiederhier/ntfy/issues/4"><img src="../../static/img/badge-appstore.png"></a>
|
||||
|
||||
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:
|
||||
|
||||
<figure markdown>
|
||||
{ width=500 }
|
||||
<figcaption>Creating/adding your first topic</figcaption>
|
||||
</figure>
|
||||
|
||||
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:
|
||||
|
||||
<figure markdown>
|
||||
{ width=500 }
|
||||
<figcaption>Android notification</figcaption>
|
||||
</figure>
|
||||
|
||||
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:
|
||||
|
||||
<figure>
|
||||
<video controls muted autoplay loop width="650" src="static/img/overview.mp4"></video>
|
||||
|
|
|
@ -1,7 +1,10 @@
|
|||
# Install your own ntfy server
|
||||
The following steps are only required if you want to **self-host your own ntfy server**. If you just want to
|
||||
[send messages using ntfy.sh](publish.md), you don't need to install anything. Just use `curl`
|
||||
or your favorite HTTP client.
|
||||
**Self-hosting your own ntfy server** is pretty straight forward. Just install the binary, package or Docker image, then
|
||||
configure it and run it. Just like any other software. No fuzz.
|
||||
|
||||
!!! info
|
||||
The following steps are only required if you want to **self-host your own ntfy server**. If you just want to
|
||||
[send messages using ntfy.sh](publish.md), you don't need to install anything.
|
||||
|
||||
## General steps
|
||||
The ntfy server comes as a statically linked binary and is shipped as tarball, deb/rpm packages and as a Docker image.
|
||||
|
@ -129,7 +132,7 @@ The [ntfy image](https://hub.docker.com/r/binwiederhier/ntfy) is available for a
|
|||
straight forward to use.
|
||||
|
||||
The server exposes its web UI and the API on port 80, so you need to expose that in Docker. To use the persistent
|
||||
message cache, you also need to map a volume to `/var/cache/ntfy`. To change other settings, you should map `/etc/ntfy`,
|
||||
[message cache](config.md#message-cache), you also need to map a volume to `/var/cache/ntfy`. To change other settings, you should map `/etc/ntfy`,
|
||||
so you can edit `/etc/ntfy/config.yml`.
|
||||
|
||||
Basic usage (no cache or additional config):
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
# Privacy policy
|
||||
|
||||
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.
|
||||
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, and this service and software will always stay free and open.**
|
||||
|
||||
Neither the server nor the app record any personal information, or share any of the messages and topics with
|
||||
any outside service. All data is exclusively used to make the service function properly. The only external service
|
||||
|
|
9
docs/static/css/extra.css
vendored
9
docs/static/css/extra.css
vendored
|
@ -6,9 +6,14 @@ article {
|
|||
padding-bottom: 50px;
|
||||
}
|
||||
|
||||
figure img {
|
||||
figure iframe, figure img, figure video {
|
||||
filter: drop-shadow(3px 3px 3px #ccc);
|
||||
border-radius: 7px;
|
||||
filter: drop-shadow(3px 3px 5px #ccc);
|
||||
}
|
||||
|
||||
figure video {
|
||||
width: 100%;
|
||||
max-height: 450px;
|
||||
}
|
||||
|
||||
.remove-md-box {
|
||||
|
|
BIN
docs/static/img/getting-started-add.png
vendored
Normal file
BIN
docs/static/img/getting-started-add.png
vendored
Normal file
Binary file not shown.
After Width: | Height: | Size: 90 KiB |
BIN
docs/static/img/web-pin.png
vendored
Normal file
BIN
docs/static/img/web-pin.png
vendored
Normal file
Binary file not shown.
After Width: | Height: | Size: 18 KiB |
|
@ -168,12 +168,12 @@ format of the message. It's very straight forward:
|
|||
| Field | Required | Type | Example | Description |
|
||||
|---|---|---|---|---|
|
||||
| `id` | ✔️ | *string* | `hwQ2YpKdmg` | Randomly chosen message identifier |
|
||||
| `time` | ✔️ | *int* | 1635528741 | Message date time, as Unix time stamp |
|
||||
| `time` | ✔️ | *int* | `1635528741` | Message date time, as Unix time stamp |
|
||||
| `event` | ✔️ | `open`, `keepalive` or `message` | `message` | Message type, typically you'd be only interested in `message` |
|
||||
| `topic` | ✔️ | *string* | `topic1,topic2` | Comma-separated list of topics the message is associated with; only one for all `message` events, but may be a list in `open` events |
|
||||
| `message` | - | *string* | `Some message` | Message body; always present in `message` events |
|
||||
| `title` | - | *string* | `Some title` | Message [title](../publish.md#message-title); if not set defaults to `ntfy.sh/<topic>` |
|
||||
| `tags` | - | *string array* | `["tag1","tag2"]` | List of [tags](../publish.md#tags--emojis--) that may or not map to emojis |
|
||||
| `tags` | - | *string array* | `["tag1","tag2"]` | List of [tags](../publish.md#tags-emojis) that may or not map to emojis |
|
||||
| `priority` | - | *1, 2, 3, 4, or 5* | `4` | Message [priority](../publish.md#message-priority) with 1=min, 3=default and 5=max |
|
||||
|
||||
Here's an example for each message type:
|
||||
|
|
|
@ -51,7 +51,7 @@ the settings (and custom sounds or vibration) for each of the priorities:
|
|||
</figure>
|
||||
|
||||
### 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:
|
||||
|
||||
|
|
|
@ -11,4 +11,10 @@ To learn how to send messages, check out the [publishing page](../publish.md).
|
|||
<a href="../../static/img/web-detail.png"><img src="../../static/img/web-detail.png"/></a>
|
||||
</div>
|
||||
|
||||
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:
|
||||
|
||||
<figure markdown>
|
||||
{ width=500 }
|
||||
<figcaption>Pin web app to move it out of the way</figcaption>
|
||||
</figure>
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue