Self-host ntfy on a VPS: push notifications for scripts and CI/CD

Uptime Kuma monitors your services, Beszel monitors your VPS metrics, Backrest manages your backups, and your cron jobs go silent at night — except when they fail. Each has its own notification channel: Slack, email, webhook, Telegram. The result: five different integrations to maintain, five alert formats to read, and no unified view when something breaks at 3 AM. ntfy solves this from the other direction: you host the notification hub, and every tool or script sends its alerts over plain HTTP. A single topic to watch on your phone, zero dependency on a third-party service.

ntfy is a Go binary that runs in a single Docker container. It exposes a simple HTTP interface: PUT or POST to /your-topic publishes a message; any client listening to that topic (via WebSocket, SSE or the mobile app) receives it instantly. Messages are cached in SQLite (/var/lib/ntfy/cache.db) with configurable retention (12 hours by default). In production, ntfy is expected to sit behind an nginx reverse proxy that handles TLS — behind-proxy: true in server.yml tells ntfy to read the real client IP from X-Forwarded-For. All advanced configuration — authentication, SMTP, access control — lives in a single /etc/ntfy/server.yml file mounted as a Docker volume.

By default, ntfy starts with no access control (the docs give auth-default-access as read-write) — anyone who knows the URL can read and write. In production, three layers of protection stack up: first auth-default-access: deny-all locks out all unknown requests; then users created with ntfy user add with bcrypt-hashed passwords stored in user.db; finally access tokens (ntfy token add) tied to a specific user and revocable independently of the password. A compromised token can be revoked without changing the user's password. Per-topic ACLs (ntfy access) provide compartmentalization: the backrest user can only write to backups and never sees server-alerts.

ntfy supports multiple namespaces on the same server through topic naming conventions. Create one user per service or team, grant rights only to that user's topics, and each service believes it has its own dedicated hub. The admin role sees everything; regular user role accounts are scoped to their ACLs. For teams that must be fully isolated (separate billing, separate data), deploy two ntfy containers on two distinct subdomains.

1. HTTP 403 Forbidden on publish or subscribe
Message: {"code":40301,"http":403,"error":"Unauthorized"}
Cause: auth-default-access: deny-all is active and the token is missing or expired. Check: curl -v -H "Authorization: Bearer tk_..." https://ntfy.example.com/my-topic. Regenerate the token with ntfy token add <user> and update your scripts.

2. Notification sent but never received on mobile
On Android, first check that the app is subscribed to your instance and not to the public ntfy.sh server (URL in the app settings). On iOS, the most likely cause is a missing upstream-base-url: "https://ntfy.sh" in server.yml: without this relay, the docs warn that delivery can take hours. Set it, then run through the checklist in the iOS section below. base-url must also be set, but the docs tie it to attachment URLs and email footers, not to push delivery.

3. Wrong links in outbound emails
SMTP emails sent by ntfy contain links back to the notifications. Without base-url in server.yml, the email footer (link back to the notification) is built without the public URL and is unusable externally. Fix: set base-url: https://ntfy.example.com and restart the container.

4. Repeated WebSocket drops in production (reconnects every 30 s)
Cause: nginx keepalive timeout is shorter than ntfy's heartbeat interval (keepalive-interval: "45s" in the docs' example configuration). The proxy closes the WebSocket before ntfy can send its heartbeat. Add to the nginx location block: proxy_read_timeout 60; and proxy_send_timeout 60;. Also verify that proxy_http_version 1.1; and proxy_set_header Upgrade $http_upgrade; are present — without them, WebSocket degrades to SSE long-polling.

5. OOM (Out of Memory) on a high-throughput topic
ntfy buffers recent messages in memory before writing to SQLite. On a topic receiving hundreds of messages per second (e.g., unfiltered real-time logs), the in-memory buffer can exhaust a 512 MB VPS. Immediate fix: reduce cache-duration to 1h or 30m. Structural fix: never use ntfy as a real-time log sink — filter at the script level (| grep -E 'ERROR|WARN') and push only actionable events. For high-throughput deployments, ntfy can use PostgreSQL instead of SQLite for its stores (see the configuration docs).

On iOS an app cannot keep a connection open in the background: the ntfy documentation explains that this restriction makes instant push impossible without a central server. For every message, your self-hosted server therefore forwards a "poll" request to an upstream server, ntfy.sh by default, which takes care of waking the app. The setting is upstream-base-url: "https://ntfy.sh". That request carries only the message ID (X-Poll-ID header) and the SHA-256 hash of the topic URL, never the text: the self-hosted server literally sends "New message", and the app then fetches the real content from your server. Without upstream-base-url, the documentation warns that notifications eventually arrive, but delivery can take hours (20 to 30 minutes if the phone is actively in use). upstream-access-token is optional: the docs only reserve it for when the upstream server's limits are exceeded or when it is protected.

These two issues in the ntfy repository describe the symptom you are chasing: a self-hosted server, an iOS push that does not show, messages that appear only when you refresh the app by hand. Read on 30 October 2026, both are open and neither names a confirmed cause.

#1305 "No push notifications on ios?" (opened in March 2025, labels ios and bug). The reporter gets no banner, neither with ntfy.sh nor with their own instance. Comments say reinstalling the app helped, others that the problem came back months later. A contributor proposes that the app re-subscribes to the Firebase topics at launch and opened a draft PR, stating they could not test it. A maintainer asks the reporter whether the Firebase subscription is the cause, without concluding.

#1844 "No iOS Push notification, also with valid subscription" (opened in July 2026, labels ios, server and bug). The reporter runs ntfy in Docker with NTFY_UPSTREAM_BASE_URL set to https://ntfy.sh and NTFY_UPSTREAM_ACCESS_TOKEN filled in. They say they hit the free limit of 250 messages per day, then took a paid subscription. Their logs show the message published and sent to the relay, and still no push. A contributor answers that 429 errors can lead to an IP ban of up to 4 hours, notes that the reporter's curl test succeeds (so no ban), and that the account showed 48 messages sent out of 2,500. They add that iOS notifications are finicky without anyone knowing exactly why. Reported workaround: switch "Background App Refresh" and "Notifications" off and on again in the iOS settings. The author writes they do not know why this works; the problem came back, then went away with no known cause, and another user confirms the workaround in September 2026. Another report ties a similar case to DNS blocklists.

What you can conclude, and what you cannot. Neither a daily message limit nor a 429 block is established as the cause in these threads: the 429 is ruled out for the reporter's IP, and the 250-message limit is a figure given by the reporter, not by the configuration documentation. The upstream token does not fix the problem there. Treat the list above as checks, not as a guaranteed fix.

Backrest natively supports ntfy as a hook type: configure the topic URL and Bearer token in the Backrest UI, and every completed or failed snapshot automatically generates a push notification with the snapshot name, deduplicated size, and duration. Zero scripting required — the integration is built into the tool.

Uptime Kuma supports ntfy natively in its notification manager. Configuration takes under a minute. Each monitor (HTTP, TCP port, ping, TLS certificate) can have multiple notification channels — combine ntfy for mobile push and ntfy's SMTP for auditability.

Grafana uses generic webhooks. Create a contact point of type webhook, point it at https://ntfy.example.com/grafana, add the Authorization: Bearer tk_... and Content-Type: text/plain headers. Grafana alerts (CPU > 90%, P99 latency, disk > 80%) arrive immediately on your phone with the rule name in the notification title.