How to self-host ntfy with Docker Compose
Run ntfy on Ubuntu 24.04 or Debian 13 behind TLS, lock topics with users and ACLs, then send alerts from cron and systemd OnFailure units.
Wetin self-hosted ntfy server dey do
Self-hosted ntfy server dey turn HTTP POST into push notification for your phone. You publish with curl, and message go reach the Android app, iOS app, browser tab, or anything wey fit keep HTTP connection open. You no need install client library or run message broker.
ntfy dey use topic take address messages. Topic na name for URL path, like https://ntfy.example.com/alerts, and e dey exist as soon as person publish to am. For default install, anybody wey know that name fit read the topic and write to am. Na why the project's own documentation dey compare topic name to password. That model dey okay for public ntfy.sh service. E no dey okay for server wey dey carry your backup failures, so this guide go turn authentication on before anybody send the first message.
Wetin you need before you start
You need VPS wey dey run Ubuntu 24.04 or Debian 13 with Docker Engine and the Compose plugin, one domain name, and very small RAM. Create DNS (domain name system) A record wey point ntfy.example.com to the server public IP address, then confirm say e resolve before you do anything else.
dig +short ntfy.example.com
sudo ufw allow 80,443/tcp
sudo ufw statusdig suppose print your server IP. Certificate issuance need the hostname to resolve publicly to the server through A or AAAA record. Port 80 remain open because ACME (automatic certificate management environment), wey be the protocol behind Let's Encrypt, dey use am for HTTP challenge. The ntfy container itself no get public port.
ntfy config file write
Docker image no get config file, so you go create one. Every command wey come later for this guide dey read from am. First find the user ID and group ID wey the container go run with.
id -u
id -g
sudo install -d -o "$(id -u)" -g "$(id -g)" /etc/ntfy /var/cache/ntfy /var/lib/ntfy
sudo nano /etc/ntfy/server.ymlbase-url: "https://ntfy.example.com"
listen-http: ":2586"
behind-proxy: true
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
enable-login: true
enable-signup: falseFour of those lines carry the main weight. base-url must be the exact public HTTPS address, because ntfy dey use am for generated attachment links and self-hosted iOS push notifications. listen-http: ":2586" bind to all interfaces inside the container. E fit look careless, but na the correct setting: the container get its own network namespace, so if you bind to 127.0.0.1 there, the port no go reachable from the host and Docker's published port no go connect. auth-default-access: "deny-all" na the whole security posture, because e refuse read and write access for anybody wey no get explicit grant. behind-proxy: true tell ntfy make e take the client address from the X-Forwarded-For header, so rate limits go count real visitors instead of counting the reverse proxy as one very busy client.
enable-login: true let users sign in through the web app or API. enable-signup remain false, because self-service account creation for private server na open access with extra steps.
sudo chown "$(id -u):$(id -g)" /etc/ntfy/server.yml
sudo chmod 600 /etc/ntfy/server.ymlRun ntfy with Docker Compose
Put this inside /opt/ntfy/compose.yaml, replace 1000:1000 with the two numbers id -u and id -g wey print above.
services:
ntfy:
image: binwiederhier/ntfy:v2.36.0
container_name: ntfy
command: serve
user: "1000:1000"
environment:
- TZ=UTC
volumes:
- /etc/ntfy:/etc/ntfy
- /var/cache/ntfy:/var/cache/ntfy
- /var/lib/ntfy:/var/lib/ntfy
ports:
- "127.0.0.1:2586:2586"
restart: unless-stoppedcd /opt/ntfy
sudo docker compose up -d
sudo docker compose logs ntfy
curl -s http://127.0.0.1:2586/v1/healthHealthy server go answer {"healthy":true,"role":"active"}. Two details for that compose file dey deliberate. Dem pin the image to v2.36.0, wey be the current stable release as of November 1, 2026, instead of latest, because with latest the next docker compose pull go download the current image, then a later docker compose up -d go recreate the container with am; pulling alone no change the version wey server dey run. Pin still need update. October 2026 alone get ten releases: v2.29.0 on October 7, v2.30.0 on October 12, v2.31.0 and v2.31.1 on October 16, v2.32.0 on October 18, v2.33.0 and v2.33.1 on October 23, v2.34.0 on October 24, v2.35.0 on October 30, and v2.36.0 on October 31. v2.31.0 fix messages wey dey lost when client reconnect before dem reach message cache, but e reconnects with since=<message ID> dey read every message for the topic from database, and ntfy.sh roll back from am. v2.31.1 fix that load with new index, and v2.34.0 fix revoked or deleted users wey still dey retain some subscriptions. v2.35.0 fix concurrent requests wey dey treat valid credentials as anonymous and Matrix push gateway authorization bypass for SQLite, so move older pins to v2.36.0. Dem publish the port as 127.0.0.1:2586:2586, so container fit reach only from the host's loopback address. If you write 2586:2586 instead, Docker go put im own firewall rules before your own rules, meaning the port go answer from internet even though ufw status talk say the port dey closed. Both habits still apply to the next container wey you add: self-hosted RustDesk relay pins im image tag the same way, but e no fit hide behind loopback because im signal and relay ports must answer from internet.
If curl print Connection refused, read the container log. Permission error for /var/lib/ntfy/user.db mean say user: line no match the owner of those directories, so the process no fit create im own database and e go exit. Docker Compose basics guide for a VPS explain volume ownership and restart policies in more detail.
Put TLS for front with Caddy
Caddy dey request and renew the certificate by itself. Na the shortest way to get working TLS (transport layer security).
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddyReplace wetin dey inside /etc/caddy/Caddyfile with three lines.
ntfy.example.com {
reverse_proxy 127.0.0.1:2586
}sudo systemctl reload caddy
curl -s https://ntfy.example.com/v1/healthThe same {"healthy":true,"role":"active"} for HTTPS show say the whole path dey work. A 502 from Caddy usually mean say ntfy no dey listen: check am with sudo ss -lntp | grep 2586. If ntfy dey listen and the 502 still dey happen, Caddy logs the upstream error wey e encounter, like connection reset. Certificate error usually mean say the DNS record no correct, or certificate validation no fit reach the server for port 80 or 443; inspect sudo journalctl -u caddy -n 50 for the validation error. If you add another service later, na one more hostname block for the same Caddyfile you need. Na so something like Halcyon, one 90s video store front end for your Jellyfin library fit end up for another subdomain for the same box.
If you already dey run nginx, copy the proxy settings wey ntfy documents: proxy_http_version 1.1, proxy_buffering off, proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for, and read and send timeouts of at least three minutes. Subscriber dey hold one HTTP connection open as long as e dey listen. nginx default proxy_read_timeout of 60 seconds only count the time between two reads, and ntfy dey send keepalive message every 45 seconds by default (keepalive-interval), exactly so intermediaries no go close the connection because of inactivity. So quiet subscriber still dey connected even behind stock nginx, and the longer timeouts na extra headroom, no be wetin dey keep am alive. If you increase keepalive-interval, make sure say e remain below your proxy read timeout.
Users create dem and lock topics down
Authentication don turn on, and nobody get access to anything yet. Na so e suppose be. Create one admin account for yourself and one machine account for scripts. These commands dey read /etc/ntfy/server.yml from inside the container, na why the config file be volume mount.
sudo docker compose exec ntfy ntfy user add --role=admin admin
sudo docker compose exec ntfy ntfy user add robot
sudo docker compose exec ntfy ntfy user listEach user add command go ask for password. Admin no dey follow the access list, and e fit read and write every topic. So keep that account for yourself and the phone app. robot na normal user wey no get any access until you grant some.
sudo docker compose exec ntfy ntfy access robot alerts write
sudo docker compose exec ntfy ntfy access robot "alerts_*" write
sudo docker compose exec ntfy ntfy accessACL (access control list) entry na user, topic, and permission. Topic fit be exact name or pattern where * match anything. So alerts_* go cover alerts_backup and alerts_db without separate command for every host. Permission write mean publish only. This way, if person steal token from cron job, e no fit subscribe and read wetin e send back. Special username everyone set wetin unauthenticated visitor fit do. With deny-all as default, you go mostly use am to deliberately open something public, like ntfy access everyone status read. E also accept deny when you want explicit rule wey keep anonymous visitors away from topic.
Scripts suppose carry token, no be your password.
sudo docker compose exec ntfy ntfy token add robotThe command go print token wey start with tk_. Token inherit exactly the access of the user wey e belong to. So this one fit publish to alerts topics and do nothing else. ntfy token list show wetin exist, while ntfy token remove revoke one without touching the user's password.
Send your first message and prove the lock works
Start by checking say the door don shut.
curl -s -o /dev/null -w '%{http_code}\n' -d "hello" https://ntfy.example.com/alertsThat go print 403, and 403 na the correct answer: auth-default-access: "deny-all" no gree anonymous publish. Now send a real one.
curl -H "Authorization: Bearer tk_REPLACE_WITH_YOUR_TOKEN" \
-H "Title: Nightly backup finished" \
-H "Priority: default" \
-H "Tags: white_check_mark" \
-d "42 GB copied in 11 minutes" \
https://ntfy.example.com/alertsThe server go reply with the stored message as JSON. Na so you know say e accept am, instead make e swallow am. Title na the bold first line. Priority dey run from 1 to 5, or by name from min to urgent, and e decide whether the phone go make sound. Tags go turn emoji for the notification when the name match known emoji short code, and dem go remain plain text when e no match.
To watch a topic from terminal, stream am:
curl -s -u admin https://ntfy.example.com/alerts/rawcurl go prompt for the password. Each message go come as one line, and the blank lines wey dey show sometimes na keepalives. Open https://ntfy.example.com for browser and sign in with the same account to get the web app version of the same stream.
Set rate limits so one script no fit flood the server
By default, every visitor get bucket of 60 requests, and the bucket dey refill at one request every 5 seconds. For private server, this limit generous. But script wey dey stuck for retry loop fit use all of am. Add limits to server.yml.
visitor-request-limit-burst: 30
visitor-request-limit-replenish: "10s"
visitor-message-daily-limit: 500sudo docker compose restart ntfyVisitor wey pass the limit go get HTTP 429 instead of message wey deliver. The system dey count the limit per visitor address. Na why behind-proxy: true important well-well: without am, ntfy go see only Caddy address. Every client go count as the same visitor, and one noisy script fit finish the bucket wey your phone and other servers dey share. From v2.36.0, daily counts dey remain after restart inside the user database. Each visitor allowance dey reset for its own 24-hour cycle, instead of for midnight UTC.
Alert from a cron job wey fail
No put the token for command line. ps aux dey show the complete command line of every process wey dey run to every user for the server, so any local account fit read token wey you pass with -H for as long as curl dey run. curl config file go avoid this problem.
sudo install -d -m 700 /etc/ntfy-alert
printf 'header = "Authorization: Bearer tk_REPLACE_WITH_YOUR_TOKEN"\n' | sudo tee /etc/ntfy-alert/curlrc
sudo chmod 600 /etc/ntfy-alert/curlrcNow wrap the job. Save am as /usr/local/bin/backup-with-alert.sh and chmod 750 am.
#!/bin/bash
out=$(/usr/local/bin/backup.sh 2>&1)
code=$?
if [ "$code" -ne 0 ]; then
printf '%s' "$out" | tail -c 1000 | curl -K /etc/ntfy-alert/curlrc \
-H "Title: backup.sh failed with exit $code" \
-H "Priority: high" \
-H "Tags: warning" \
--data-binary @- \
https://ntfy.example.com/alerts
fi
exit "$code"17 3 * * * /usr/local/bin/backup-with-alert.sh >> /var/log/backup-alert.log 2>&1$? dey captured for the line immediately after the command, because the next command wey run go overwrite am. The output dey pass through tail -c 1000 because ntfy get maximum message size, and notification no be log viewer. The closing exit "$code" preserves the original status, so anything else wey dey monitor this job still go see failure. Test everything by pointing the script to /bin/false for one run.
Failure branch wey never execute worse pass no alerting, because e go look like silence mean success. Cron dey give your job environment wey almost empty, plus much shorter PATH than your login shell. So script wey work when you run am by hand fit die before e reach the curl line. The guide on why a cron job no dey run explain those environment traps. Use absolute paths everywhere, and read the log file after the first scheduled run instead of assuming.
Alert when systemd unit fail
Cron dey handle scheduled work. Services wey dey run for long time need OnFailure=, wey systemd dey run whenever unit enter failed state. Create one template unit and reuse am for every service for the box. Save am as /etc/systemd/system/ntfy-unit-failed@.service.
[Unit]
Description=Send an ntfy alert because %i failed
[Service]
Type=oneshot
ExecStart=/usr/local/bin/ntfy-unit-failed %iThen /usr/local/bin/ntfy-unit-failed, mode 750:
#!/bin/bash
unit="$1"
journalctl -u "$unit" -n 15 --no-pager -o cat | tail -c 1000 | curl -K /etc/ntfy-alert/curlrc \
-H "Title: $unit failed on $(hostname -s)" \
-H "Priority: urgent" \
-H "Tags: rotating_light" \
--data-binary @- \
https://ntfy.example.com/alertsAttach am to one service with drop-in, so package upgrade no fit overwrite your edit.
sudo systemctl edit myapp.service[Unit]
OnFailure=ntfy-unit-failed@%n.service%n go expand to the full unit name, so the instantiated unit go become ntfy-unit-failed@myapp.service.service, and %i inside the template go hand myapp.service to the script as e first argument. Na this one make one template fit serve every unit. Prove say e dey work with one unit wey fail on purpose, saved as /etc/systemd/system/ntfy-selftest.service.
[Unit]
Description=Deliberately failing unit
OnFailure=ntfy-unit-failed@%n.service
[Service]
Type=oneshot
ExecStart=/bin/falsesudo systemctl daemon-reload
sudo systemctl start ntfy-selftest.serviceThe start command go exit non-zero and print Job for ntfy-selftest.service failed because the control process exited with error code, and the phone suppose buzz about one second later. Delete the test unit afterwards.
One trap need attention. OnFailure= dey run only when unit reach failed state, and RestartMode=direct dey skip that state during automatic restarts, so e dey skip the failure handler too. With the default RestartMode=normal, automatic restarts go pass through the failed state. StartLimitBurst and StartLimitIntervalSec control when repeated starts go get refused; set dem so crash loop go eventually stop. Timers dey provide cleaner replacement for the cron pattern above, because timer service unit supports the same OnFailure= drop-in, and the guide to systemd services and timers for VPS dey explain how to convert one.
Uptime monitor wire am for the same topic
Uptime Kuma, self-hosted status monitor, get ntfy notification type. Open Settings, then Notifications, then Setup Notification, choose Ntfy, set the server URL to https://ntfy.example.com and the topic to alerts, choose priority, then paste the robot access token. Send the test notification before you save am, because wrong topic name go return error for a write grant wey no cover am.
The honest limit of this setup be say: monitor wey dey run for the same VPS no fit tell you say the VPS dey down, and ntfy no fit deliver the news say ntfy dey down. Run the monitor for another machine, and give am second notification channel, like email, for the monitor wey dey watch ntfy itself. Uptime Kuma Push monitor type cover the other blind spot: your cron job call push URL after successful run, and Kuma alert when those calls stop to arrive. Failure branch go fire only when the job run, so e no talk anything about job wey never start.
Self-hosted ntfy work for Android and iPhone?
For Android, yes, without any condition. Install the app from Google Play or F-Droid, open Settings, set the default server to https://ntfy.example.com, add your account under the user management screen, then subscribe to alerts. Instant delivery keep one foreground service running, so messages go arrive even when the phone dey for doze mode. The permanent notification wey come with am na Android requirement for foreground services, no be bug. The F-Droid build no get Firebase code at all, so every subscription dey use instant delivery. ntfy fit also act as UnifiedPush distributor, wey be open replacement for Google's push service, so other apps wey support UnifiedPush fit deliver through your server too.
For the official iOS app, e work with one dependency wey you no fit remove. iOS dey suspend app wey enter background, and the background modes wey Apple allow — playing audio, receiving location updates, processing scheduled tasks — no allow app to sit down dey wait for message from your server. So prompt wake-up must come through APNs (Apple push notification service). Only provider wey get credentials authorized for the app fit send message go am, so your server no get way to reach the official app directly. ntfy solve this with relay: your server sends a poll_request wey hold the message ID go ntfy.sh, ntfy.sh forwards am through Firebase and APNs to wake the app, then the app fetches the message body from your server.
upstream-base-url: "https://ntfy.sh"Make you understand wetin this cost. The message content remain for your box, but the fact say message arrive, plus the message ID, pass through infrastructure wey you no run. Without this setting, notifications on iPhone from self-hosted server still go arrive eventually, but ntfy docs warn say delay fit reach hours, because nothing dey wake the app promptly. To use native iOS app without ntfy.sh relay, build and ship the app yourself with your own Apple developer account and your own APNs keys. This means annual fee and rebuild for every update. Another option na ntfy's PWA for iOS 16.4 or later: add am to the home screen and configure Web Push for your server. This one avoid ntfy.sh relay, but e still use the browser's push infrastructure. If the relay no acceptable for your use, keep alerting for Android or desktop web app.
Backups, upgrades and pinning the image
Two paths no fit regenerate: /etc/ntfy/server.yml and /var/lib/ntfy/user.db. The second one hold every user, password hash, ACL entry, and token, so handle am like private key.
sudo tar czf ntfy-backup.tgz -C / etc/ntfy var/lib/ntfy
sudo chmod 600 ntfy-backup.tgzCopy that file comot from the server. cache.db hold recent messages, 12 hours of dem with the cache-duration above, plus any message wey schedule for later delivery. E go remain until 12 hours after dem deliver am. Unless you schedule messages ahead, losing am no cost anything wey worth protecting. Upgrade mean say you edit the tag for compose file, pull the image, and recreate the container.
sudo docker compose pull
sudo docker compose up -d
curl -s https://ntfy.example.com/v1/healthRead the release notes first. The SQLite databases dey migrate when dem start, so rollback to older tag after schema change no safe. For example, v2.31.1 move message cache to schema version 17, and the upgrade notes say downgrade to v2.31.0 or earlier need you set that version back to 16 by hand. Upgrade to v2.36.0 go reset everybody's existing daily counts once. Keep the backup wey you just make until the new version don run for one day. The notes also flag behaviour changes. From v2.31.0 onward, client wey reconnect with since=<message ID> go also receive messages wey publish for the same second, so e fit see duplicate. The ntfy apps and web app dey drop duplicates by message ID, but your own script wey replay topic must do the same. Every service for the box get im own short list of paths wey no fit regenerate, and comparison of PhotoPrism and Immich work out that list and the backup commands wey go with am for photo library on the same kind VPS.
Gotify and Apprise
Gotify na the smaller option: na one binary with web UI and Android app, and e dey arrange messages by application. This one good for private box wey Android na the only target. Apprise na Python library and command line tool. E get separate Apprise API server wey you fit use, and e fit send one message go more than hundred services, including ntfy. This one good for script wey need reach different places at the same time. ntfy na the one wey give you server, HTTP API, and apps for both mobile platforms. Na why e be the usual answer for alerting from rented server.
FAQ
Why ntfy server dey return 403 when I publish?
When auth-default-access: "deny-all" dey inside server.yml, anonymous publish no dey allowed, and na so e suppose be. Send credentials with -u user:pass or -H "Authorization: Bearer tk_...". If you already dey send token but you still get 403, check whether the user get ACL entry wey allow writes to the topic: if no matching entry dey, read-only or deny go refuse the publish. For v2.34.0, concurrent requests from the same IP fit also make valid credentials look like anonymous credentials; v2.35.0 fix this bug, so upgrade before you treat intermittent 403 as proof of ACL problem. Run ntfy access to print the complete list. Remember say write grant no allow subscribing, so account wey fit publish well still go get refused when e try read the same topic.
Notifications dey work for iPhone with self-hosted ntfy server?
Dem dey work through relay when you use the official iOS app. For suspended iPhone app to wake up quickly, the request must pass through APNs (Apple push notification service). Sending to the official app also requires the publisher's push credentials, so ntfy forwards poll_request wey contain the message ID to ntfy.sh, and ntfy.sh relays am to the device. Set upstream-base-url: "https://ntfy.sh" inside server.yml, then restart the container. The message body itself still dey fetched from your server. Without that setting, iOS notifications still go arrive eventually, but ntfy docs warn say the delay fit reach hours. The PWA give another option for iOS 16.4 or later when Web Push dey configured for your server.
Why my cron job ntfy alert never arrive?
Run the curl line by itself first to confirm say the token and topic correct. If e work by hand but e no work from cron, the problem dey before the alert: cron dey run jobs with minimal environment and short PATH, so script wey call command by bare name fit stop before e reach the curl line. Use absolute paths, redirect the job output go log file, then read that file after the next run. 429 response instead of delivery mean say limit refuse the request. Usually, the script dey retry too fast. But visitor wey don use up daily quota, like the message limit wey you set above, go also get refused the same way even for one request.
I suppose expose ntfy for public internet?
Phone apps need reach am through mobile networks, so public HTTPS endpoint with auth-default-access: "deny-all" and per-topic ACLs na the normal setup. E safe as long as no topic readable by everyone. VPN-only instance make sense when every subscriber na machine wey you control. But e no suit phones well, because app go receive alerts only while the tunnel dey up. Alerts go queue until the phone reconnect.