Service: Ntfy - EyevinnOSC/community GitHub Wiki

ntfy

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.

What it can do

  • 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.

Creating an instance

ntfy uses a PostgreSQL database for persistence. Create it first and confirm it is running.

  1. Create a PostgreSQL instance (serviceId birme-osc-postgresql, see PostgreSQL) with create-service-instance, with a name and a PostgresPassword. Wait with wait-for-service-ready.
  2. Read the IP and port with describe-service-instance. The connection URL is postgres://postgres:<password>@<IP>:<PORT>/postgres.
  3. Store the full URL as a service secret with create-service-secret (serviceId: "binwiederhier-ntfy", for example name dburl).
  4. Create the ntfy instance with create-service-instance using serviceId: "binwiederhier-ntfy". The instance name must be alphanumeric and at most 20 characters.
{ "name": "mynotify", "databaseUrl": "{{secrets.dburl}}" }
  1. Verify with wait-for-service-ready or get-instance-status, then read the URL with describe-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"

Options

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.

PostgreSQL options (birme-osc-postgresql)

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.

Using the instance

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>/alerts

Subscribe 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);
};

Limitations

  • Storage is limited to 5 GiB per instance.

Resources

⚠️ **GitHub.com Fallback** ⚠️