Self-Hosting ntfy With Docker Compose: Auth, a Reverse Proxy and iPhone Notifications That Arrive
Omar Fenton
November 19, 2026
You want your backup script, your NAS and your uptime monitor to ping your phone, and you would rather not route those alerts through someone else’s server or pay per message. ntfy is the usual answer: a single Go binary that turns an HTTP POST into a push notification. Getting a container running takes a minute. Getting a server that is locked down, sits behind a reverse proxy without breaking long-lived connections, and actually delivers to an iPhone in seconds instead of hours takes a little more care. This guide walks through that whole path with Docker Compose, using the official image and the configuration keys documented at docs.ntfy.sh.
If you are still deciding whether ntfy is the right tool at all, the comparison in ntfy vs Pushover vs Gotify: Which Homelab Alert Path Still Wakes You covers the trade-offs. The rest of this article assumes you have picked ntfy and own a domain such as ntfy.example.com that points at the host.
What the official image expects from you
The project publishes its image as binwiederhier/ntfy on Docker Hub. The container does nothing until you pass it the serve command, and inside the container the server listens on port 80. Two paths matter:
/etc/ntfyholdsserver.yml. The image does not ship one, so the install docs tell you to create it on the host and mount it.- A data directory of your choosing holds the SQLite files: the message cache, the user and access database, and the attachment cache. The docs’ own examples use
/var/cache/ntfyor/var/lib/ntfy. This guide uses/var/lib/ntfy.
Every server.yml option also works as an NTFY_ environment variable, but the file is easier to back up, and the ntfy CLI inside the container reads it too.
A Compose file with persistent cache, auth and attachments
Create a project directory, for example ~/ntfy, with a config folder and a data folder next to the Compose file:
services:
ntfy:
image: binwiederhier/ntfy
container_name: ntfy
command:
- serve
environment:
- TZ=UTC
volumes:
- ./config:/etc/ntfy
- ./data:/var/lib/ntfy
ports:
- 127.0.0.1:2586:80
healthcheck:
test: ["CMD-SHELL", "wget -q --tries=1 http://localhost:80/v1/health -O - | grep -Eo '"healthy"\s*:\s*true' || exit 1"]
interval: 60s
timeout: 10s
retries: 3
start_period: 40s
init: true
restart: unless-stopped
The port is bound to 127.0.0.1, so the only way in is through the reverse proxy below; 2586 matches the upstream port in the ntfy docs’ Caddy example. The health check comes from the official install page, which notes that init: true prevents zombie processes when it runs. If you prefer to run the container as a non-root user, add a user: "1000:1000" line; the install docs then say to make sure the config file, databases and attachment folder are owned by that same UID and GID.
The server.yml keys that lock it down
Save this as config/server.yml:
base-url: "https://ntfy.example.com"
cache-file: "/var/lib/ntfy/cache.db"
cache-duration: "12h"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
behind-proxy: true
attachment-cache-dir: "/var/lib/ntfy/attachments"
upstream-base-url: "https://ntfy.sh"
enable-login: true
What each line does, according to the configuration reference:
base-urlis the public URL of your server. Attachments, the web app and iOS delivery all depend on it being correct, including the scheme.cache-filepoints to the SQLite message cache. Without it, a phone that was offline when an alert fired never sees it.cache-durationsets retention; the default is 12 hours.auth-fileenables authentication and access control. The file is created on first start.auth-default-accessdecides what happens when no access rule matches. The default isread-write, which means anyone who guesses a topic name can read and post.deny-allflips that: nothing works until you grant it.behind-proxytells ntfy to take the visitor’s IP from the forwarded header the proxy sets, instead of seeing every request as coming from the proxy. Rate limits are per visitor, so this matters.attachment-cache-dirturns on file attachments and says where to store them. The default total limit for this folder is 5G.upstream-base-urlis the iPhone fix, covered in its own section below.enable-loginlets users sign in to the web app. Leaveenable-signupoff.
Start it with docker compose up -d and check docker compose logs ntfy. With deny-all, the server now refuses everything, which is where you want to start.

