NTFY on StartOS

Upstream repo: https://github.com/binwiederhier/ntfy Upstream docs: https://docs.ntfy.sh

NTFY is a simple, privacy-first pub/sub push notification service. Send notifications to your phone or desktop from any script, server, or service. Self-hosted on your StartOS server, your notifications stay on your infrastructure - by default, login is required for all access.

---

Quick Start

After installing:

1. Open Actions and run Set Admin Password — the service will not start until this is done.
2. Once the service is running, open the NTFY web UI at your server's address and log in as admin.
3. Subscribe to a topic from the web UI (e.g. alerts).
4. Send your first notification (update commands below using your actual server name and admin password):

   curl -d "Hello from my server" http://ntfy.local/alerts -u admin:yourpassword

5. Try priorities, titles, and tags:

   curl -H "Title: Disk almost full" -H "Priority: high" -H "Tags: warning" \
     -d "Disk usage at 90%" http://ntfy.local/alerts -u admin:yourpassword

6. Read the User Management section below to learn how you can let users register, publish and subscribe to notifications.
7. Read the Mobile Apps and Clients section below to learn how to configure Android and iOS clients to reliably receive messages.

---

Container Runtime

Property	Value
Image	binwiederhier/ntfy:v2.19.2
Architectures	x86_64, aarch64
Entrypoint	ntfy serve

Volumes

Volume	Mount Point	Purpose
main	/data	Persistent data (user database, message cache, attachments, config)

Network Interfaces

Interface	Port	Protocol	Purpose
Web UI	80	HTTP	NTFY web UI and API

Actions

Action	Description
Set Admin Password	Set or change the admin account password. Required before the service will start.
Get Admin Credentials	Show the admin username, password, current server URL, and VAPID public key.
Toggle User Registration	Enable or disable new user self-registration.
Configure Base URL	Choose which address is embedded in attachment links and web push notifications.
Configure Storage	Set attachment size limits, total storage cap, per-user quota, and cache retention.
Configure Web Push	Set the contact email for VAPID web push notifications.
Set Log Level	Change server log verbosity (trace / debug / info / warn / error).
Server Stats	View message count, active visitors, active topics, registered users, attachment storage, config summary, and server version (service must be running).
Server Metrics	View detailed Prometheus metrics: message throughput, subscriber counts, attachment bytes, UnifiedPush and web push delivery stats (service must be running).
Manage Topic Access	Grant or revoke anonymous (unauthenticated) access to a topic.
Provision User Topics	Grant a registered user ownership of their personal topic namespace (username_*).

Dependencies

None.

Backups

The main volume is backed up. This includes:

• User database and credentials (auth.db)
• Message cache (cache.db)
• Attachment files (attachments/)
• VAPID keys and settings (store.json, webpush.db)

Backup size: Attachment files are automatically deleted after the cache retention period (default 12 hours). Backup size at any point is bounded by cache retention × upload rate, not total historical uploads. To reduce backup size, lower the attachment size limits or cache retention via Configure Storage.

On restore: All users, passwords, topic ACLs, attachments, and web push subscriptions are restored. VAPID keys are preserved so existing browser push subscriptions remain valid. If your server URL has changed, update it via Configure Base URL — attachment links in already-delivered notifications will continue to point to the old URL (expected trade-off; cannot be retroactively fixed).

Stale cache: The message cache is included in backups. After restoring from an old backup, the cache may contain messages that have since expired. These age out normally; no data is lost.

Health Checks

Check	Method	Messages
Web Interface	GET /v1/health (HTTP 200)	Ready: "The web interface is ready"

---

User Management

NTFY has a built-in web admin panel accessible after logging in as admin. StartOS actions complement it — they handle operations the REST API does not support (such as granting anonymous topic access) and provide a convenient interface for common configuration tasks.

How topic access works

NTFY's default access policy is deny-all: no topic is accessible to anyone until access is explicitly granted. This means:

• Unauthenticated (anonymous) users can't access any topic by default
• Registered users can log in but still can't access any topic until the admin provisions them
• The admin user has the admin role and bypasses all access controls

Adding a new user

1. Enable user registration if needed via Toggle User Registration (enabled by default)
2. User visits the NTFY web UI and registers an account
3. Admin runs Provision User Topics and enters the new user's username
4. The user can now freely publish and subscribe to any topic prefixed with their username and an underscore — for example, if their username is alice, they can use alice_alerts, alice_reminders, alice_status, and so on — without any further admin involvement

Making a topic public (no login required)

To allow anonymous access to a topic:

1. Admin runs Manage Topic Access
2. Enter the topic name and choose the access level:
   • Read & Write — anyone can publish and subscribe
   • Read Only — anyone can subscribe; login required to publish
   • Write Only — anyone can publish; login required to subscribe
   • Deny — removes previously granted anonymous access
3. Wildcard patterns are supported (e.g. announcements_*)

Access tokens

Users create and manage their own access tokens from the NTFY web UI profile page. Use tokens in scripts and apps instead of storing passwords.

Disabling self-registration

Use Toggle User Registration to prevent new registrations. When disabled new accounts cannot be created until registration is re-enabled. No "Create User" action exists in StartOS.

---

Base URL and Hostnames

NTFY embeds its base-url into attachment download links and web push notification payloads. It is not stored in the database — it is computed dynamically from the current config value.

