Getting Started

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 will receive it instantly — no account required. ntfy is ideal for sending server alerts, CI/CD notifications, IoT events, or any lightweight push notification from scripts and applications. Available as an open web service in Eyevinn Open Source Cloud.

Prerequisites

Step 1: Create a PostgreSQL database

ntfy uses a PostgreSQL database to persist messages, user accounts, and subscriptions across restarts. Navigate to the PostgreSQL service in the Eyevinn OSC web console. Click on "Create psql-db" and fill in:

  • Name: a name for your database instance (alphanumeric only)
  • Password: a strong password for the postgres user

Once the instance is running, note the IP and port. The connection URL will be:

postgres://postgres:<password>@<IP>:<PORT>/postgres

Step 2: Store the database URL as a secret

Navigate to the ntfy service in the Eyevinn OSC web console. Go to the tab "Service Secrets" and click "New Secret".

Create a secret named dburl containing the PostgreSQL connection URL from Step 1.

Step 3: Create the ntfy instance

Go to the tab "My ntfy" and click "Create ntfy". Fill in:

  • Name: a name for your instance (alphanumeric only)
  • databaseUrl: {{secrets.dburl}}

Click the instance card when the status is green and "running". Your ntfy server is now live.

Step 4: Publish and receive notifications

ntfy works without any login. Publish a message by sending an HTTP POST to any topic URL:

# Publish a notification to the topic "alerts" on your ntfy instance
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. You can also subscribe using the ntfy mobile app (iOS and Android) or the ntfy CLI.

Usage example

Send notifications from a shell script:

NTFY_URL="https://<instance-url>"
TOPIC="my-alerts"

# Send a plain text notification
curl -s -d "Backup completed successfully" "$NTFY_URL/$TOPIC"

# Send with a title and priority
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 from your application:

// Subscribe to a topic using the EventSource API (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);
};

Using the CLI

# Create a PostgreSQL database first
npx @osaas/cli create birme-osc-postgresql myntfydb \
  -o Password="mypassword"

# Create the ntfy instance
npx @osaas/cli create binwiederhier-ntfy mynotify \
  -o databaseUrl="postgres://postgres:mypassword@<IP>:<PORT>/postgres"

Configuration Options

Option Required Description
databaseUrl Yes PostgreSQL connection string for persistent message and user storage.

Resources