Users, topic permissions and access tokens
The image’s entry point is the ntfy binary, so you can run CLI subcommands inside the running container with docker compose exec. Because server.yml is mounted at the default path, the CLI finds the auth database without extra flags.
Create an admin account for yourself. Admins can read and write every topic, which is what you want on your own phone:
docker compose exec ntfy ntfy user add --role=admin alice
You will be prompted for a password. Next, create a separate account for machines, and give it write-only access to the topics it should post to. The ntfy access syntax is ntfy access USERNAME TOPIC PERMISSION, where permission is read-write (rw), read-only (ro), write-only (wo) or deny. Topic names accept a trailing wildcard:
docker compose exec ntfy ntfy user add publisher
docker compose exec ntfy ntfy access publisher 'homelab*' wo
docker compose exec ntfy ntfy access publisher
The last command lists the grants. A leaked write-only credential can spam your topics but cannot read past alerts, which may contain hostnames and error messages.
Scripts should not carry a password at all. ntfy access tokens start with tk_, are tied to a user, and can expire:
docker compose exec ntfy ntfy token add --expires=365d --label="backup-scripts" publisher
docker compose exec ntfy ntfy token list publisher
The docs allow up to 60 tokens per user, so create one per host or per job. When a machine is retired, remove its token with ntfy token remove and nothing else breaks. If you prefer configuration as code, newer ntfy releases also accept auth-users, auth-access and auth-tokens lists directly in server.yml; note that the docs warn users removed from that list are deleted from the database on restart.
Caddy or nginx without breaking streaming connections
ntfy clients hold connections open for a long time. The Android app, the web app and anything subscribing over JSON streams or WebSockets keeps a request alive and waits for messages. A proxy that buffers responses or times out idle connections after a minute turns instant delivery into delayed delivery.
With Caddy, the minimal setup is short, because reverse_proxy handles WebSockets on its own and Caddy fetches the TLS certificate:
ntfy.example.com {
reverse_proxy 127.0.0.1:2586
}
The ntfy docs add an optional refinement: redirecting plain HTTP to HTTPS only for GET requests, so that curl -d ... ntfy.example.com/topic without a scheme still publishes. That is convenience, not a requirement; the docs themselves describe their Caddy example as likely incomplete.
With nginx, the ntfy docs show the settings that run ntfy.sh. The important parts inside the HTTPS location / block are:
proxy_pass http://127.0.0.1:2586;
proxy_http_version 1.1;
proxy_buffering off;
proxy_request_buffering off;
proxy_redirect off;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_connect_timeout 3m;
proxy_send_timeout 3m;
proxy_read_timeout 3m;
client_max_body_size 0;
Turning off buffering lets messages flow to subscribers as soon as they arrive. The Upgrade and Connection headers allow WebSockets. The three-minute timeouts keep nginx from cutting quiet streams between ntfy’s periodic keepalive messages. client_max_body_size 0 lets attachment uploads stream through instead of hitting nginx’s default 1 MB cap. If you use Nginx Proxy Manager or Traefik instead, look for the equivalent switches: WebSocket support on, buffering off, long read timeouts.
Why iPhones need upstream-base-url pointed at ntfy.sh
On Android, the ntfy app can keep its own connection open. iOS does not allow that kind of background work, so instant notifications have to come through Apple’s push service, and the iOS app is wired to receive them through the central ntfy.sh server. A self-hosted server cannot talk to Apple directly.
That is what upstream-base-url: "https://ntfy.sh" fixes. The configuration docs explain that when it is set, every incoming message makes your server publish a poll request to the upstream. Apple wakes the app, and the app then fetches the real message from your server. According to the docs, the poll request only carries the message ID and a SHA-256 hash of the topic URL, not the message content. Without this setting, the docs warn that delivery to iOS “can take hours, depending on the state of the phone.”
Two practical consequences follow. First, your server still has to be reachable from the phone, because the app pulls the content directly from base-url; a server only reachable on your LAN will not work away from home unless the phone is on a VPN such as Tailscale. Second, the forwarded request counts against ntfy.sh’s rate limits. The docs mention an optional upstream-access-token for cases where you exceed those limits or the upstream requires authentication.
In the iOS app, add your server and your credentials for it in settings, then subscribe using the full server URL.

