Service: Ntfy - EyevinnOSC/community GitHub Wiki
ntfy (serviceId binwiederhier-ntfy, pronounced "notify") is an open-source HTTP-based pub/sub notification service. Any client can publish a message to a topic URL and any subscriber listening on that URL receives it instantly, with no account required. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance with up to 5 GiB of storage per instance. License: Apache-2.0.
- Send server alerts, CI/CD notifications, IoT events or other lightweight push notifications from scripts and applications with a plain HTTP request.
- Subscribe to topics in a browser, in the ntfy mobile apps (iOS and Android), with the ntfy CLI, or from code with Server-Sent Events.
- Persist messages, user accounts and subscriptions across restarts in PostgreSQL.
ntfy uses a PostgreSQL database for persistence. Create it first and confirm it is running.
- Create a PostgreSQL instance (serviceId
birme-osc-postgresql, see PostgreSQL) withcreate-service-instance, with a name and aPostgresPassword. Wait withwait-for-service-ready. - Read the IP and port with
describe-service-instance. The connection URL ispostgres://postgres:<password>@<IP>:<PORT>/postgres. - Store the full URL as a service secret with
create-service-secret(serviceId: "binwiederhier-ntfy", for example namedburl). - Create the ntfy instance with
create-service-instanceusingserviceId: "binwiederhier-ntfy". The instance name must be alphanumeric and at most 20 characters.
{ "name": "mynotify", "databaseUrl": "{{secrets.dburl}}" }- Verify with
wait-for-service-readyorget-instance-status, then read the URL withdescribe-service-instance.
OSC CLI example:
# Create a PostgreSQL database first
npx @osaas/cli create birme-osc-postgresql myntfydb \
-o PostgresPassword="mypassword"
# Create the ntfy instance
npx @osaas/cli create binwiederhier-ntfy mynotify \
-o databaseUrl="postgres://postgres:mypassword@<IP>:<PORT>/postgres"| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Letters, digits and underscore only; on OSC at most 20 characters. |
| databaseUrl | Yes | string, sensitive | PostgreSQL connection URL for persistent storage of messages, users and subscriptions. Format postgres://<user>:<password>@<host>:<port>/<db>. Store as a service secret and pass as {{secrets.NAME}}. |
A {{secrets.NAME}} reference must be the whole field value, so the entire URL must be the secret. Overwriting a secret does not restart a running instance.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Instance name, at most 20 characters. |
| PostgresPassword | Yes | string, sensitive | Password for the PostgreSQL superuser. Example: {{secrets.postgrespwd}}. |
| PostgresUser | No | string | Superuser name; postgres if not provided. |
| PostgresDb | No | string | Name of the default database created at first start; the user name if not specified. |
| PostgresInitDbArgs | No | string | Extra arguments passed to initdb when the cluster is initialized (for example encoding or locale). |
| PostgresInitDbSql | No | string | SQL executed during database initialization. |
ntfy works without any login. Publish a message by sending an HTTP POST to any topic URL:
curl -d "Server CPU usage is above 90%" \
https://<instance-url>/alertsSubscribe to a topic in a browser by opening https://<instance-url>/alerts, with the ntfy mobile app, or with the ntfy CLI.
Send notifications from a shell script, optionally with title, priority and tags:
NTFY_URL="https://<instance-url>"
TOPIC="my-alerts"
curl -s -d "Backup completed successfully" "$NTFY_URL/$TOPIC"
curl -s \
-H "Title: Deployment complete" \
-H "Priority: high" \
-H "Tags: white_check_mark" \
-d "v2.3.1 deployed to production" \
"$NTFY_URL/$TOPIC"Receive messages in an application with Server-Sent Events:
const eventSource = new EventSource('https://<instance-url>/my-alerts/sse');
eventSource.onmessage = (event) => {
const msg = JSON.parse(event.data);
console.log('Notification:', msg.message);
};- Storage is limited to 5 GiB per instance.