Emoji reference and such
This commit is contained in:
parent
62f4d9963e
commit
29f2196376
8 changed files with 2049 additions and 29 deletions
|
@ -24,6 +24,9 @@ variable before running the `ntfy` command (e.g. `export NTFY_LISTEN_HTTP=:80`).
|
|||
| Config option | Env variable | Format | Default | Description |
|
||||
|---|---|---|---|---|
|
||||
| `listen-http` | `NTFY_LISTEN_HTTP` | `[host]:port` | `:80` | Listen address for the HTTP web server |
|
||||
| `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. |
|
||||
| `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. |
|
||||
|
@ -67,20 +70,43 @@ firebase-key-file: "/etc/ntfy/ntfy-sh-firebase-adminsdk-ahnce-9f4d6f14b5.json"
|
|||
## Behind a proxy (TLS, etc.)
|
||||
|
||||
!!! warning
|
||||
If you are behind a proxy, you must set the `behind-proxy` flag. Otherwise all visitors are rate limited
|
||||
If you are running ntfy behind a proxy, you must set the `behind-proxy` flag. Otherwise all visitors are rate limited
|
||||
as if they are one.
|
||||
|
||||
**TLS/SSL*: ntfy does not support TLS at this time.
|
||||
|
||||
If you are running ntfy behind a proxy (e.g. nginx, HAproxy or Apache), you should set the `behind-proxy` flag. This will
|
||||
instruct the [rate limiting](#rate-limiting) logic to use the `X-Forwarded-For` header as the primary identifier
|
||||
**Rate limiting:** If you are running ntfy behind a proxy (e.g. nginx, HAproxy or Apache), you should set the `behind-proxy`
|
||||
flag. This will instruct the [rate limiting](#rate-limiting) logic to use the `X-Forwarded-For` header as the primary
|
||||
identifier for a visitor, as opposed to the remote IP address. If the `behing-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.
|
||||
|
||||
## Rate limiting
|
||||
Rate limiting: Allowed GET/PUT/POST requests per second, per visitor:
|
||||
- visitor-request-limit-burst is the initial bucket of requests each visitor has
|
||||
- visitor-request-limit-replenish is the rate at which the bucket is refilled
|
||||
!!! info
|
||||
Be aware that if you are running ntfy behind a proxy, you must set the `behind-proxy` flag.
|
||||
Otherwise all visitors are rate limited as if they are one.
|
||||
|
||||
By default, ntfy runs without authentication, so it is vitally important that we protect the server from abuse or overload.
|
||||
There are various limits and rate limits in place that you can use to configure the server. Let's do the easy ones first:
|
||||
|
||||
* `global-topic-limit` defines the total number of topics before the server rejects new topics. It defaults to 5000.
|
||||
* `visitor-subscription-limit` is the number of subscriptions (open connections) per visitor. This value defaults to 30.
|
||||
|
||||
A **visitor** is identified by its IP address (or the `X-Forwarded-For` header if `behind-proxy` is set). All config
|
||||
options that start with the word `visitor` apply only on a per-visitor basis.
|
||||
|
||||
In addition to the limits above, there is a requests/second limit per visitor for all sensitive GET/PUT/POST requests.
|
||||
This limit uses a [token bucket](https://en.wikipedia.org/wiki/Token_bucket) (using Go's [rate package](https://pkg.go.dev/golang.org/x/time/rate)):
|
||||
|
||||
Each visitor has a bucket of 60 requests they can fire against the server (defined by `visitor-request-limit-burst`).
|
||||
After the 60, new requests will encounter a `429 Too Many Requests` response. The visitor request bucket is refilled at a rate of one
|
||||
request every 10s (defined by `visitor-request-limit-replenish`)
|
||||
|
||||
* `visitor-request-limit-burst` is the initial bucket of requests each visitor has. This defaults to 60.
|
||||
* `visitor-request-limit-replenish` is the rate at which the bucket is refilled (one request per x). Defaults to 10s.
|
||||
|
||||
During normal usage, you shouldn't encounter this limit at all, and even if you burst a few requests shortly (e.g. when you
|
||||
reconnect after a connection drop), it shouldn't have any effect.
|
||||
|
||||
## Command line options
|
||||
```
|
||||
|
|
1831
docs/emojis.md
Normal file
1831
docs/emojis.md
Normal file
File diff suppressed because it is too large
Load diff
|
@ -115,6 +115,60 @@ a [title](#message-title), and [tag messages](#tags-emojis) 🥳 🎉. Here's an
|
|||
<figcaption>Urgent notification with tags and title</figcaption>
|
||||
</figure>
|
||||
|
||||
## Message title
|
||||
The notification title is typically set to the topic short URL (e.g. `ntfy.sh/mytopic`). To override the title,
|
||||
you can set the `X-Title` header (or any of its aliases: `Title`, `ti`, or `t`).
|
||||
|
||||
=== "Command line (curl)"
|
||||
```
|
||||
curl -H "X-Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
|
||||
curl -H "Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
|
||||
curl -H "t: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
|
||||
```
|
||||
|
||||
=== "HTTP"
|
||||
``` http
|
||||
POST /controversial HTTP/1.1
|
||||
Host: ntfy.sh
|
||||
Title: Dogs are better than cats
|
||||
|
||||
Oh my ...
|
||||
```
|
||||
|
||||
=== "JavaScript"
|
||||
``` javascript
|
||||
fetch('https://ntfy.sh/controversial', {
|
||||
method: 'POST',
|
||||
body: 'Oh my ...',
|
||||
headers: { 'Title': 'Dogs are better than cats' }
|
||||
})
|
||||
```
|
||||
|
||||
=== "Go"
|
||||
``` go
|
||||
req, _ := http.NewRequest("POST", "https://ntfy.sh/controversial", strings.NewReader("Oh my ..."))
|
||||
req.Header.Set("Title", "Dogs are better than cats")
|
||||
http.DefaultClient.Do(req)
|
||||
```
|
||||
|
||||
=== "PHP"
|
||||
``` php
|
||||
file_get_contents('https://ntfy.sh/controversial', false, stream_context_create([
|
||||
'http' => [
|
||||
'method' => 'POST',
|
||||
'header' =>
|
||||
"Content-Type: text/plain\r\n" .
|
||||
"Title: Dogs are better than cats",
|
||||
'content' => 'Oh my ...'
|
||||
]
|
||||
]));
|
||||
```
|
||||
|
||||
<figure markdown>
|
||||
![notification with title](../static/img/notification-with-title.png){ width=500 }
|
||||
<figcaption>Detail view of notification with title</figcaption>
|
||||
</figure>
|
||||
|
||||
## Message priority
|
||||
All messages have a priority, which defines how urgently your phone notifies you. You can set custom
|
||||
notification sounds and vibration patterns on your phone to map to these priorities (see [Android config](../subscribe/phone.md)).
|
||||
|
@ -182,26 +236,99 @@ You can set the priority with the header `X-Priority` (or any of its aliases: `P
|
|||
</figure>
|
||||
|
||||
## Tags & emojis 🥳 🎉
|
||||
You can tag messages with emojis (or other relevant strings). If a tag matches a <a href="https://raw.githubusercontent.com/github/gemoji/master/db/emoji.json">known emoji short code</a>,
|
||||
it will be converted to an emoji. If it doesn't match, it will be listed below the notification. This is useful
|
||||
for things like warnings and such (⚠️, ️🚨, or 🚩), but also to simply tag messages otherwise (e.g. which script the
|
||||
message came from, ...).
|
||||
You can tag messages with emojis and other relevant strings:
|
||||
|
||||
You can set tags with the `X-Tags` header (or any of its aliases: `Tags`, or `ta`).
|
||||
Use <a href="https://raw.githubusercontent.com/github/gemoji/master/db/emoji.json">this reference</a>
|
||||
to figure out what tags can be converted to emojis. In the example below, the tag "warning" matches the emoji ⚠️,
|
||||
the tag "ssh-login" doesn't match and will be displayed below the message.
|
||||
* **Emojis**: If a tag matches an [emoji short code](../emojis.md), it'll be converted to an emoji and prepended
|
||||
to title or message.
|
||||
* **Other tags:** If a tag doesn't match, it will be listed below the notification.
|
||||
|
||||
```
|
||||
$ curl -H "Tags: warning,ssh-login" -d "Unauthorized SSH access" ntfy.sh/mytopic
|
||||
{"id":"ZEIwjfHlSS",...,"tags":["warning","ssh-login"],"message":"Unauthorized SSH access"}
|
||||
```
|
||||
This feature is useful for things like warnings (⚠️, ️🚨, or 🚩), but also to simply tag messages otherwise (e.g. script
|
||||
names, hostnames, etc.). Use [the emoji short code list](../emojis.md) to figure out what tags can be converted to emojis.
|
||||
Here's an **excerpt of emojis** I've found very useful in alert messages:
|
||||
|
||||
## Message title
|
||||
The notification title is typically set to the topic short URL (e.g. `ntfy.sh/mytopic`.
|
||||
To override it, you can set the `X-Title` header (or any of its aliases: `Title`, `ti`, or `t`).
|
||||
<table class="remove-md-box"><tr>
|
||||
<td>
|
||||
<table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>
|
||||
<tr><td><code>+1</code></td><td>👍️</td></tr>
|
||||
<tr><td><code>partying_face</code></td><td>🥳</td></tr>
|
||||
<tr><td><code>tada</code></td><td>🎉</td></tr>
|
||||
<tr><td><code>heavy_check_mark</code></td><td>✔️</td></tr>
|
||||
<tr><td><code>loudspeaker</code></td><td>📢</td></tr>
|
||||
<tr><td>...</td><td>...</td></tr>
|
||||
</tbody></table>
|
||||
</td>
|
||||
<td>
|
||||
<table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>
|
||||
<tr><td><code>-1</code></td><td>👎️</td></tr>
|
||||
<tr><td><code>warning</code></td><td>⚠️</td></tr>
|
||||
<tr><td><code>rotating_light</code></td><td>️🚨</td></tr>
|
||||
<tr><td><code>triangular_flag_on_post</code></td><td>🚩</td></tr>
|
||||
<tr><td><code>skull</code></td><td>💀</td></tr>
|
||||
<tr><td>...</td><td>...</td></tr>
|
||||
</tbody></table>
|
||||
</td>
|
||||
<td>
|
||||
<table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>
|
||||
<tr><td><code>facepalm</code></td><td>🤦</td></tr>
|
||||
<tr><td><code>no_entry</code></td><td>⛔</td></tr>
|
||||
<tr><td><code>no_entry_sign</code></td><td>🚫</td></tr>
|
||||
<tr><td><code>cd</code></td><td>💿</td></tr>
|
||||
<tr><td><code>computer</code></td><td>💻</td></tr>
|
||||
<tr><td>...</td><td>...</td></tr>
|
||||
</tbody></table>
|
||||
</td>
|
||||
</tr></table>
|
||||
|
||||
You can set tags with the `X-Tags` header (or any of its aliases: `Tags`, or `ta`). Specify multiple tags by separating
|
||||
them with a comma, e.g. `tag1,tag2,tag3`.
|
||||
|
||||
=== "Command line (curl)"
|
||||
```
|
||||
curl -H "X-Tags: warning,mailsrv13,daily-backup" -d "Backup of mailsrv13 failed" ntfy.sh/backups
|
||||
curl -H "Tags: horse,unicorn" -d "Unicorns are just horses with unique horns" ntfy.sh/backups
|
||||
curl -H ta:dog -d "Dogs are awesome" ntfy.sh/backups
|
||||
```
|
||||
|
||||
=== "HTTP"
|
||||
``` http
|
||||
POST /backups HTTP/1.1
|
||||
Host: ntfy.sh
|
||||
Tags: warning,mailsrv13,daily-backup
|
||||
|
||||
Backup of mailsrv13 failed
|
||||
```
|
||||
|
||||
=== "JavaScript"
|
||||
``` javascript
|
||||
fetch('https://ntfy.sh/backups', {
|
||||
method: 'POST',
|
||||
body: 'Backup of mailsrv13 failed',
|
||||
headers: { 'Tags': 'warning,mailsrv13,daily-backup' }
|
||||
})
|
||||
```
|
||||
|
||||
=== "Go"
|
||||
``` go
|
||||
req, _ := http.NewRequest("POST", "https://ntfy.sh/backups", strings.NewReader("Backup of mailsrv13 failed"))
|
||||
req.Header.Set("Tags", "warning,mailsrv13,daily-backup")
|
||||
http.DefaultClient.Do(req)
|
||||
```
|
||||
|
||||
=== "PHP"
|
||||
``` php
|
||||
file_get_contents('https://ntfy.sh/backups', false, stream_context_create([
|
||||
'http' => [
|
||||
'method' => 'POST',
|
||||
'header' =>
|
||||
"Content-Type: text/plain\r\n" .
|
||||
"Tags: warning,mailsrv13,daily-backup",
|
||||
'content' => 'Backup of mailsrv13 failed'
|
||||
]
|
||||
]));
|
||||
```
|
||||
|
||||
<figure markdown>
|
||||
![priority notification](../static/img/notification-with-tags.png){ width=500 }
|
||||
<figcaption>Detail view of notifications with tags</figcaption>
|
||||
</figure>
|
||||
|
||||
```
|
||||
curl -H "Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/mytopic<
|
||||
```
|
||||
|
||||
|
|
10
docs/static/css/extra.css
vendored
10
docs/static/css/extra.css
vendored
|
@ -2,3 +2,13 @@ figure img {
|
|||
border-radius: 7px;
|
||||
filter: drop-shadow(3px 3px 5px #ccc);
|
||||
}
|
||||
|
||||
.remove-md-box {
|
||||
background: none;
|
||||
border: none;
|
||||
margin: 0 auto;
|
||||
}
|
||||
|
||||
.remove-md-box td {
|
||||
padding: 0 10px
|
||||
}
|
||||
|
|
BIN
docs/static/img/notification-with-tags.png
vendored
Normal file
BIN
docs/static/img/notification-with-tags.png
vendored
Normal file
Binary file not shown.
After Width: | Height: | Size: 155 KiB |
BIN
docs/static/img/notification-with-title.png
vendored
Normal file
BIN
docs/static/img/notification-with-title.png
vendored
Normal file
Binary file not shown.
After Width: | Height: | Size: 161 KiB |
|
@ -79,7 +79,8 @@ nav:
|
|||
- "Polling": subscribe/poll.md
|
||||
- "Other things":
|
||||
- "Examples": examples.md
|
||||
- "FAQs": faq.md
|
||||
- "Emojis 🥳 🎉": emojis.md
|
||||
- "Development": develop.md
|
||||
- "FAQs": faq.md
|
||||
|
||||
|
||||
|
|
|
@ -7,10 +7,11 @@ SCRIPTDIR="$(cd "$(dirname "$0")" && pwd)"
|
|||
ROOTDIR="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
|
||||
if [ -z "$1" ]; then
|
||||
echo "Syntax: $0 FILE.(js|json)"
|
||||
echo "Syntax: $0 FILE.(js|json|md)"
|
||||
echo "Example:"
|
||||
echo " $0 emoji-converted.json"
|
||||
echo " $0 $ROOTDIR/server/static/js/emoji.js"
|
||||
echo " $0 $ROOTDIR/docs/emojis.md"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
|
@ -19,6 +20,30 @@ if [[ "$1" == *.js ]]; then
|
|||
// Original data source: https://github.com/github/gemoji/blob/master/db/emoji.json
|
||||
const rawEmojis = " > "$1"
|
||||
cat "$SCRIPTDIR/emoji.json" | jq -rc 'map({emoji: .emoji,aliases: .aliases})' >> "$1"
|
||||
elif [[ "$1" == *.md ]]; then
|
||||
echo "# Emoji reference
|
||||
|
||||
<!-- This file was generated by scripts/emoji-convert.sh -->
|
||||
|
||||
You can [tag messages](../publish/#tags-emojis) with emojis 🥳 🎉 and other relevant strings. Matching tags are automatically
|
||||
converted to emojis. This is a reference of all supported emojis. To learn more about the feature, please refer to the
|
||||
[tagging and emojis page](../publish/#tags-emojis).
|
||||
|
||||
<table class="remove-md-box"><tr>
|
||||
" > "$1"
|
||||
|
||||
count="$(cat "$SCRIPTDIR/emoji.json" | jq -r '.[] | .emoji' | wc -l)"
|
||||
percolumn=$(($count / 3)) # This will misbehave if the count is not divisible by 3
|
||||
for col in 0 1 2; do
|
||||
from="$(($col * $percolumn + 1))"
|
||||
to="$(($col * $percolumn + 1 + $percolumn))"
|
||||
echo "<td><table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>" >> "$1"
|
||||
cat "$SCRIPTDIR/emoji.json" \
|
||||
| jq -r '.[] | "<tr><td><code>" + .aliases[0] + "</code></td><td>" + .emoji + "</td></tr>"' \
|
||||
| sed -n "${from},${to}p" >> "$1"
|
||||
echo "</tbody></table></td>" >> "$1"
|
||||
done
|
||||
echo "</tr></table>" >> "$1"
|
||||
else
|
||||
cat "$SCRIPTDIR/emoji.json" | jq -rc 'map({emoji: .emoji,aliases: .aliases})' > "$1"
|
||||
fi
|
||||
|
|
Loading…
Reference in a new issue