Default: The mDNS/LAN address (yourserver.local). Works on your home network. Not accessible remotely.

Changing the base URL:

• Use the Configure Base URL action to select a different address (Tor, public domain, or another LAN address).
• Only a service restart is needed — no reinstall, no database migration.
• The only consequence: attachment links in already-delivered notifications will point to the old URL. New notifications immediately use the new URL.

Access method summary:

Access method	Attachment links work?	Notes
LAN (home network)	✓ Always	Best default experience
Tor	✗ If base-url=LAN	Links resolve to .local, unreachable via Tor
StartTunnel / public	✗ If base-url=LAN	Links resolve to .local, unreachable remotely

For remote or Tor access, change the base URL to your StartTunnel domain or Tor address via Configure Base URL.

---

Mobile Apps and Clients

Official NTFY apps: The official Android app (F-Droid build also available) and iOS app work with self-hosted servers. In the app settings, set the server URL to your NTFY address and use your username/password or an access token. Note: reliable background delivery requires additional setup on both platforms — see Push Notification Limitations below.

CLI: The ntfy CLI can publish and subscribe. Example:

ntfy publish -u admin:<pass> http://ntfy.local/mytopic "Hello"

ntfy subscribe -u admin:<pass> http://ntfy.local/mytopic

You can also use an access token (generated from the web UI profile page) instead of a password: --token <token>.

UnifiedPush: NTFY works as a UnifiedPush distributor for Android. Other privacy-focused apps on your device (Mastodon, Element, etc.) can use your self-hosted NTFY as their push relay instead of Google FCM — no extra configuration needed. Note: this is separate from NTFY's own notification delivery, which uses long-polling regardless. The server URL must be reachable from the device (Tor or StartTunnel recommended for use outside the home network).

Web push (browser): VAPID keys are generated automatically on install. Browser push notifications work in the NTFY web UI — subscribe to a topic and notifications arrive even when the tab is closed, as long as the browser is running.

Message replay on reconnect: When a client goes offline and reconnects, NTFY automatically replays missed messages from the cache. Clients catch up automatically. The replay window is the cache retention period (default 12 hours, configurable via Configure Storage).

---

Push Notification Limitations

No Firebase (FCM) / APNs push: This self-hosted package does not use Google Firebase or Apple APNs. The official NTFY Android and iOS apps will not receive background push notifications via Google/Apple infrastructure. Instead, apps maintain a persistent connection to your server (long-polling).

Android — recommended setup:

1. Install the NTFY Android app (or the F-Droid build for a Google-free version).
2. Set the server URL to your NTFY address and log in.
3. Disable battery optimization for the NTFY app — this is critical. Without it, Android will kill the background connection and you will miss notifications. Go to Settings → Apps → NTFY → Battery → Unrestricted (wording varies by device/Android version). With battery exemption granted, real-time delivery is reliable.

iOS — recommended setup: iOS restricts background apps more aggressively than Android. The native NTFY app cannot reliably deliver notifications when the app is backgrounded or the screen is locked. The recommended approach for iOS is to use the NTFY web app via Safari:

1. Open your NTFY server URL in Safari on your iOS device (iOS 16.4 or later required).
2. Tap the Share button → Add to Home Screen.
3. Open the app from your home screen and subscribe to your topics.
4. Enable browser notifications when prompted.

This uses Apple's Web Push infrastructure (VAPID), which delivers notifications reliably even when Safari is closed — no ntfy.sh relay or Apple Developer account needed. Your self-hosted NTFY server already has VAPID keys configured automatically.

Web push works fully: Browser notifications via Web Push (VAPID) are fully supported on desktop browsers and iOS Safari (16.4+) and do not require Firebase or Apple services.

---

Attachment Storage

• Attachments are stored in /data/attachments on the main volume.
• Expiry: Attachment files are deleted automatically when their message expires (controlled by cache retention — the same setting as message cache duration).
• When full: New attachment uploads are rejected with an immediate error. Regular text/link/action notifications are completely unaffected — only new file uploads are blocked.
• No proactive alerts: NTFY does not notify the admin when limits are approaching. Use Server Stats to check current usage and Configure Storage to adjust limits.
• Storage limits (defaults):
  • Per-file limit: 15 MB
  • Total server limit: 5,000 MB
  • Per-visitor quota: 100 MB

---

v2 Roadmap (Not in This Release)

• Create User action: Allow the admin to create new user accounts directly from StartOS without enabling self-registration.
• SMTP email gateway: Forward notifications to email via the StartOS system SMTP gateway.
• Telegram integration: Forward notifications to Telegram via a bot.

---

Contributing

See CONTRIBUTING.md for build instructions and development workflow.

---

Quick Reference for AI Consumers

package_id: ntfy
image: binwiederhier/ntfy:v2.19.2
architectures: [x86_64, aarch64]
volumes:
  main: /data
ports:
  ui: 80
dependencies: none
actions:
  - set-admin-password
  - get-admin-credentials
  - toggle-signup
  - choose-base-url
  - configure-storage
  - configure-web-push
  - set-log-level
  - server-stats
  - server-metrics
  - manage-topic-access
  - provision-user
health_checks:
  - GET /v1/health (HTTP 200)
backup_volumes:
  - main