Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Updated Sep 2026
verified on Ubuntu 26.04 · Sep 2026Self-host ntfy — push notifications to your phone from any script with a single curl — on a small VPS, locked down to deny-all with an admin user, persistent cache and HTTPS via Caddy.
ntfy (pronounced "notify") is a pub/sub notification server.
You publish a message with a plain HTTP PUT or POST to a topic — a URL
like https://ntfy.example.com/backups — and every phone, browser tab or script
subscribed to that topic receives it. There is an Android app, an iOS app and a
web app, but the publishing side needs nothing more than curl:
curl -d "Nightly backup finished" https://ntfy.example.com/backups
That one-liner is the whole appeal. Cron jobs, CI pipelines, backup scripts and monitoring tools can all notify you without an SDK, an account or a third-party cloud in the middle.
The default is wide open, and that is the thing to change. Out of the box,
ntfy lets anyone read and write any topic — the topic name is the password.
That is how the public ntfy.sh service works, and it is fine for throwaway
topics, but on your own server you almost certainly want the opposite: nobody
gets in unless you created them a user. This guide sets
auth-default-access: "deny-all" from the first start and creates one admin
account.
If you are still choosing between push servers, Gotify vs ntfy covers the trade-offs.
ntfy is a single Go binary with SQLite databases next to it, and it is about as light as a self-hosted service gets:
Disk growth comes from two places: the message cache (small — messages are kept
for 12 hours by default) and file attachments, if you enable them (capped by
attachment-total-size-limit, 5 GB by default).
Like any alerting tool, ntfy is most useful on a box that is not the thing it tells you about. If your notifications come from the same VPS that just ran out of disk, you may not hear about it.
This guide assumes Docker Engine and the Compose plugin are installed. If not, work through Docker & Compose on Ubuntu first.
Open SSH plus the ports the reverse proxy needs — ntfy's own port stays on loopback:
sudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw --force enable
sudo ufw status verbose
Paid link — we earn a commission if you shop through it.
The ntfy Docker image does not ship a /etc/ntfy/server.yml; you create one
on the host and mount the directory. Every option has an environment-variable
twin (NTFY_BASE_URL, NTFY_AUTH_DEFAULT_ACCESS, …), but a file is easier to
read, diff and back up, and the ntfy user / ntfy access CLI commands read the
same file — so the auth database path only has to be written down once.
Create the project directory, with one folder per thing that must survive a container restart:
mkdir -p ~/ntfy/etc ~/ntfy/cache ~/ntfy/lib
cd ~/ntfy
Now the config. Replace ntfy.example.com with your own hostname:
cd ~/ntfy
cat > etc/server.yml <<'YAML'
# Public URL of this server — used for attachment links and the web app.
base-url: "https://ntfy.example.com"
# Inside the container ntfy listens on :80; compose maps it to loopback only.
listen-http: ":80"
# Caddy sits in front: take the visitor IP from X-Forwarded-For.
# Without this, every visitor is rate-limited as one.
behind-proxy: true
# Persistent message cache (without it, messages live only in memory).
cache-file: "/var/cache/ntfy/cache.db"
# File attachments (needs base-url to build download links).
attachment-cache-dir: "/var/cache/ntfy/attachments"
# Private instance: nobody can read or write unless granted.
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
# Let users log in to the web app.
enable-login: true
# iOS only: uncomment so iPhones get instant notifications (see below).
# upstream-base-url: "https://ntfy.sh"
YAML
A few notes on those keys:
behind-proxy: true is not optional once Caddy is in front. ntfy
rate-limits per visitor IP; behind a proxy every request appears to come from
127.0.0.1 unless you tell it to read the forwarded header.cache-file keeps messages across restarts, so a phone that was offline
catches up on what it missed (within cache-duration, default 12 hours).auth-file is a SQLite database created automatically on first use.upstream-base-url matters only for the iOS app. Apple restricts background
work, so your server forwards a tiny poll_request (a message ID and a hash of
the topic URL, not the message body) to ntfy.sh, which wakes the phone; the
phone then fetches the real message from your server. Without it, iOS
notifications still arrive, just late. Android and the web app don't need it.This follows the upstream compose example — serve as the command, the health
check against /v1/health, and init: true, which upstream says is needed when
a health check is used — with the port bound to loopback and three bind mounts
for the config, cache and user database:
cd ~/ntfy
cat > docker-compose.yml <<'YAML'
services:
ntfy:
image: binwiederhier/ntfy:latest
container_name: ntfy
command:
- serve
environment:
- TZ=UTC
volumes:
- ./etc:/etc/ntfy
- ./cache:/var/cache/ntfy
- ./lib:/var/lib/ntfy
ports:
# Loopback only — Caddy is the sole route in from outside.
- "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
YAML
docker compose up -d
Wait for it to answer on the loopback port:
for i in $(seq 1 30); do
curl -fsS http://127.0.0.1:2586/v1/health && break
sleep 2
done
docker compose -f ~/ntfy/docker-compose.yml ps
You should see {"healthy":true}.
With deny-all in place, the server currently refuses everyone — including you.
Create an admin; the admin role can read and write every topic, so no extra
access rules are needed for it. ntfy user add normally prompts for the
password, but it also accepts it from the NTFY_PASSWORD environment variable,
which is what makes it scriptable. Generate a strong password and keep it in a
file only you can read:
cd ~/ntfy
[ -f admin-password ] || openssl rand -base64 24 | tr -d '/+=' > admin-password
chmod 600 admin-password
docker compose exec -T -e NTFY_PASSWORD="$(cat admin-password)" ntfy \
ntfy user add --role=admin --ignore-exists admin
docker compose exec -T ntfy ntfy access
--ignore-exists makes the command safe to re-run. The last line prints the
access control list: your admin user and the deny-all default for everyone
else. Print the password once with cat ~/ntfy/admin-password and put it in your
password manager.
Three checks, all against the loopback port: an anonymous publish must be refused, an authenticated publish must succeed, and polling the topic must return the message.
cd ~/ntfy
PASS="$(cat admin-password)"
# Anonymous: expect 403 Forbidden.
code=$(curl -s -o /dev/null -w '%{http_code}' -d "should fail" http://127.0.0.1:2586/test-topic)
echo "anonymous publish: $code"
[ "$code" = "403" ]
# Authenticated publish, with a title.
curl -fsS -u "admin:$PASS" -H "Title: Hello" -d "ntfy is working" \
http://127.0.0.1:2586/test-topic
# Poll the topic instead of holding a connection open.
curl -fsS -u "admin:$PASS" "http://127.0.0.1:2586/test-topic/json?poll=1"
The last command prints the message as a line of JSON. If the anonymous check
prints 200, the deny-all setting didn't load — see Troubleshooting.
Point an A record (and AAAA if you have IPv6) for ntfy.example.com at the
server, then install Caddy by following Automatic HTTPS with
Caddy. The site block is short — Caddy's
reverse_proxy already handles the WebSocket and streaming connections ntfy
subscribers use:
ntfy.example.com {
reverse_proxy 127.0.0.1:2586
}
Reload Caddy and it will fetch a certificate on the first request. Then open
https://ntfy.example.com, log in as admin and subscribe to test-topic in
the web app. From your laptop:
curl -u "admin:YOUR_PASSWORD" -d "Hello over HTTPS" https://ntfy.example.com/test-topic
In the Android or iOS app, subscribe using your server's URL instead of ntfy.sh and sign in with the same user.
ntfy user add backup-script, then ntfy access backup-script backups rw
(run both via docker compose exec -T ntfy … as above).ntfy token add backup-script creates an access token you
can send as a bearer token instead of a password, and revoke on its own.enable-signup defaults to false; keep it that way so
the only accounts are the ones you create.127.0.0.1:2586 binding plus ufw means
the only public entry is Caddy on 443.The state is three directories: etc/ (config), lib/ (users, access rules,
tokens) and cache/ (messages and attachments). Only the first two are hard to
recreate — cached messages expire within hours anyway. Stop the container
briefly so the SQLite files are consistent:
cd ~/ntfy
mkdir -p backups
docker compose stop
sudo tar czf backups/ntfy-$(date +%F).tar.gz etc lib cache docker-compose.yml admin-password
docker compose start
ls -lh backups/
Copy the archive off the box. To restore, stop the stack, extract the archive
over ~/ntfy, and start it again.
cd ~/ntfy
docker compose pull
docker compose up -d
docker compose ps
latest follows the newest release. If you
prefer upgrades to be a deliberate step, pin a version tag such as
binwiederhier/ntfy:v2.37.2 (the newest release on 2026-11-06) in the compose file and bump it after reading the
release notes. Take a backup before any upgrade.
Anonymous publishes still succeed. The config file isn't being read. Check
that it exists at ~/ntfy/etc/server.yml (not a directory of that name) and
that the volume maps ./etc to /etc/ntfy. Upstream notes the image contains
no config file of its own, so a missing mount silently falls back to the open
defaults.
ntfy user add fails, or users vanish on restart. The CLI reads auth-file from /etc/ntfy/server.yml; if that key is
missing, it has nowhere to write. Also make sure /var/lib/ntfy is mounted —
otherwise the database lives inside the container and disappears when it is
recreated.
Everyone gets rate-limited at once. behind-proxy: true is missing, so ntfy
sees every request as coming from Caddy's address.
Attachments fail. Attachments need both attachment-cache-dir and
base-url. A base-url still set to ntfy.example.com produces download links
that point nowhere.
iPhone notifications arrive late. Set upstream-base-url: "https://ntfy.sh"
and restart the container.
For anything else, read the recent logs:
cd ~/ntfy
docker compose logs -f ntfy
You're done when: https://ntfy.example.com loads over a valid certificate and
asks you to log in, an anonymous curl publish gets 403, an authenticated one
reaches your phone within seconds, and docker compose restart doesn't lose
your users.
From there, wire ntfy into the things that should wake you up. Uptime Kuma and Gatus can alert to an ntfy topic, and Healthchecks covers the other half — noticing when a cron job didn't run. For the ranked host picks, see Best VPS for Monitoring & Uptime.
We estimate about 25 minutes of hands-on time for "How to Deploy ntfy on a VPS"; this is an editorial estimate, not a measurement.
The "How to Deploy ntfy on a VPS" guide was verified end-to-end on Ubuntu 26.04 (Sep 2026).