Android delivery and the persistent notification
The Android app comes in a Google Play build and an F-Droid build. According to the ntfy phone docs, the Play build uses Firebase only for the main ntfy.sh host and never for self-hosted servers. For your own server, the app relies on its own connection, which it keeps alive through a foreground service when instant delivery is turned on for a subscription. That foreground service is why the app shows a permanent notification. The docs say messages can arrive with a significant delay if instant delivery is off; on the F-Droid build, it is always on.
A persistent connection uses some battery, so turn on instant delivery for the topics that matter and leave low-priority ones on regular delivery. If the permanent notification bothers you, the docs point to the “Subscription Service” toggle in that notification’s settings; check the app’s current behavior before relying on it, since hiding the wrong channel can also hide your alerts.
Testing with curl before wiring up anything else
Start with a request that should fail. Without credentials, a deny-all server should reject the publish:
curl -d "Should be rejected" https://ntfy.example.com/homelab-test
Then publish with the token you created. Besides the bearer header, ntfy also accepts the token as a basic-auth password with an empty username (-u :tk_...):
curl -H "Authorization: Bearer tk_yourtokenhere"
-d "Backup done"
https://ntfy.example.com/homelab-backups
Headers set the title, priority and tags. Priority 5 is the highest and is meant for alerts that should interrupt you:
curl -H "Authorization: Bearer tk_yourtokenhere"
-H "Title: nightly restic backup failed"
-H "Priority: 5"
-H "Tags: warning,backup"
-d "Exit code 1 on nas01, see /var/log/restic.log"
https://ntfy.example.com/homelab-backups
Sending from cron jobs, scripts and Uptime Kuma
For shell scripts, keep the token in a file readable only by the user that runs the job, and wrap the call in a small function so every script sends alerts the same way:
#!/bin/sh
NTFY_URL="https://ntfy.example.com/homelab-backups"
NTFY_TOKEN="$(cat /etc/ntfy-token)"
notify() {
curl -fsS -m 10
-H "Authorization: Bearer $NTFY_TOKEN"
-H "Title: $1" -H "Priority: ${3:-3}"
-d "$2" "$NTFY_URL" >/dev/null
}
if restic backup /srv/data; then
notify "Backup OK" "restic finished on $(hostname)" 2
else
notify "Backup FAILED" "restic exited non-zero on $(hostname)" 5
fi
The -m 10 timeout stops a hung call from blocking the job.
Uptime Kuma ships an ntfy notification type. Enter your server URL and topic, choose a priority, and set the authentication method to access token or username and password; the Kuma source includes none, username/password and access token options. Use the publisher token, not your admin login. Then send a test from Kuma and confirm it lands. The failure mode where Kuma looks healthy but nothing reaches your phone is covered in Uptime Kuma + ntfy: When the Dashboard Is Green and Your Phone Stays Dark.
Tools that cannot post to a URL with a header often support Apprise, which speaks ntfy; see Apprise vs ntfy for Homelab Notifications.
What to back up, and where not to run it
Only one file is truly precious: user.db. It holds users, password hashes, access grants and tokens. Losing it means recreating every account and redistributing tokens to every script. The message cache and attachments are short-lived by design, so losing them costs you at most the last few hours of history.
SQLite files should not be copied while the server writes to them. Either stop the container briefly, copy the data and config folders, and start it again, or use the sqlite3 tool’s .backup command on the host to take a consistent copy while it runs. Include server.yml and the Compose file in the same backup so a rebuild is one docker compose up -d away. If you manage users declaratively in server.yml, that file effectively becomes your user backup.
Finally, placement: an alert server on the same machine it reports on goes silent exactly when you need it. A small VPS or separate low-power box avoids that, as laid out in ntfy on the Same Box as Kuma: The Alert Path That Dies With the Outage.
A short checklist before you trust it
- An unauthenticated publish to a random topic is rejected.
- The publisher token can post but cannot subscribe.
- Your phone receives a priority 5 test while locked, on both Wi-Fi and mobile data.
- On iOS, the test arrives in seconds, which confirms
upstream-base-urlis working. - A subscription left open through the proxy for ten minutes still delivers, which confirms buffering and timeouts are right.
- A backup of
user.dbexists somewhere other than the ntfy host.
Once those six pass, you have a notification path you control end to end, with one small dependency on ntfy.sh for iPhones and nothing else.